0
# @intlify/unplugin-vue-i18n
1

2
@intlify/unplugin-vue-i18n is an unplugin that provides comprehensive Vue I18n integration capabilities for various bundlers including Vite, Webpack, and Nuxt. It enables i18n resource pre-compilation to optimize Vue I18n performance by transforming locale messages into JavaScript functions or AST objects during build time.
3

4
## Package Information
5

6
- **Package Name**: @intlify/unplugin-vue-i18n
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @intlify/unplugin-vue-i18n`
10

11
## Core Imports
12

13
```typescript
14
import VueI18nPlugin from "@intlify/unplugin-vue-i18n/vite";
15
import { PluginOptions, SFCLangFormat, VueI18nModule } from "@intlify/unplugin-vue-i18n";
16
```
17

18
For Webpack:
19
```typescript
20
import VueI18nPlugin from "@intlify/unplugin-vue-i18n/webpack";
21
```
22

23
For direct unplugin usage:
24
```typescript
25
import { unplugin, unpluginFactory } from "@intlify/unplugin-vue-i18n";
26
```
27

28
For types only:
29
```typescript
30
import type { PluginOptions, SFCLangFormat } from "@intlify/unplugin-vue-i18n/types";
31
```
32

33
## Basic Usage
34

35
### Vite Configuration
36

37
```typescript
38
// vite.config.ts
39
import { defineConfig } from 'vite';
40
import vue from '@vitejs/plugin-vue';
41
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite';
42
import path from 'path';
43

44
export default defineConfig({
45
  plugins: [
46
    vue(),
47
    VueI18nPlugin({
48
      include: [path.resolve(__dirname, './src/locales/**')],
49
      runtimeOnly: true,
50
      compositionOnly: true
51
    })
52
  ]
53
});
54
```
55

56
### Webpack Configuration
57

58
```typescript
59
// webpack.config.js
60
const VueI18nPlugin = require('@intlify/unplugin-vue-i18n/webpack');
61

62
module.exports = {
63
  plugins: [
64
    VueI18nPlugin({
65
      include: [path.resolve(__dirname, './src/locales/**')],
66
      runtimeOnly: true,
67
      compositionOnly: true
68
    })
69
  ]
70
};
71
```
72

73
### Using Pre-compiled Messages
74

75
```typescript
76
// Import all locale messages automatically
77
import messages from '@intlify/unplugin-vue-i18n/messages';
78
import { createI18n } from 'vue-i18n';
79

80
const i18n = createI18n({
81
  locale: 'en',
82
  messages
83
});
84
```
85

86
## Architecture
87

88
@intlify/unplugin-vue-i18n is built around several key components:
89

90
- **Unplugin Core**: Universal plugin system supporting Vite, Webpack, and other bundlers
91
- **Resource Plugin**: Pre-compiles i18n resources (JSON, YAML, JS, TS) at build time
92
- **SFC Integration**: Processes `<i18n>` custom blocks in Vue Single File Components
93
- **Virtual Module System**: Provides `@intlify/unplugin-vue-i18n/messages` for bulk message imports
94
- **Directive Optimization**: Optimizes `v-t` translation directives for better performance
95
- **Vue I18n Build Selection**: Automatically selects appropriate Vue I18n builds (runtime vs full)
96

97
## Capabilities
98

99
### Plugin Configuration
100

101
Core plugin configuration and initialization for different bundlers. Supports universal unplugin architecture with bundler-specific optimizations.
102

103
```typescript { .api }
104
/**
105
 * Main unplugin factory function
106
 * @param options - Plugin configuration options
107
 * @param meta - Unplugin context metadata
108
 * @returns Array of unplugin options
109
 */
110
function unpluginFactory(
111
  options?: PluginOptions,
112
  meta: UnpluginContextMeta
113
): UnpluginOptions[];
114

115
/**
116
 * Main unplugin instance for universal bundler support
117
 */
118
const unplugin: UnpluginInstance<PluginOptions | undefined, boolean>;
119

