diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 71fd18d74..1e3de5b91 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -67,7 +67,7 @@ function nav() { }, { text: 'Roadmap', - link: '/guide/roadmap' + link: '/guide/extra/roadmap' }, { text: 'v9.x', @@ -90,17 +90,9 @@ function sidebarGuide() { text: 'What is Vue I18n?', link: '/guide/introduction' }, - { - text: 'Getting Started', - link: '/guide/' - }, { text: 'Installation', link: '/guide/installation' - }, - { - text: 'Roadmap', - link: '/guide/roadmap' } ] }, @@ -108,6 +100,10 @@ function sidebarGuide() { text: 'Essentials', collapsible: true, items: [ + { + text: 'Getting Started', + link: '/guide/essentials/started', + }, { text: 'Message Format Syntax', link: '/guide/essentials/syntax' @@ -217,13 +213,20 @@ function sidebarGuide() { ] }, { - text: 'v8.x', + text: 'Extra Topics', collapsible: true, - collapsed: true, items: [ + { + text: 'Different Distribution files', + link: '/guide/extra/dist' + }, { text: 'Documentation for v8.x', - link: '/guide/v8-docs' + link: '/guide/extra/v8-docs' + }, + { + text: 'Roadmap', + link: '/guide/extra/roadmap' } ] } diff --git a/docs/.vitepress/theme/styles/global.css b/docs/.vitepress/theme/styles/global.css index 6516422db..8e4b7f7a6 100644 --- a/docs/.vitepress/theme/styles/global.css +++ b/docs/.vitepress/theme/styles/global.css @@ -1,10 +1,26 @@ :root { + --vp-c-brand-1: var(--vp-c-green-1); + --vp-c-brand-2: var(--vp-c-green-2); + --vp-c-brand-3: var(--vp-c-green-3); + --vp-c-brand-soft: var(--vp-c-green-soft); + --vp-code-color: #476582; --vp-home-hero-name-color: transparent; --vp-home-hero-image-filter: blur(72px); --vp-home-hero-image-background-image: linear-gradient( -45deg, #647eff 30%, #42d392 ); --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #647eff, #42d392); } +:root.dark { + --vp-code-color: #c9def1; + + --vp-home-hero-image-filter: blur(72px); + --vp-home-hero-image-background-image: linear-gradient( + 0deg, + var(--vp-c-brand-soft) 50%, + var(--vp-c-brand-soft) 50% + ); +} + .vp-sponsor-grid.xmini .vp-sponsor-grid-link { height: 64px; } .vp-sponsor-grid.xmini .vp-sponsor-grid-image { max-width: 64px; max-height: 22px } diff --git a/docs/guide/advanced/composition.md b/docs/guide/advanced/composition.md index 8d7f2ebcc..53f49311a 100644 --- a/docs/guide/advanced/composition.md +++ b/docs/guide/advanced/composition.md @@ -6,23 +6,31 @@ We have been describing the features of Vue I18n using the Legacy API, which is ## Basic Usage -Let’s look at the basic usage of Vue I18n Composition API! Here we will learn the basic usage by modifying the code in [Getting Started](../../guide/) to learn the basic usage. +Let’s look at the basic usage of Vue I18n Composition API! Here we will learn the basic usage by modifying the code in [Getting Started](../../guide/essentials/started) to learn the basic usage. To compose with `useI18n` in `setup` of Vue 3, there is one thing you need to do, you need set the `legacy` option of the `createI18n` function to `false`. The following is an example of adding the `legacy` option to `createI18n`: -```js{5} +```js{4} // ... -// 2. Create i18n instance with options const i18n = VueI18n.createI18n({ - legacy: false, // you must set `false`, to use Composition API - locale: 'ja', // set locale - fallbackLocale: 'en', // set fallback locale - messages, // set locale messages - // If you need to specify other options, you can set other options - // ... + legacy: false, // you must set `false`, to use Composition API // [!code ++] + locale: 'ja', + fallbackLocale: 'en', + messages: { + en: { + message: { + hello: 'hello world' + } + }, + ja: { + message: { + hello: 'こんにちは、世界' + } + } + } }) // ... @@ -37,39 +45,42 @@ The following properties of i18n instance created by `createI18n` change its beh - `global` property: VueI18n instance to Composer instance ::: -You are now ready to use `useI18n` in the component `setup`. The code looks like this: +You are now ready to use `useI18n` in the `App.vue` component. The code looks like this: -```js{5-8} -// ... - -// 3. Create a vue root instance -const app = Vue.createApp({ - setup() { - const { t } = VueI18n.useI18n() // call `useI18n`, and spread `t` from `useI18n` returning - return { t } // return render context that included `t` - } -}) +```vue + // [!code ++] -// ... + ``` -You must call `useI18n` at top of the `setup`. +You must call `useI18n` at top of the ` + + ``` The output follows: -```html{2} +```vue

こんにちは、世界

@@ -81,7 +92,38 @@ In the Legacy API mode, the messages were translated using either `$t` or the Vu In the Composition API mode, the Message Format Syntax remains the same as in the Legacy API mode. You can use the Composer instance `t` to translate a message as follows: -```html +```vue + + - ``` For more details of `t`, see the [API Reference](../../api/composition#t-key). @@ -135,7 +141,22 @@ In the Legacy API mode, the plural form of the message was translated using eith In the Composition API mode, the plural form of the message is left in syntax as in the Legacy API mode, but is translated using the `t` of the Composer instance: -```html +```vue + + - - ``` :::tip NOTE @@ -183,44 +183,39 @@ In the Legacy API mode, Datetime value was formatted using `$d` or the VueI18n i In the Composition API mode, it uses the `d` of the Composer instance to format: -```html - - - + + + ``` For more details of `d`, see the [API Reference](../../api/composition#d-value). @@ -231,40 +226,34 @@ In the Legacy API mode, Number value is formatted using `$n` or the `n` of the V In the Composition API mode, it is formatted using the `n` of the Composer instance: -```html - - - + + ``` For more details of `n`, see the [API Reference](../../api/composition#n-value). @@ -279,20 +268,14 @@ There are two ways to refer the global scope Composer instance at the component. ### Explicit with `useI18n` -As we have explained, `setup` in `useI18n` is a way. +As we have explained, in `useI18n` is a way. -```js +```ts import { useI18n } from 'vue-i18n' -export default { - setup() { - const { t } = useI18n({ useScope: 'global' }) - - // Something to do here ... +const { t } = useI18n({ useScope: 'global' }) - return { t } - } -} +// Something to do here ... ``` The above code sets the `useI18n` option to `useScope: 'global'`, which allows `useI18n` to return a Composer instance that can be accessed by the i18n instance `global` property. This allows `useI18n` to return the Composer instance that can be accessed by i18n instance`global` property, which is a global scope. The Composer instance is a global scope. @@ -362,42 +345,36 @@ The following example codes: ```js import { useI18n } from 'vue-i18n' -export default { - setup() { - const { t, d, n, tm, locale } = useI18n({ - locale: 'ja-JP', - fallbackLocale: 'en-US', - messages: { - 'en-US': { - // .... - }, - 'ja-JP': { - // ... - } - }, - datetimeFormats: { - 'en-US': { - // .... - }, - 'ja-JP': { - // ... - } - }, - numberFormats: { - 'en-US': { - // .... - }, - 'ja-JP': { - // ... - } - } - }) - - // Something to do here ... - - return { t, d, n, tm, locale } +const { t, d, n, tm, locale } = useI18n({ + locale: 'ja-JP', + fallbackLocale: 'en-US', + messages: { + 'en-US': { + // .... + }, + 'ja-JP': { + // ... + } + }, + datetimeFormats: { + 'en-US': { + // .... + }, + 'ja-JP': { + // ... + } + }, + numberFormats: { + 'en-US': { + // .... + }, + 'ja-JP': { + // ... + } } -} +}) + +// Something to do here ... ``` @@ -405,27 +382,21 @@ If you use i18n custom blocks in SFC as i18n resource of locale messages, it w The following is an example of using i18n custom blocks and `useI18n` options: -```html - @@ -443,21 +414,19 @@ In this example, the definition of resources is separated from i18n custom block ### Global Scope -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() { - const { t, locale } = useI18n({ useScope: 'global' }) +You want to change the locale with ` ``` And you can also use the setup context in the template, which can be changed as follows: -```html +```vue diff --git a/docs/guide/advanced/optimization.md b/docs/guide/advanced/optimization.md index f9d8dbeae..09f490c07 100644 --- a/docs/guide/advanced/optimization.md +++ b/docs/guide/advanced/optimization.md @@ -44,10 +44,23 @@ If you do the production build, Vue I18n will automatically bundle the runtime o #### Install plugin -```sh -npm install --save-dev @intlify/unplugin-vue-i18n +::: code-group + +```sh [npm] +npm install @intlify/unplugin-vue-i18n -D +``` + +```sh [yarn] +yarn add @intlify/unplugin-vue-i18n -D +``` + +```sh [pnpm] +pnpm add -D @intlify/unplugin-vue-i18n ``` +::: + + #### Configure plugin for vite ```js @@ -132,7 +145,7 @@ Each time localization is performed in an application using `$t` or `t` function You need to configure the following feature flag with `esm-bundler` build and bundler such as vite: -- `__INTLIFY_JIT_COMPILATION__` (enable/disable message compiler for JIT style, default: `false`) +- `__INTLIFY_JIT_COMPILATION__` (enable/disable message compiler for JIT style, default: `false`) - `__INTLIFY_DROP_MESSAGE_COMPILER__` (enable/disable whether to tree-shake message compiler when we will be bundling, this flag works when `__INTLIFY_JIT_COMPILATION__` is enabled. default: `false`) :::warning NOTICE diff --git a/docs/guide/advanced/sfc.md b/docs/guide/advanced/sfc.md index b8f76bffc..3fe1eedb9 100644 --- a/docs/guide/advanced/sfc.md +++ b/docs/guide/advanced/sfc.md @@ -6,7 +6,7 @@ If you are building Vue component or Vue application using single file component The following in [single file components example](https://github.com/kazupon/vue-i18n/tree/dev/examples/sfc): -```html +```vue + + ``` the above codes, by specifying the defined schema as the first type parameter of `useI18n`, you can use TypeScript to check for undefined resources for locale messages and number formats. Also, by specifying the locale to be defined in the second type parameter, TypeScript can check for undefined locales. @@ -186,6 +183,7 @@ Use-cases on your project, you may have Vue components that do not use local sco For that use case, you can also support interpolation of resource keys by explicitly specifying the schema defined for the global scope in the type parameter of `useI18n`. define schema for global scope: + ```ts /** * define the resource schema @@ -207,29 +205,24 @@ export type NumberSchema = { ``` Then, just import the defined schema and use it as a type parameter of `useI18n`, as in the following Vue component: -```html - +```vue + + + ``` As a result, you can use the interpolation of resource keys in the APIs provided by VueI18n, such as `t` and `n`. @@ -256,6 +249,7 @@ VueI18n provides the following interfaces: With using these interfaces and the `declare module`, you can define a global schema for VueI18n. The following is an example of a global schema defined in `d.ts`: + ```ts /** * you need to import the some interfaces @@ -304,6 +298,7 @@ Previously, when using `createI18n` and `useI18n` with type definitions for glob This way, you don't need to do that. The following is an example with `createI18n`: + ```ts import { createI18n, type I18nOptions } from 'vue-i18n' @@ -356,28 +351,22 @@ The first type parameter of `createI18n` above does not specify the type that is The second type parameter of `createI18n` specifies a type hint for options. In the case of the `useI18n` case used by Vue components, it looks like this: -```html - - + + ``` As you can see from the above code, you don't need to specify anything for the type parameter of `useI18n`. You can interpolate API Resource Keys such as `t`, `d`, and `n` without specifying them. diff --git a/docs/guide/advanced/wc.md b/docs/guide/advanced/wc.md index 9aaccc161..26af7708a 100644 --- a/docs/guide/advanced/wc.md +++ b/docs/guide/advanced/wc.md @@ -21,9 +21,10 @@ Using `defineCustomElement`, which is supported since Vue 3.2, we can provide Vu However, the provided Web Components cannot be inserted directly into HTML. You need to prepare the following Web Components to host the i18n instance created by `createI18n`. Web Components that host the i18n instance: -```html - @@ -79,7 +71,7 @@ Then, to host other Web Components, the `template` block makes it possible by us Export this hosted Web Components as follows: -```javascript +```js import { defineCustomElement } from 'vue' import I18nHost from './components/I18nHost.ce.vue' @@ -90,7 +82,7 @@ export { I18nHostElement } The following `useI18n` implements and exports Web Components to: -```html +```vue - - -
-

{{ $t("message.hello") }}

-
-``` - -In the HTML template, we use the `$t` translation API injected with Vue I18n, to localize. This allows Vue I18n to change the locale without rewriting the template, also to be able to support the global application. - -## JavaScript - -```js -// 1. Ready translated locale messages -// The structure of the locale message is the hierarchical object structure with each locale as the top property -const messages = { - en: { - message: { - hello: 'hello world' - } - }, - ja: { - message: { - hello: 'こんにちは、世界' - } - } -} - -// 2. Create i18n instance with options -const i18n = VueI18n.createI18n({ - locale: 'ja', // set locale - fallbackLocale: 'en', // set fallback locale - messages, // set locale messages - // If you need to specify other options, you can set other options - // ... -}) - - -// 3. Create a vue root instance -const app = Vue.createApp({ - // set something options - // ... -}) - -// 4. Install i18n instance to make the whole app i18n-aware -app.use(i18n) - -// 5. Mount -app.mount('#app') - -// Now the app has started! -``` - -Output the following: - -```html -
-

こんにちは、世界

-
-``` - -By default, calling `app.use(i18n)` gives us access to the VueI18n instance from each component with `this.$i18n`, which can be referenced from the `global` property of i18n instance that created with `createI18n`. As well as, translation API such as `this.$t` is also injected into each component, so these API can be used with templates. - -To use similar ways like the `setup` function, you need to call the `useI18n` functions. We will learn more about this in the [Composition API](./advanced/composition). - -:::tip NOTE -For more information on the Composition API, please refer to [documentation](https://v3.vuejs.org/guide/composition-api-introduction.html) of Vue.js -::: - -Throughout the docs, we’ll use APIs like `this.$i18n` and `this.$t`, which are almost backwards compatible from Vue I18n v8.x. - -:::tip NOTE -In Vue I18n v9 and later, the API offered by Vue I18n v8.x is called **Legacy API** mode. -::: - -The following sections will be explained using the Legacy API mode. diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 5a9348a0f..debdac7ee 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -5,51 +5,24 @@ - Vue.js `3.0.0`+ - -## Direct Download - - - -[unpkg.com](https://unpkg.com) provides a npm-based CDN links. The above link will always point to the latest release on npm. - -### Global import - -```html - - -``` - -You can also use a specific version/tag via URLs like - -### ES Modules import - -```html - + ``` +You can also use a specific version/tag via URLs like -## Explanation of Different Builds -In the [dist/ directory of the npm package](https://cdn.jsdelivr.net/npm/vue-i18n@9.1.10/dist/) you will find many different builds of Vue I18n. Here is an overview of which dist file should be used depending on the use-case. - -### From CDN or without a Bundler - -- **`vue-i18n(.runtime).global(.prod).js`**: - - For direct use via ` + - - ``` ## DatetimeFormat Component diff --git a/docs/guide/migration/vue2.md b/docs/guide/migration/vue2.md index e98a53af5..001af6423 100644 --- a/docs/guide/migration/vue2.md +++ b/docs/guide/migration/vue2.md @@ -2,6 +2,10 @@ ## `vue-i18n-bridge` +:::danger NOTE +vue-i18n-bridge will not be provided in v10 due to Vue 2 EOL. v9.x will be the last version. +::: + ### What is `vue-i18n-bridge`? `vue-i18n-bridge` is a bridge to make the upgrade as easy as possible between vue-i18n@v8.26.1 or later and vue-i18n@v9.x. @@ -17,15 +21,23 @@ And, also some features are backported from vue-i18n@v9.x: #### Package manager -```sh -# npm +::: code-group + +```sh [npm] npm install vue-i18n-bridge -# yarn +``` + +```sh [yarn] yarn add vue-i18n-bridge -# pnpm +``` + +```sh [pnpm] pnpm add vue-i18n-bridge ``` +::: + + You must install the below packages before using this library: - vue-i18n: >= v8.26.1 < v9 diff --git a/examples/type-safe/global-type-definition/src/App.vue b/examples/type-safe/global-type-definition/src/App.vue index 00a694468..4c5cd7824 100644 --- a/examples/type-safe/global-type-definition/src/App.vue +++ b/examples/type-safe/global-type-definition/src/App.vue @@ -1,19 +1,11 @@ + + - -