0
# Build Optimizations
1

2
Vue I18n build selection, tree-shaking, and performance optimizations including runtime-only builds and message compiler optimization.
3

4
## Capabilities
5

6
### Automatic Build Selection
7

8
Automatic selection of appropriate Vue I18n builds based on environment and configuration.
9

10
```typescript { .api }
11
/**
12
 * Vue I18n build selection strategy
13
 */
14
interface BuildSelection {
15
  /**
16
   * Development builds include full message compiler
17
   * Production builds use runtime-only for smaller size
18
   */
19
  development: 'vue-i18n.esm-bundler.js';
20
  production: 'vue-i18n.runtime.esm-bundler.js';
21
  
22
  /**
23
   * Alternative module support
24
   */
25
  petite: {
26
    development: 'petite-vue-i18n.esm-bundler.js';
27
    production: 'petite-vue-i18n.runtime.esm-bundler.js';
28
  };
29
}
30
```
31

32
### Runtime-Only Optimization
33

34
Configure runtime-only builds for production optimization.
35

36
```typescript { .api }
37
/**
38
 * Runtime-only build configuration
39
 */
40
interface RuntimeOnlyOptions {
41
  /**
42
   * Use Vue I18n runtime-only build in production
43
   * Excludes message compiler from final bundle
44
   * @default true
45
   */
46
  runtimeOnly?: boolean;
47
}
48
```
49

50
**Configuration Example:**
51

52
```typescript
53
VueI18nPlugin({
54
  runtimeOnly: true  // Automatic in production, full build in development
55
});
56

57
// Results in bundler alias configuration:
58
// Production: vue-i18n → vue-i18n.runtime.esm-bundler.js
59
// Development: vue-i18n → vue-i18n.esm-bundler.js
60
```
61

62
### Composition API Optimization
63

64
Tree-shake legacy Options API for smaller bundles.
65

66
```typescript { .api }
67
/**
68
 * Composition API optimization
69
 */
70
interface CompositionAPIOptions {
71
  /**
72
   * Tree-shake legacy Options API, use Composition API only
73
   * Removes $t, $tc, $te methods from Vue instances
74
   * @default true
75
   */
76
  compositionOnly?: boolean;
77
}
78
```
79

80
**Impact Example:**
81

82
```typescript
83
// With compositionOnly: true (default)
84
// ✅ Available: useI18n(), useScope(), etc.
85
// ❌ Removed: this.$t, this.$tc, this.$te, etc.
86

87
// With compositionOnly: false  
88
// ✅ Available: Both Composition and Options API
89
// ⚠️ Larger bundle size
90
```
91

92
### Full Install Control
93

94
Control which Vue I18n features are included in the bundle.
95

96
```typescript { .api }
97
/**
98
 * Full install feature control
99
 */
100
interface FullInstallOptions {
101
  /**
102
   * Install full Vue I18n feature set including built-in components
103
   * When false, excludes i18n-t, i18n-n, i18n-d components and v-t directive
104
   * @default true
105
   */
106
  fullInstall?: boolean;
107
}
108
```
109

110
**Feature Impact:**
111

112
```typescript
113
// With fullInstall: true (default)
114
// ✅ Available: <i18n-t>, <i18n-n>, <i18n-d> components
115
// ✅ Available: v-t directive
116
// ✅ Available: All utility functions
117

118
// With fullInstall: false
119
// ❌ Components and directive tree-shaken
120
// ✅ Available: Core i18n functions only
121
// ⚠️ Smaller bundle size
122
```
123

124
### Message Compiler Tree-shaking
125

126
Remove message compiler from production bundles.
127

128
```typescript { .api }
129
/**
130
 * Message compiler optimization
131
 */
132
interface MessageCompilerOptions {
133
  /**
134
   * Tree-shake message compiler from bundle
135
   * Requires pre-compiled messages (no runtime compilation)
136
   * @default false
137
   */
138
  dropMessageCompiler?: boolean;
139
}
140
```
141

142
**Usage Requirements:**
143

