Skip to content

breaking: change globalInjection default disable #204

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 3, 2020
Merged

breaking: change globalInjection default disable #204

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 18 additions & 25 deletions docs-old/.vuepress/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,9 @@ module.exports = {
lang: 'ru-RU',
title: 'Vue I18n',
description: 'Vue I18n — плагин для интернационализации во Vue.js'
},
}
},
head: [
['meta', { name: 'theme-color', content: '#3eaf7c' }],
],
head: [['meta', { name: 'theme-color', content: '#3eaf7c' }]],
serviceWorker: false,
themeConfig: {
repo: 'kazupon/vue-i18n',
Expand Down Expand Up @@ -70,11 +68,13 @@ module.exports = {
items: [
{
text: 'BabelEdit',
link: 'https://www.codeandweb.com/babeledit?utm_campaign=vue-i18n-2019-01'
link:
'https://www.codeandweb.com/babeledit?utm_campaign=vue-i18n-2019-01'
},
{
text: 'i18n Ally',
link: 'https://marketplace.visualstudio.com/items?itemName=antfu.i18n-ally'
link:
'https://marketplace.visualstudio.com/items?itemName=antfu.i18n-ally'
}
]
}
Expand Down Expand Up @@ -116,10 +116,7 @@ module.exports = {
{
title: 'Legacy',
collapsable: false,
children: [
'/legacy/',
'/legacy/v5'
]
children: ['/legacy/', '/legacy/v5']
}
]
},
Expand All @@ -131,7 +128,7 @@ module.exports = {
nav: [
{
text: '指南',
link: '/zh/guide/formatting',
link: '/zh/guide/formatting'
},
{
text: 'API',
Expand Down Expand Up @@ -166,7 +163,8 @@ module.exports = {
items: [
{
text: 'BabelEdit',
link: 'https://www.codeandweb.com/babeledit?utm_campaign=vue-i18n-2019-01'
link:
'https://www.codeandweb.com/babeledit?utm_campaign=vue-i18n-2019-01'
}
]
}
Expand Down Expand Up @@ -208,10 +206,7 @@ module.exports = {
{
title: 'Legacy',
collapsable: false,
children: [
'/zh/legacy/',
'/zh/legacy/v5'
]
children: ['/zh/legacy/', '/zh/legacy/v5']
}
]
},
Expand All @@ -223,7 +218,7 @@ module.exports = {
nav: [
{
text: 'Руководство',
link: '/ru/guide/formatting',
link: '/ru/guide/formatting'
},
{
text: 'Справочник API',
Expand Down Expand Up @@ -258,11 +253,13 @@ module.exports = {
items: [
{
text: 'BabelEdit',
link: 'https://www.codeandweb.com/babeledit?utm_campaign=vue-i18n-2019-01'
link:
'https://www.codeandweb.com/babeledit?utm_campaign=vue-i18n-2019-01'
},
{
text: 'i18n Ally',
link: 'https://marketplace.visualstudio.com/items?itemName=antfu.i18n-ally'
link:
'https://marketplace.visualstudio.com/items?itemName=antfu.i18n-ally'
}
]
}
Expand Down Expand Up @@ -304,14 +301,10 @@ module.exports = {
{
title: 'Устаревшие версии',
collapsable: false,
children: [
'/ru/legacy/',
'/ru/legacy/v5'
]
children: ['/ru/legacy/', '/ru/legacy/v5']
}
]
},
}
}
}
}

48 changes: 31 additions & 17 deletions docs/advanced/composition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,9 +179,9 @@ In the Composition API mode, plural translations have been integrated into `t`.

## Datetime Formatting

In the Legacy API mode, Datetime value was localized using `$d` or the VueI18n instance of `d`.
In the Legacy API mode, Datetime value was formatted using `$d` or the VueI18n instance of `d`.

In the Compostion API mode, it uses the `d` of the Composer instance to localize:
In the Compostion API mode, it uses the `d` of the Composer instance to format:

```html
<template>
Expand Down Expand Up @@ -227,9 +227,9 @@ For more details of `d`, see the [API Reference](../api/composition#d-value).

## Number Formatting

In the Legacy API mode, Number value is localized using `$n` or the `n` of the VueI18n instance.
In the Legacy API mode, Number value is formatted using `$n` or the `n` of the VueI18n instance.

In the Compostion API mode, it is localized using the `n` of the Composer instance:
In the Compostion API mode, it is formatted using the `n` of the Composer instance:

```html
<template>
Expand Down Expand Up @@ -303,7 +303,9 @@ Then you can compose using the functions and properties exposed from the Compose

Another way to refer a global scope Composer instance is through properties and functions implicitly injected into the component.

