Skip to content

Commit 2aef7f8

Browse files
userquinuserquin
authored
docs: add defaultSFCLocale and globalSFCScope to sfc (#555)
* docs: add `defaultSFCLocale` and `globalSFCScope` to sfc * docs: add `defaultSFCLocale` hint and `globalSFCScope` warning * docs: add warning and `WIP` for rollup and webpack plugins for `defaultSFCLocale` and `globalSFCScope` global options * docs: remove warning from `globalSFCScope` on `rollup` and `webpack` plugins
1 parent 528566b commit 2aef7f8

File tree

1 file changed

+192
-2
lines changed

1 file changed

+192
-2
lines changed

‎docs/guide/advanced/sfc.md‎

Lines changed: 192 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ export default {
3636

3737
In i18n custom blocks, the format of the locale messages resource is **json** format by default.
3838

39-
The locale messages defined by i18n custom blocks are used as the local scope in single file components.
39+
The locale messages defined by i18n custom blocks, are used as the local scope in single file components.
4040

4141
If `$t('hello')` is used in the template, the `hello` key defined by `i18n` custom blocks is referred to.
4242

@@ -68,6 +68,8 @@ npm i --save-dev @intlify/vite-plugin-vue-i18n
6868

6969
#### Configuration
7070

71+
See also [use global format](#use-global-format-with-vite-plugin) and [use global scope](#use-global-scope-with-vite-plugin).
72+
7173
vite config for example:
7274

7375
```ts
@@ -108,6 +110,8 @@ npm i --save-dev @intlify/vue-i18n-loader
108110

109111
#### Configuration
110112

113+
See also [use global format](#use-global-format-with-webpack-plugin) and [use global scope](#use-global-scope-with-webpack-plugin).
114+
111115
Webpack config for example:
112116

113117
```js
@@ -128,7 +132,7 @@ module.exports = {
128132
path.resolve(__dirname, './src/locales'),
129133
],
130134
loader: '@intlify/vue-i18n-loader'
131-
}
135+
},
132136
// for i18n custom block
133137
{
134138
resourceQuery: /blockType=i18n/,
@@ -162,6 +166,8 @@ npm i --save-dev @intlify/rollup-plugin-vue-i18n
162166

163167
#### Configuration
164168

169+
See also [use global format](#use-global-format-with-rollup-plugin) and [use global scope](#use-global-scope-with-rollup-plugin).
170+
165171
Rollup config for example:
166172

167173
```js
@@ -295,6 +301,93 @@ The `i18n` custom blocks below of `json5` format:
295301
</i18n>
296302
```
297303

304+
### Define global format
305+
306+
If you are using one of `@intlify/vite-plugin-vue-i18n`, `@intlify/vue-i18n-loader` or `@intlify/rollup-plugin-vue-i18n`
307+
plugin on your project, you can also define the `lang` for all your inlined `i18n` custom blocks
308+
on all your `SFC` using the `defaultSFCLocale` option.
309+
310+
:::warning:::
311+
`@intlify/vue-i18n-loader` and `@intlify/rollup-plugin-vue-i18n` are currently in progress to add this feature.
312+
313+
On inlined `i18n` custom blocks that have specified the `lang` attribute, the `defaultSFCLang` is not applied.
314+
315+
For example, in order to configure `yml` format on all your inlined `i18n` custom blocks on all your `SFC`:
316+
317+
```html
318+
<!-- custom block equivalent to &lt;i18n lang="yml"> -->
319+
<i18n>
320+
en:
321+
hello: Hello
322+
es:
323+
hello: Hola
324+
</i18n>
325+
```
326+
327+
just configure `defaultSFCLocale: "yml"` on your plugin configuration:
328+
329+
#### Use global format with vite plugin
330+
331+
```javascript
332+
import vue from '@vitejs/plugin-vue'
333+
import vueI18n from '@intlify/vite-plugin-vue-i18n'
334+
335+
plugins: [
336+
vue(),
337+
vueI18n({
338+
defaultSFCLocale: "yml",
339+
/* other options */
340+
})
341+
]
342+
```
343+
344+
#### Use global format with webpack plugin (WIP)
345+
346+
```javascript
347+
module.exports = {
348+
// ...
349+
module: {
350+
rules: [
351+
{
352+
test: /\.vue$/,
353+
loader: 'vue-loader',
354+
},
355+
// for i18n resources (json/json5/yaml)
356+
{
357+
test: /\.(json5?|ya?ml)$/, // target json, json5, yaml and yml files
358+
type: 'javascript/auto',
359+
defaultSFCLocale: 'yml',
360+
/* other options */,
361+
loader: '@intlify/vue-i18n-loader'
362+
},
363+
// for i18n custom block
364+
{
365+
resourceQuery: /blockType=i18n/,
366+
type: 'javascript/auto',
367+
loader: '@intlify/vue-i18n-loader'
368+
}
369+
// ...
370+
]
371+
}
372+
// ...
373+
}
374+
```
375+
376+
#### Use global format with rollup plugin (WIP)
377+
378+
```javascript
379+
plugins: [
380+
// set `customBlocks` opton to `rollup-plugin-vue`
381+
VuePlugin({ customBlocks: ['i18n'] }),
382+
// set `rollup-plugin-vue-i18n` after **`rollup-plugin-vue`**
383+
VueI18nPlugin({
384+
defaultSFCLocale: 'yml',
385+
/* other options */
386+
}),
387+
/* other plugins */
388+
]
389+
```
390+
298391
## Define locale messages for global scope
299392

300393
You can use define locale messages for global scope with `global` attribute:
@@ -311,6 +404,103 @@ You can use define locale messages for global scope with `global` attribute:
311404

312405
In the above example, since the `global` attribute is set, the locale messages defined in `i18n` custom blocks can be merged as a resource for locale messages of global scope.
313406

407+
### Define global scope
408+
409+
If you are using one of `@intlify/vite-plugin-vue-i18n`, `@intlify/vue-i18n-loader` or
410+
`@intlify/rollup-plugin-vue-i18n`
411+
plugin on your project, you can also define the `global` scope for all your `i18n` custom blocks
412+
on all your `SFC` using the `globalSFCScope` option.
413+
414+
:::warning:::
415+
`@intlify/vue-i18n-loader` and `@intlify/rollup-plugin-vue-i18n` are currently in progress to add this feature.
416+
417+
**Warning**: beware enabling `globalSFCScope: true`, all `i18n` custom blocks in all your `SFC` will be on `global` scope.
418+
419+
For example, in order to configure `global` scope on all your `i18n` custom blocks on all your `SFC`:
420+
421+
```html
422+
<!-- custom block equivalent to &lt;i18n lang="yml" global> -->
423+
<i18n lang="yml">
424+
en:
425+
hello: Hello
426+
es:
427+
hello: Hola
428+
</i18n>
429+
```
430+
431+
or
432+
433+
```html
434+
<!-- custom block equivalent to &lt;i18n src="./locales/myMessages.json" global> -->
435+
<i18n src="./locales/myMessages.json5">
436+
</i18n>
437+
```
438+
439+
just configure `globalSFCScope: true` on your plugin configuration:
440+
441+
#### Use global format with vite plugin
442+
443+
```javascript
444+
import vue from '@vitejs/plugin-vue'
445+
import vueI18n from '@intlify/vite-plugin-vue-i18n'
446+
447+
plugins: [
448+
vue(),
449+
vueI18n({
450+
globalSFCScope: true,
451+
/* other options */
452+
})
453+
]
454+
```
455+
456+
#### Use global format with webpack plugin (WIP)
457+
458+
```javascript
459+
module.exports = {
460+
// ...
461+
module: {
462+
rules: [
463+
{
464+
test: /\.vue$/,
465+
loader: 'vue-loader',
466+
},
467+
// for i18n resources (json/json5/yaml)
468+
{
469+
test: /\.(json5?|ya?ml)$/, // target json, json5, yaml and yml files
470+
type: 'javascript/auto',
471+
globalSFCScope: true,
472+
/* other options */,
473+
loader: '@intlify/vue-i18n-loader'
474+
},
475+
// for i18n custom block
476+
{
477+
resourceQuery: /blockType=i18n/,
478+
type: 'javascript/auto',
479+
loader: '@intlify/vue-i18n-loader'
480+
}
481+
// ...
482+
]
483+
}
484+
// ...
485+
}
486+
```
487+
488+
#### Use global format with rollup plugin (WIP)
489+
490+
```javascript
491+
plugins: [
492+
// set `customBlocks` opton to `rollup-plugin-vue`
493+
VuePlugin({ customBlocks: ['i18n'] }),
494+
// set `rollup-plugin-vue-i18n` after **`rollup-plugin-vue`**
495+
VueI18nPlugin({
496+
globalSFCScope: true,
497+
/* other options */
498+
}),
499+
/* other plugins */
500+
]
501+
```
502+
503+
314504
:::warning NOTICE
315505
The locale messages for global scope defined in i18n custom blocks are available **only composition API mode**. You need to run `useI18n` option to `useScope: 'global'` at `setup`. About details, see the [Composition API](./composition).
316506
:::

0 commit comments

Comments
 (0)