144
```typescript
145
VueI18nPlugin({
146
  dropMessageCompiler: true,
147
  // Must pre-compile all messages
148
  include: ['./locales/**']
149
});
150

151
// ⚠️ Warning: All messages must be pre-compiled
152
// ❌ Runtime message compilation will fail
153
// ✅ Significant bundle size reduction
154
```
155

156
### SSR Optimization
157

158
Server-side rendering optimizations.
159

160
```typescript { .api }
161
/**
162
 * SSR build configuration
163
 */
164
interface SSROptions {
165
  /**
166
   * Enable SSR-specific Vue I18n bundle
167
   * Includes server-side optimizations
168
   * @default false
169
   */
170
  ssr?: boolean;
171
}
172
```
173

174
**SSR Configuration:**
175

176
```typescript
177
// For SSR applications
178
VueI18nPlugin({
179
  ssr: true,
180
  optimizeTranslationDirective: true  // Required for v-t directive in SSR
181
});
182
```
183

184
### Translation Directive Optimization
185

186
Optimize `v-t` directive for better performance.
187

188
```typescript { .api }
189
/**
190
 * Translation directive optimization
191
 */
192
interface DirectiveOptimizationOptions {
193
  /**
194
   * Optimize v-t directive transformation
195
   * Converts v-t to function calls at compile time
196
   * Required for SSR applications using v-t
197
   * @default false
198
   */
199
  optimizeTranslationDirective?: boolean | string | string[];
200
}
201
```
202

203
**Directive Optimization Examples:**
204

205
```typescript
206
// Basic optimization
207
VueI18nPlugin({
208
  optimizeTranslationDirective: true
209
});
210

211
// Custom translation function signatures
212
VueI18nPlugin({
213
  optimizeTranslationDirective: ['$t', 'translate', 'getMessage']
214
});
215
```
216

217
```vue
218
<!-- Before optimization -->
219
<p v-t="'message.key'"></p>
220
<span v-t="{ path: 'user.name', args: { name: 'John' } }"></span>
221

222
<!-- After optimization (compile-time transformation) -->
223
<p>{{ $t('message.key') }}</p>
224
<span>{{ $t('user.name', { name: 'John' }) }}</span>
225
```
226

227
### Module Type Selection
228

229
Choose between Vue I18n variants for different use cases.
230

231
```typescript { .api }
232
/**
233
 * Module type selection
234
 */
235
interface ModuleTypeOptions {
236
  /**
237
   * Target Vue I18n module variant
238
   * @default 'vue-i18n'
239
   */
240
  module?: VueI18nModule;
241
}
242

243
type VueI18nModule = 'vue-i18n' | 'petite-vue-i18n';
244
```
245

246
**Module Comparison:**
247

248
```typescript
249
// vue-i18n (default) - Full-featured
250
VueI18nPlugin({
251
  module: 'vue-i18n'
252
  // ✅ All features available
253
  // ✅ Complete API surface
254
  // ⚠️ Larger bundle size
255
});
256

257
// petite-vue-i18n - Lightweight
258
VueI18nPlugin({
259
  module: 'petite-vue-i18n'
260
  // ✅ Core i18n functionality
261
  // ❌ Reduced feature set
262
  // ✅ Smaller bundle size
263
});
264
```
265

266
### String Formatting Optimization
267

268
Optimize non-string value handling.
269

270
```typescript { .api }
271
/**
272
 * String formatting optimization
273
 */
274
interface StringFormattingOptions {
275
  /**
276
   * Force stringify numbers, booleans, and null values
277
   * Converts them to message functions returning strings
278
   * @default false
279
   */
280
  forceStringify?: boolean;
281
}
282
```
283

284
**Stringify Example:**
285

286
```json
287
// Original locale data
288
{
289
  "count": 42,
290
  "enabled": true,
291
  "value": null
292
}
293
```
294

295
```typescript
296
// With forceStringify: false (default)
297
const messages = {
298
  count: 42,           // number
299
  enabled: true,       // boolean  
300
  value: null         // null
301
};
302

303
// With forceStringify: true
304
const messages = {
305
  count: () => "42",      // function returning string
306
  enabled: () => "true",  // function returning string
307
  value: () => "null"     // function returning string
308
};
309
```
310