If you use Compostion API mode with the `legacy: false` option for `createI18n`, Vue I18n defaults to the following properties and functions, which injected to the component via `app.config.globalProperties`:
You need to specify **`globalInjection: true`** together with `legacy: false` as an option for `createI18n`, because disabled by default.

This allows Vue I18n to inject the following properties and functions into the components:

- `$i18n`: An object wrapped with the following global scope Composer instance properties
- `locale`
Expand All @@ -328,8 +330,11 @@ You’ve noticed that the ones listed above are prifixed with `$`. The reason fo

By doing so, the user is made aware that they are special properties and functions.

With the previously explained explicit way, you had to run `useI18n` in `setup` every time. **If your Vue application doesn’t use local scope and does everything i18n in global scope**, it is very convenient because you don’t have to run `useI18n` in the `setup` every time.
:::warning NOTICE
If your Vue application doesn’t use local scope and does everything i18n in global scope, this is very useful as it does not need to run `useI18n` in the `setup` for each component. However, this way has the problem with global variables of the same nature. You should be used with caution, especially for large Vue applications.

If you use it once and stop using it, you must change all the properties or functions used in the templates to those of the setup context returned with the `setup` using the `useI18n` with `useScope: 'global'` option.
:::

## Local scope

Expand Down Expand Up @@ -423,16 +428,7 @@ In this example, the definition of resources is separated from i18n custom block

### Global Scope

Changing the locale in the global scope, i.e., Composer instance `locale` property referenced by i18n instance `global` property, you can change with `$i18n.locale`.

```html
<select v-model="$i18n.locale">
<option value="en">en</option>
<option value="ja">ja</option>
</select>
```

If you want to change the locale with `setup`, just get a global Composer with `useI18n` and change it using the `locale` property of the instance.
You want to change the locale with `setup`, just get a global Composer with `useI18n` and change it using the `locale` property of the instance.

```js
setup() {
Expand All @@ -444,11 +440,29 @@ setup() {
}
```

And you can also use the setup context in the template, which can be changed as follows:

```html
<select v-model="locale">
<option value="en">en</option>
<option value="ja">ja</option>
</select>
```

When you change the locale of the global scope, components that depend on the global scope, such as `t` translation API can work reactive and switch the display messages to those of the target locale.