120
/**
121
 * Plugin configuration options interface
122
 */
123
interface PluginOptions {
124
  include?: string | string[];
125
  onlyLocales?: string | string[];
126
  allowDynamic?: boolean;
127
  module?: VueI18nModule;
128
  dropMessageCompiler?: boolean;
129
  runtimeOnly?: boolean;
130
  compositionOnly?: boolean;
131
  ssr?: boolean;
132
  fullInstall?: boolean;
133
  forceStringify?: boolean;
134
  defaultSFCLang?: SFCLangFormat;
135
  globalSFCScope?: boolean;
136
  strictMessage?: boolean;
137
  escapeHtml?: boolean;
138
  optimizeTranslationDirective?: boolean | string | string[];
139
  transformI18nBlock?: (src: string | Buffer) => string;
140
}
141

142
type SFCLangFormat = 'json' | 'json5' | 'yml' | 'yaml';
143
type VueI18nModule = 'vue-i18n' | 'petite-vue-i18n';
144
```
145

146
[Plugin Configuration](./plugin-configuration.md)
147

148
### Resource Processing
149

150
Pre-compilation and transformation of i18n resource files including JSON, YAML, JavaScript, and TypeScript locale files. Handles static bundling and virtual module generation.
151

152
```typescript { .api }
153
// Virtual import for all messages
154
declare module '@intlify/unplugin-vue-i18n/messages' {
155
  import type { I18nOptions } from 'vue-i18n';
156
  const messages: I18nOptions['messages'];
157
  export default messages;
158
}
159
```
160

161
[Resource Processing](./resource-processing.md)
162

163
### SFC Integration
164

165
Processing of Vue Single File Component `<i18n>` custom blocks with support for multiple formats, scoping, and import functionality.
166

167
```typescript { .api }
168
interface VueQuery {
169
  vue?: boolean;
170
  src?: boolean;
171
  global?: boolean;
172
  type?: 'script' | 'template' | 'style' | 'custom' | 'i18n';
173
  blockType?: string;
174
  index?: number;
175
  locale?: string;
176
  lang?: string;
177
  raw?: boolean;
178
  issuerPath?: string;
179
}
180

181
function parseVueRequest(id: string): {
182
  filename: string;
183
  query: VueQuery;
184
};
185
```
186

187
[SFC Integration](./sfc-integration.md)
188

189
### Build Optimizations
190

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

193
```typescript { .api }
194
interface BuildOptimizations {
195
  runtimeOnly: boolean;
196
  compositionOnly: boolean;
197
  fullInstall: boolean;
198
  dropMessageCompiler: boolean;
199
  ssr: boolean;
200
}
201
```
202

203
[Build Optimizations](./build-optimizations.md)
204

205
### Core Plugin Functions
206

207
Internal plugin functions and utilities for advanced usage and customization.
208

209
```typescript { .api }
210
/**
211
 * Resolve and normalize plugin options
212
 * @param options - Raw plugin options
213
 * @returns Resolved options with defaults applied
214
 */
215
function resolveOptions(options: PluginOptions): ResolvedOptions;
216

217
/**
218
 * Resource processing plugin instance
219
 * @param options - Resolved plugin options
220
 * @param meta - Unplugin context metadata
221
 * @returns Unplugin options for resource processing
222
 */
223
function resourcePlugin(
224
  options: ResolvedOptions,
225
  meta: UnpluginContextMeta
226
): UnpluginOptions;
227

228
/**
229
 * Translation directive optimization plugin
230
 * @param options - Resolved plugin options
231
 * @returns Unplugin options for directive optimization
232
 */
233
function directivePlugin(options: ResolvedOptions): UnpluginOptions;
234

235
/**
236
 * Resolved plugin options with computed defaults
237
 */