311
## Performance Impact
312

313
### Bundle Size Comparison
314

315
```typescript
316
/**
317
 * Typical bundle size impact of optimizations
318
 */
319
interface BundleSizeImpact {
320
  baseline: '~100KB';           // Full Vue I18n with all features
321
  runtimeOnly: '~75KB';         // -25% (no message compiler)
322
  compositionOnly: '~85KB';     // -15% (no Options API)
323
  fullInstall_false: '~80KB';   // -20% (no built-in components)
324
  dropMessageCompiler: '~60KB'; // -40% (requires pre-compilation)
325
  petiteVueI18n: '~40KB';       // -60% (lightweight variant)
326
  
327
  // Combined optimizations
328
  aggressive: '~30KB';          // All optimizations enabled
329
}
330
```
331

332
### Runtime Performance
333

334
```typescript
335
/**
336
 * Runtime performance optimizations
337
 */
338
interface PerformanceOptimizations {
339
  preCompiledMessages: {
340
    impact: 'Significant';
341
    description: 'Messages compiled to functions at build time';
342
    benefit: 'No runtime parsing or compilation overhead';
343
  };
344
  
345
  treeShaking: {
346
    impact: 'Moderate';
347
    description: 'Unused APIs removed from bundle';
348
    benefit: 'Faster JavaScript parsing and execution';
349
  };
350
  
351
  directiveOptimization: {
352
    impact: 'Moderate';
353
    description: 'v-t directive compiled to function calls';
354
    benefit: 'Reduced runtime directive processing';
355
  };
356
}
357
```
358

359
## Complete Optimization Examples
360

361
### Production Optimized Configuration
362

363
```typescript
364
// Maximum optimization for production
365
VueI18nPlugin({
366
  // Build optimizations
367
  runtimeOnly: true,
368
  compositionOnly: true,
369
  fullInstall: false,
370
  dropMessageCompiler: true,
371
  
372
  // Performance optimizations
373
  forceStringify: true,
374
  optimizeTranslationDirective: true,
375
  
376
  // Resource optimization
377
  include: ['./locales/**'],
378
  onlyLocales: ['en', 'fr', 'de'],
379
  
380
  // Security
381
  strictMessage: true,
382
  escapeHtml: true
383
});
384
```
385

386
### Development Friendly Configuration
387

388
```typescript
389
// Development configuration with debugging support
390
VueI18nPlugin({
391
  // Keep full builds for development
392
  runtimeOnly: false,
393
  compositionOnly: false,
394
  fullInstall: true,
395
  dropMessageCompiler: false,
396
  
397
  // Flexible during development
398
  strictMessage: false,
399
  allowDynamic: true,
400
  
401
  // Resource processing
402
  include: ['./locales/**', './src/**/*.vue'],
403
  defaultSFCLang: 'yaml'  // More readable in development
404
});
405
```
406

407
### SSR Optimized Configuration
408

409
```typescript
410
// Server-side rendering optimization
411
VueI18nPlugin({
412
  // SSR requirements
413
  ssr: true,
414
  optimizeTranslationDirective: true,  // Required for v-t in SSR
415
  
416
  // Production optimizations
417
  runtimeOnly: true,
418
  compositionOnly: true,
419
  dropMessageCompiler: true,
420
  
421
  // Resource handling
422
  include: ['./locales/**'],
423
  globalSFCScope: false  // Better for SSR hydration
424
});
425
```
426

427
### Micro-frontend Configuration
428

429
```typescript
430
// Optimized for micro-frontend architecture
431
VueI18nPlugin({
432
  // Minimal footprint
433
  module: 'petite-vue-i18n',
434
  fullInstall: false,
435
  compositionOnly: true,
436
  dropMessageCompiler: true,
437
  
438
  // Shared resources only
439
  onlyLocales: ['en'],
440
  include: ['./shared-locales/**'],
441
  
442
  // No global scope to avoid conflicts
443
  globalSFCScope: false
444
});
445
```