If you are using the [implicit way](composition#implicit-with-injected-properties-and-functions), you can also change it in template with `$i18n.locale`, as follows:

```html
<select v-model="$i18n.locale">
<option value="en">en</option>
<option value="ja">ja</option>
</select>
```

### Local Scope

The local scope locales, that is, the Composer instance `locale` property returned by `useI18n`, are inherited from the global scope, as is the Legacy API. Therefore, when you change the locale at global scope, the inherited local scope locale is also changed. If you want to switch the locale for the whole application, you need to do so via `$i18n.locale`.
The local scope locales, that is, the Composer instance `locale` property returned by `useI18n`, are inherited from the global scope, as is the Legacy API. Therefore, when you change the locale at global scope, the inherited local scope locale is also changed. If you want to switch the locale for the whole application, you can use the `locale` returned by `useI18n({ useScope: 'global' })` or, if you use [implicit way](composition#implicit-with-injected-properties-and-functions), you can use `$i18n.locale`.

:::tip NOTE
If you do not want to inherit the locale from the global scope, the `inheritLocale` option of `useI18n` must be `false`.
Expand Down
8 changes: 4 additions & 4 deletions docs/api/injection.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -776,10 +776,10 @@ $d(value: number | Date): DateTimeFormatResult;

If this is used in a reactive context, it will re-evaluate once the locale changes.

In [Compostion API mode](general#i18nmode), the `$d` is injected by `app.config.globalProperties`. The input / output is the same as for Composer instance, and it work on **global scope**. About that details, see [Composer#d](composition#d-value).

In [Compostion API mode](general#i18nmode), the input / output is the same as for VueI18n instance. About details, see [VueI18n#d](legacy#d-value).

In [Compostion API mode](general#i18nmode), the `$d` is injected by `app.config.globalProperties`. The input / output is the same as for Composer instance, and it work on **global scope**. About that details, see [Composer#d](composition#d-value).

**See Also**
- [Datetime Formatting](../essentials/datetime)
- [Scope and Locale Changing](../essentials/scope)
Expand Down Expand Up @@ -969,10 +969,10 @@ $n(value: number): NumberFormatResult;

If this is used in a reactive context, it will re-evaluate once the locale changes.

In [Compostion API mode](general#i18nmode), the `$n` is injected by `app.config.globalProperties`. The input / output is the same as for Composer instance, and it work on **global scope**. About that details, see [Composer#n](composition#n-value).

In [Legacy API mode](general#i18nmode), the input / output is the same as for VueI18n instance. About details, see [VueI18n#n](legacy#n-value).

In [Compostion API mode](general#i18nmode), the `$n` is injected by `app.config.globalProperties`. The input / output is the same as for Composer instance, and it work on **global scope**. About that details, see [Composer#n](composition#n-value).

**See Also**
- [Number Formatting](../essentials/number)
- [Scope and Locale Changing](../essentials/scope)
Expand Down
8 changes: 4 additions & 4 deletions examples/composition/formatting/linked.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
<body>
<div id="app">
<form>
<label>{{ $t('message.language') }}</label>
<select v-model="$i18n.locale">
<label>{{ t('message.language') }}</label>
<select v-model="locale">
<option value="en">en</option>
<option value="ja">ja</option>
</select>
Expand Down Expand Up @@ -64,12 +64,12 @@

const app = createApp({
setup() {
const { t } = useI18n()
const { t, locale } = useI18n()

// Something to do ...
//

return { t }
return { t, locale }
}
})
app.use(i18n)
Expand Down
1 change: 1 addition & 0 deletions examples/composition/scope/global.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ <h1>Child</h1>

const i18n = createI18n({
legacy: false,
globalInjection: true,
locale: 'ja',
messages: {
en: {
Expand Down
6 changes: 3 additions & 3 deletions src/i18n.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,12 +84,12 @@ export interface I18nAdditionalOptions {
* Whether Whether to inject global properties & functions into for each component.
*
* @remarks
* If set to `false`, then properties and methods prefixed with `$` are injected into Vue Component.
* If set to `true`, then properties and methods prefixed with `$` are injected into Vue Component.
*
* @VueI18nSee [Implicit with injected properties and functions](../advanced/composition#implicit-with-injected-properties-and-functions)
* @VueI18nSee [ComponentCustomProperties](injection#componentcustomproperties)
*
* @defaultValue `true`
* @defaultValue `false`
*/
globalInjection?: boolean
}
Expand Down Expand Up @@ -315,7 +315,7 @@ export function createI18n<
const __legacyMode = __FEATURE_LEGACY_API__ && isBoolean(options.legacy)
? options.legacy
: true
const __globalInjection = !options.globalInjection
const __globalInjection = !!options.globalInjection
const __instances = new Map<
ComponentInternalInstance,
VueI18n<Messages> | Composer<Messages>
Expand Down
16 changes: 8 additions & 8 deletions src/vue.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,11 @@ declare module '@vue/runtime-core' {
* @remarks
* If this is used in a reactive context, it will re-evaluate once the locale changes.
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#t | `VueI18n#t`}.
*
* In {@link I18nMode | Compostion API mode}, the `$t` is injected by `app.config.globalProperties`.
* the input / output is the same as for Composer, and it work on **global scope**. About that details, see {@link Composer#t | `Composer#t` }.
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#t | `VueI18n#t`}.
*
* @param key - A target locale message key
*
* @returns translation message
Expand Down Expand Up @@ -427,11 +427,11 @@ declare module '@vue/runtime-core' {
* @remarks
* If this is used in a reactive context, it will re-evaluate once the locale changes.
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#d | `VueI18n#d` }.
*
* In {@link I18nMode | Compostion API mode}, the `$d` is injected by `app.config.globalProperties`.
* the input / output is the same as for Composer instance, and it work on **global scope**. About that details, see {@link Composer#d | `Composer#d` }.
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#d | `VueI18n#d` }.
*
* @param value - A value, timestamp number or `Date` instance
*
* @returns formatted value
Expand Down Expand Up @@ -531,11 +531,11 @@ declare module '@vue/runtime-core' {
* @remarks
* If this is used in a reactive context, it will re-evaluate once the locale changes.
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#n | `VueI18n.n` }.
*
* In {@link I18nMode | Compostion API mode}, the `$n` is injected by `app.config.globalProperties`.
* the input / output is the same as for Composer instance, and it work on **global scope**. About that details, see {@link Composer#n | `Composer.n` }.
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#n | `VueI18n.n` }.
*
* @param value - A number value
*
* @returns formatted value
Expand Down Expand Up @@ -629,12 +629,12 @@ declare module '@vue/runtime-core' {
/**
* Locale messages getter
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#tm | `VueI18n#tm` }.
*
* @remarks
* In {@link I18nMode | Compostion API mode}, the `$tm` is injected by `app.config.globalProperties`.
* the input / output is the same as for Composer instance, and it work on **global scope**. About that details, see {@link Composer#tm | `Composer.tm` }.
*
* In {@link I18nMode | Legacy API mode}, the input / output is the same as for VueI18n instance. About that details, see {@link VueI18n#tm | `VueI18n#tm` }.
*
* @param key - A target locale message key
*
* @return locale messages
Expand Down