238
interface ResolvedOptions {
239
  include: string | string[] | undefined;
240
  exclude: string | undefined;
241
  module: string;
242
  onlyLocales: string[];
243
  forceStringify: boolean;
244
  defaultSFCLang: string;
245
  globalSFCScope: boolean;
246
  runtimeOnly: boolean;
247
  dropMessageCompiler: boolean;
248
  compositionOnly: boolean;
249
  fullInstall: boolean;
250
  ssrBuild: boolean;
251
  allowDynamic: boolean;
252
  strictMessage: boolean;
253
  escapeHtml: boolean;
254
  optimizeTranslationDirective: boolean | string | string[];
255
  translationIdentifiers: Map<string, TranslationDirectiveResolveIndetifier>;
256
  transformI18nBlock: ((src: string | Buffer) => string) | null;
257
}
258

259
/**
260
 * Translation directive resolver identifier
261
 */
262
interface TranslationDirectiveResolveIndetifier {
263
  type: 'identifier' | 'object';
264
  key: string;
265
  style?: 'script-setup' | 'setup-hook';
266
}
267
```
268

269
## Utility Functions
270

271
Internal utilities for plugin operations, logging, and path handling.
272

273
```typescript { .api }
274
/**
275
 * Package name constant
276
 */
277
const PKG_NAME = 'unplugin-vue-i18n';
278

279
/**
280
 * Resolve plugin namespace for debugging
281
 * @param name - Namespace name
282
 * @returns Formatted namespace string
283
 */
284
function resolveNamespace(name: string): string;
285

286
/**
287
 * Normalize file paths across platforms
288
 * @param id - File path to normalize
289
 * @returns Normalized path string
290
 */
291
function normalizePath(id: string): string;
292

293
/**
294
 * Warning logger function
295
 * @param args - Arguments to log
296
 */
297
function warn(...args: unknown[]): void;
298

299
/**
300
 * Error logger function
301
 * @param args - Arguments to log
302
 */
303
function error(...args: unknown[]): void;
304

305
/**
306
 * Throw formatted error with plugin context
307
 * @param message - Error message
308
 * @throws Formatted error with plugin branding
309
 */
310
function raiseError(message: string): void;
311

312
/**
313
 * Get Vite plugin by name from config
314
 * @param config - Vite user config
315
 * @param name - Plugin name to find
316
 * @returns Found plugin or null
317
 */
318
function getVitePlugin(config: UserConfig, name: string): RollupPlugin | null;
319

320
/**
321
 * Validate Vue plugin compatibility
322
 * @param vuePlugin - Vue plugin instance
323
 * @returns Whether plugin is compatible
324
 */
325
function checkVuePlugin(vuePlugin: RollupPlugin | null): boolean;
326
```
327

328
## Types
329

330
```typescript { .api }
331
type SFCLangFormat = 'json' | 'json5' | 'yml' | 'yaml';
332

333
type VueI18nModule = 'vue-i18n' | 'petite-vue-i18n';
334

335
interface PluginOptions {
336
  include?: string | string[];
337
  onlyLocales?: string | string[];
338
  allowDynamic?: boolean;
339
  module?: VueI18nModule;
340
  dropMessageCompiler?: boolean;
341
  runtimeOnly?: boolean;
342
  compositionOnly?: boolean;
343
  ssr?: boolean;
344
  fullInstall?: boolean;
345
  forceStringify?: boolean;
346
  defaultSFCLang?: SFCLangFormat;
347
  globalSFCScope?: boolean;
348
  strictMessage?: boolean;
349
  escapeHtml?: boolean;
350
  optimizeTranslationDirective?: boolean | string | string[];
351
  transformI18nBlock?: (src: string | Buffer) => string;
352
}
353

354
/**
355
 * SFC parsing result with descriptor and errors
356
 */
357
interface SFCParseResult {
358
  descriptor: SFCDescriptor;
359
  errors: (CompilerError | SyntaxError)[];
360
}
361

362
/**
363
 * Vue plugin resolved options interface
364
 */
365
interface VuePluginResolvedOptions {
366
  isProduction: boolean;
367
  root: string;
368
  compiler: typeof import('vue/compiler-sfc');
369
  template?: Partial<SFCTemplateCompileOptions>;
370
}
371
```