|
| 1 | +# Migration ways |
| 2 | + |
| 3 | +## `vue-i18n-bridge` |
| 4 | + |
| 5 | +### What is `vue-i18n-bridge`? |
| 6 | + |
| 7 | +`vue-i18n-bridge` is a bridge to make the upgrade as easy as possible between [email protected] or later and [email protected]. |
| 8 | + |
| 9 | +It can be used in Vue 2 applications that you have already built with [email protected] or later. |
| 10 | + |
| 11 | +And, also some features are backported from [email protected]: |
| 12 | + |
| 13 | +- Vue I18n Compostion API, that is powered by `@vue/composition-api` |
| 14 | +- Message format syntax, that is powered by `@intlify/message-compiler` |
| 15 | + |
| 16 | +### Installation |
| 17 | + |
| 18 | +#### Package manager |
| 19 | + |
| 20 | +```sh |
| 21 | +# npm |
| 22 | +npm install vue-i18n-bridge |
| 23 | +# yarn |
| 24 | +yarn add vue-i18n-bridge |
| 25 | +# pnpm |
| 26 | +pnpm add vue-i18n-bridge |
| 27 | +``` |
| 28 | + |
| 29 | +You must install the below packages before using this library: |
| 30 | + |
| 31 | +- vue-i18n: >= v8.26.1 < v9 |
| 32 | +- @vue/composition-api: >= v1.2.0 |
| 33 | + |
| 34 | +#### CDN |
| 35 | + |
| 36 | +Include `vue-i18n-bridge` after `vue`, `@vue/composition-api` and it will install. |
| 37 | + |
| 38 | +```html |
| 39 | +< script src= "https://cdn.jsdelivr.net/npm/[email protected]"></ script> |
| 40 | +<script src="https://unpkg.com/vue-i18n@8/dist/vue-i18n.min.js"></script> |
| 41 | +< script src= "https://cdn.jsdelivr.net/npm/@vue/[email protected]"></ script> |
| 42 | +< script src= "https://unpkg.com/[email protected]/dist/vue-i18n-bridge.global.prod.js"></ script> |
| 43 | +``` |
| 44 | + |
| 45 | +### Usage |
| 46 | + |
| 47 | +#### Composition API |
| 48 | + |
| 49 | +```js |
| 50 | +import Vue from 'vue' |
| 51 | +import VueCompositionAPI, { createApp } from '@vue/composition-api' |
| 52 | +import { createI18n, useI18n } from 'vue-i18n-bridge' |
| 53 | + |
| 54 | +Vue.use(VueCompositionAPI) |
| 55 | +Vue.use(VueI18n, { bridge: true }) // you must specify '{ bridge: true }' plugin option when install vue-i18n |
| 56 | + |
| 57 | +// `createI18n` options is almost same vue-i18n-next ([email protected]) API |
| 58 | +const i18n = createI18n({ |
| 59 | + legacy: false, |
| 60 | + locale: 'ja', |
| 61 | + messages: { |
| 62 | + en: { |
| 63 | + message: { |
| 64 | + hello: 'hello, {name}!' |
| 65 | + } |
| 66 | + }, |
| 67 | + ja: { |
| 68 | + message: { |
| 69 | + hello: 'こんにちは、{name}！' |
| 70 | + } |
| 71 | + } |
| 72 | + } |
| 73 | +}, VueI18n) // `createI18n` which is provide `vue-i18n-bridge` has second argument, you **must** pass `VueI18n` constructor which is provide `vue-i18n` |
| 74 | + |
| 75 | +const app = createApp({ |
| 76 | + setup() { |
| 77 | + // `useI18n` options is almost same vue-i18n-next ([email protected]) API |
| 78 | + const { t, locale } = useI18n() |
| 79 | + // ... todo something |
| 80 | + |
| 81 | + return { t, locale } |
| 82 | + } |
| 83 | +}) |
| 84 | + |
| 85 | +app.use(i18n) // you must install `i18n` instance which is created by `createI18n` |
| 86 | +app.mount('#app') |
| 87 | +``` |
| 88 | + |
| 89 | +#### Legacy API |
| 90 | + |
| 91 | +```js |
| 92 | +import Vue from 'vue' |
| 93 | +import VueCompositionAPI from '@vue/composition-api' |
| 94 | +import { createI18n, useI18n } from 'vue-i18n-bridge' |
| 95 | + |
| 96 | +Vue.use(VueCompositionAPI) |
| 97 | +Vue.use(VueI18n, { bridge: true }) // you must specify '{ bridge: true }' plugin option when install vue-i18n |
| 98 | + |
| 99 | +// `createI18n` options is almost same vue-i18n-next ([email protected]) API |
| 100 | +const i18n = createI18n({ |
| 101 | + locale: 'ja', |
| 102 | + messages: { |
| 103 | + en: { |
| 104 | + message: { |
| 105 | + hello: 'hello, {name}!' |
| 106 | + } |
| 107 | + }, |
| 108 | + ja: { |
| 109 | + message: { |
| 110 | + hello: 'こんにちは、{name}！' |
| 111 | + } |
| 112 | + } |
| 113 | + } |
| 114 | +}, VueI18n) // `createI18n` which is provide `vue-i18n-bridge` has second argument, you **must** pass `VueI18n` constructor which is provide `vue-i18n` |
| 115 | + |
| 116 | +Vue.use(i18n) // you must install `i18n` instance which is created by `createI18n` |
| 117 | + |
| 118 | +const app = new Vue({ i18n }) |
| 119 | +app.$mount('#app') |
| 120 | +``` |
| 121 | + |
| 122 | +### Usage UMD module in browser |
| 123 | + |
| 124 | +```js |
| 125 | +const { createApp } = VueCompositionAPI // exported UMD which is named by `VueCompositionAPI |
| 126 | +const { createI18n, useI18n } = VueI18nBridge // exported UMD which is named by `VueI18nBridge` |
| 127 | + |
| 128 | +Vue.use(VueCompositionAPI) |
| 129 | +Vue.use(VueI18n, { bridge: true }) |
| 130 | +``` |
| 131 | + |
| 132 | +### Limitations |
| 133 | +- In Legacy API mode, You **cannot use [new message format syntax](https://vue-i18n.intlify.dev/guide/essentials/syntax.html)** by porting from `vue-i18n-next` |
| 134 | + - it use possible only Composition API mode |
| 135 | +- In Composition API mode, If you can use the following components, these can be referenced i18n resources, **only globally** |
| 136 | + - i18n functional component `<i18n>` |
| 137 | + - i18n-n functional component `<i18n-n>` |
| 138 | + |
| 139 | +### Explanation of Different Builds |
| 140 | +In the [dist/ directory of the npm package ](https://unpkg.com/browse/[email protected]/dist/) you will find many different builds of `vue-i18n-bridge`. Here is an overview of which dist file should be used depending on the use-case. |
| 141 | + |
| 142 | +#### From CDN or without a Bundler |
| 143 | + |
| 144 | +- **`vue-i18n-bridge(.runtime).global(.prod).js`**: |
| 145 | + - For direct use via `<script src="...">` in the browser. Exposes the `VueI18nBridge` global |
| 146 | + - In-browser message format compilation: |
| 147 | + - `vue-i18n-bridge.global.js` is the "full" build that includes both the compiler and the runtime so it supports compiling message formats on the fly |
| 148 | + - `vue-i18n-bridge.runtime.global.js` contains only the runtime and requires message formats to be pre-compiled during a build step |
| 149 | + - Inlines all Vue I18n core internal packages - i.e. it’s a single file with no dependencies on other files. This means you **must** import everything from this file and this file only to ensure you are getting the same instance of code |
| 150 | + - Contains hard-coded prod/dev branches, and the prod build is pre-minified. Use the `*.prod.js` files for production |
| 151 | + |
| 152 | +:::warning NOTICE |
| 153 | +Global builds are not [UMD](https://github.com/umdjs/umd) builds. They are built as [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) and are only meant for direct use via `<script src="...">`. |
| 154 | +::: |
| 155 | + |
| 156 | +- **`vue-i18n-bridge(.runtime).esm-browser(.prod).js`**: |
| 157 | + - For usage via native ES modules imports (in browser via `<script type="module">`) |
| 158 | + - Shares the same runtime compilation, dependency inlining and hard-coded prod/dev behavior with the global build |
| 159 | + |
| 160 | +#### With a Bundler |
| 161 | + |
| 162 | +- **`vue-i18n-bridge(.runtime).esm-bundler.js`**: |
| 163 | + - For use with bundlers like `webpack`, `rollup` and `parcel` |
| 164 | + - Leaves prod/dev branches with `process\.env\.NODE_ENV` guards (must be replaced by bundler) |
| 165 | + - Does not ship minified builds (to be done together with the rest of the code after bundling) |
| 166 | + - Imports dependencies (e.g. `@intlify/core-base`, `@intlify/message-compiler`) |
| 167 | + - Imported dependencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@intlify/message-compiler` imports `@intlify/shared`) |
| 168 | + - This means you **can** install/import these deps individually without ending up with different instances of these dependencies, but you must make sure they all resolve to the same version |
| 169 | + - In-browser locale messages compilation: |
| 170 | + - **`vue-i18n-bridge.runtime.esm-bundler.js`** is runtime only, and requires all locale messages to be pre-compiled. This is the default entry for bundlers (via `module` field in `package.json`) because when using a bundler templates are typically pre-compiled (e.g. in `*.json` files) |
| 171 | + - **`vue-i18n-bridge.esm-bundler.js` (default)**: includes the runtime compiler. Use this if you are using a bundler but still want locale messages compilation (e.g. templates via inline JavaScript strings). To use this build, change your import statement to: `import { createI18n } from "vue-i18n-bridge/dist/vue-i18n-bridge.esm-bundler.js";` |
| 172 | + |
| 173 | +:::warning NOTICE |
| 174 | +If you use `vue-i18n-bridge.runtime.esm-bundler.js`, you will need to precompile all locale messages, and you can do that with `.json` (`.json5`) or `.yaml`, i18n custom blocks to manage i18n resources. Therefore, you can be going to pre-compile all locale messages with bundler and the following loader / plugin. |
| 175 | + |
| 176 | +- [`@intlify/vite-plugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/vite-plugin-vue-i18n) |
| 177 | +- [`@intlify/vue-i18n-loader`](https://github.com/intlify/bundle-tools/tree/main/packages/vue-i18n-loader) |
| 178 | +- [`@intlify/rollup-plugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/rollup-plugin-vue-i18n) |
| 179 | +::: |
| 180 | + |
| 181 | +#### For Node.js (Server-Side) |
| 182 | + |
| 183 | +- **`vue-i18n-bridge.cjs(.prod).js`**: |
| 184 | + - For use in Node.js via `require()` |
| 185 | + - If you bundle your app with webpack with `target: 'node'` and properly externalize `vue-i18n-bridge`, this is the build that will be loaded |
| 186 | + - The dev/prod files are pre-built, but the appropriate file is automatically required based on `process\.env\.NODE_ENV` |
| 187 | + |
| 188 | + |
| 189 | +## `vue-i18n-composable` |
| 190 | + |
| 191 | +Composition API is supported from Vue 3, and you can use the official [`@vue/composition-api`](https://github.com/vuejs/composition-api) plugin to make the Composition API available to Vue 2. |
| 192 | + |
| 193 | +Vue I18n Composition API is also available in Vue 2 using the `vue-i18n-composable` plugin. |
| 194 | + |
| 195 | +About how to usage, See the [here](https://github.com/intlify/vue-i18n-composable) |
| 196 | + |
| 197 | +:::warning NOTICE |
| 198 | +`vue-i18n-composable` allows the main API of Vue I18n v8.x to work with the Composition API. All of Composition API provided in Vue I18n v9 are not available. |
| 199 | +::: |
0 commit comments