0
# Plugin Configuration
1

2
Plugin configuration and initialization for @intlify/unplugin-vue-i18n across different bundlers with universal unplugin architecture support.
3

4
## Capabilities
5

6
### Main Plugin Exports
7

8
Primary plugin exports for different bundlers and use cases.
9

10
```typescript { .api }
11
/**
12
 * Main unplugin instance for universal bundler support
13
 */
14
declare const unplugin: UnpluginInstance<PluginOptions | undefined, boolean>;
15
declare function unpluginFactory(
16
  options?: PluginOptions,
17
  meta: UnpluginContextMeta
18
): UnpluginOptions[];
19

20
export default unplugin;
21
export { unplugin, unpluginFactory };
22
```
23

24
### Vite Plugin
25

26
Vite-specific plugin integration.
27

28
```typescript { .api }
29
/**
30
 * Vite plugin for Vue I18n integration
31
 * @param options - Plugin configuration options
32
 * @returns Vite plugin instance
33
 */
34
declare const VitePlugin: UnpluginInstance<PluginOptions | undefined, boolean>['vite'];
35
export default VitePlugin;
36
```
37

38
**Usage Example:**
39

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

47
export default defineConfig({
48
  plugins: [
49
    vue(),
50
    VueI18nPlugin({
51
      include: [path.resolve(__dirname, './src/locales/**')],
52
      runtimeOnly: true,
53
      compositionOnly: true,
54
      strictMessage: false,
55
      escapeHtml: true
56
    })
57
  ]
58
});
59
```
60

61
### Webpack Plugin
62

63
Webpack-specific plugin integration.
64

65
```typescript { .api }
66
/**
67
 * Webpack plugin for Vue I18n integration
68
 * @param options - Plugin configuration options
69
 * @returns Webpack plugin instance
70
 */
71
declare const WebpackPlugin: UnpluginInstance<PluginOptions | undefined, boolean>['webpack'];
72
export default WebpackPlugin;
73
```
74

75
**Usage Example:**
76

77
```typescript
78
// webpack.config.js
79
const VueI18nPlugin = require('@intlify/unplugin-vue-i18n/webpack');
80
const path = require('path');
81

82
module.exports = {
83
  plugins: [
84
    VueI18nPlugin({
85
      include: [path.resolve(__dirname, './src/locales/**')],
86
      runtimeOnly: true,
87
      compositionOnly: true,
88
      ssr: true
89
    })
90
  ]
91
};
92
```
93

94
### Nuxt Integration
95

96
Nuxt.js framework integration support.
97

98
**Usage Example:**
99

100
```typescript
101
// nuxt.config.ts
102
import { defineNuxtConfig } from 'nuxt';
103
import VueI18nPlugin from '@intlify/unplugin-vue-i18n';
104

105
export default defineNuxtConfig({
106
  vite: {
107
    plugins: [
108
      VueI18nPlugin.vite({
109
        include: ['./locales/**'],
110
        ssr: true
111
      })
112
    ]
113
  },
114
  // For Webpack builder
115
  webpack: {
116
    plugins: [
117
      VueI18nPlugin.webpack({
118
        include: ['./locales/**'],
119
        ssr: true
120
      })
121
    ]
122
  }
123
});
124
```
125

126
## Configuration Options
127

128
### Core Options
129

130
```typescript { .api }
131
interface PluginOptions {
132
  /**
133
   * Pattern(s) to include i18n resource files for pre-compilation
134
   * Supports: .json, .json5, .yaml, .yml, .js, .ts files
135
   */
136
  include?: string | string[];
137
  
138
  /**
139
   * Specific locales to include in the bundle
140
   * Excludes other locales from the final bundle
141
   */
142
  onlyLocales?: string | string[];
143
  
144
  /**
145
   * Target Vue I18n module type
146
   * @default 'vue-i18n'
147
   */
148
  module?: VueI18nModule;
149
}
150

151
type VueI18nModule = 'vue-i18n' | 'petite-vue-i18n';
152
```
153

154
### Build Optimization Options
155

156
```typescript { .api }
157
interface BuildOptimizations {
158
  /**
159
   * Use Vue I18n runtime-only build for production
160
   * @default true
161
   */
162
  runtimeOnly?: boolean;
163
  
164
  /**
165
   * Tree-shake legacy API, use composition API only
166
   * @default true
167
   */
168
  compositionOnly?: boolean;
169
  
170
  /**
171
   * Install full Vue I18n API including built-in components
172
   * @default true
173
   */
174
  fullInstall?: boolean;
175
  
176
  /**
177
   * Tree-shake message compiler for smaller bundles
178
   * @default false
179
   */
180
  dropMessageCompiler?: boolean;
181
  
182
  /**
183
   * Enable SSR support for Vue I18n
184
   * @default false
185
   */
186
  ssr?: boolean;
187
}
188
```
189

190
### Resource Processing Options
191

192
```typescript { .api }
193
interface ResourceOptions {
194
  /**
195
   * Allow dynamic resource construction for JS/TS files
196
   * @default false
197
   */
198
  allowDynamic?: boolean;
199
  
200
  /**
201
   * Force stringify non-string values (numbers, booleans)
202
   * @default false
203
   */
204
  forceStringify?: boolean;
205
  
206
  /**
207
   * Default language format for SFC i18n blocks
208
   * @default 'json'
209
   */
210
  defaultSFCLang?: SFCLangFormat;
211
  
212
  /**
213
   * Make all SFC i18n blocks global scope
214
   * @default false
215
   */
216
  globalSFCScope?: boolean;
217
}
218

219
type SFCLangFormat = 'json' | 'json5' | 'yml' | 'yaml';
220
```
221

222
### Security Options
223

224
```typescript { .api }
225
interface SecurityOptions {
226
  /**
227
   * Strictly check for HTML tags in locale messages
228
   * @default true
229
   */
230
  strictMessage?: boolean;
231
  
232
  /**
233
   * Escape HTML tags in locale messages for XSS protection
234
   * @default false
235
   */
236
  escapeHtml?: boolean;
237
}
238
```
239

240
### Advanced Options
241

242
```typescript { .api }
243
interface AdvancedOptions {
244
  /**
245
   * Optimize v-t translation directive
246
   * @default false
247
   */
248
  optimizeTranslationDirective?: boolean | string | string[];
249
  
250
  /**
251
   * Custom transform function for i18n blocks
252
   */
253
  transformI18nBlock?: (src: string | Buffer) => string;
254
}
255
```
256

257
## Complete Configuration Example
258

259
```typescript
260
// Complete configuration example
261
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite';
262
import path from 'path';
263

264
VueI18nPlugin({
265
  // Resource inclusion
266
  include: [
267
    path.resolve(__dirname, './src/locales/**'),
268
    path.resolve(__dirname, './src/components/**/*.vue')
269
  ],
270
  onlyLocales: ['en', 'fr', 'de'],
271
  
272
  // Module selection
273
  module: 'vue-i18n',
274
  
275
  // Build optimizations
276
  runtimeOnly: true,
277
  compositionOnly: true,
278
  fullInstall: false,
279
  dropMessageCompiler: true,
280
  ssr: false,
281
  
282
  // Resource processing
283
  allowDynamic: false,
284
  forceStringify: true,
285
  defaultSFCLang: 'yaml',
286
  globalSFCScope: false,
287
  
288
  // Security
289
  strictMessage: false,
290
  escapeHtml: true,
291
  
292
  // Advanced features
293
  optimizeTranslationDirective: true,
294
  transformI18nBlock: (src) => {
295
    // Custom transformation logic
296
    return processI18nBlock(src);
297
  }
298
});
299
```