1 | # π vue-i18n-bridge
|
2 |
|
3 | A bridge for Vue I18n Legacy
|
4 |
|
5 | ## β What is `vue-i18n-bridge`?
|
6 |
|
7 | `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.
|
8 |
|
9 | It can be used in Vue 2 applications that you have already built with vue-i18n@v8.26.1 or later.
|
10 |
|
11 | And, also some features are backported from vue-i18n@v9.x:
|
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/vue@2.6"></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/composition-api@1.2"></script>
|
42 | <script src="https://unpkg.com/vue-i18n-bridge@9.2.0-beta.5/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 (vue-i18n@v9.x) 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 (vue-i18n@v9.x) 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 (vue-i18n@v9.x) 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/vue-i18n-bridge@9.2.0-beta.6/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 | > β οΈ NOTE:
|
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 | - **`vue-i18n-bridge(.runtime).esm-browser(.prod).js`**:
|
156 | - For usage via native ES modules imports (in browser via `<script type="module">`)
|
157 | - Shares the same runtime compilation, dependency inlining and hard-coded prod/dev behavior with the global build
|
158 |
|
159 | ### With a Bundler
|
160 |
|
161 | - **`vue-i18n-bridge(.runtime).esm-bundler.js`**:
|
162 | - For use with bundlers like `webpack`, `rollup` and `parcel`
|
163 | - Leaves prod/dev branches with `process.env.NODE_ENV` guards (must be replaced by bundler)
|
164 | - Does not ship minified builds (to be done together with the rest of the code after bundling)
|
165 | - Imports dependencies (e.g. `@intlify/core-base`, `@intlify/message-compiler`)
|
166 | - Imported dependencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@intlify/message-compiler` imports `@intlify/shared`)
|
167 | - 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
|
168 | - In-browser locale messages compilation:
|
169 | - **`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)
|
170 | - **`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";`
|
171 |
|
172 | > β οΈ NOTE:
|
173 | 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.
|
174 |
|
175 | - [`@intlify/vite-plugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/vite-plugin-vue-i18n)
|
176 | - [`@intlify/vue-i18n-loader`](https://github.com/intlify/bundle-tools/tree/main/packages/vue-i18n-loader)
|
177 | - [`@intlify/rollup-plugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/rollup-plugin-vue-i18n)
|
178 | :::
|
179 |
|
180 | ### For Node.js (Server-Side)
|
181 |
|
182 | - **`vue-i18n-bridge.cjs(.prod).js`**:
|
183 | - For use in Node.js via `require()`
|
184 | - If you bundle your app with webpack with `target: 'node'` and properly externalize `vue-i18n-bridge`, this is the build that will be loaded
|
185 | - The dev/prod files are pre-built, but the appropriate file is automatically required based on `process.env.NODE_ENV`
|
186 |
|
187 | ## Β©οΈ License
|
188 |
|
189 | [MIT](http://opensource.org/licenses/MIT)
|