开始
- 如果使用模块系统 (例如通过 vue-cli)，则需要导入 Vue 和 VueI18n ，然后调用 Vue.use(VueI18n)。
格式化
- 在某些情况下，你可能希望将翻译呈现为 HTML 信息而不是静态字符串。
- 在你的网站上动态插入任意 HTML 可能非常危险，因为它很容易导致 XSS 攻击。
const messages = {
en: {
message: {
hello: 'hello <br> world'
}
}
}
- ICU 信息语法
- 注释：一种用于格式化和解析文本的语法
- 注释：例如，{gender, select, male {He} female {She} other {They}} will respond shortly. 这个信息可以根据gender的值选择不同的代词，如He will respond shortly.或She will respond shortly.
- 可以使用实现格式化接口的自定义格式化函数来实现
// 实现自定义格式
class CustomFormatter {
constructor (options) {
// ...
}
//
// 插值
//
// @param {string} 信息
// 列表或具名格式的字符串。
// 例如：
// - 具名格式：'Hi {name}'
// - 列表格式：'Hi {0}'
//
// @param {Object | Array} 值
// `message` 插值的值
// 使用 `$t`， `$tc` 和 `i18n` 函数式组件传递值。
// e.g.
// - $t('hello', { name: 'kazupon' }) -> 传递值：Object `{ name: 'kazupon' }`
// - $t('hello', ['kazupon']) -> 传递值：Array `['kazupon']`
// - `i18n` 函数式组件 (组件插值)
// <i18n path="hello">
// <p>kazupon</p>
// <p>how are you?</p>
// </i18n>
// -> 传递值：Array (included VNode):
// `[VNode{ tag: 'p', text: 'kazupon', ...}, VNode{ tag: 'p', text: 'how are you?', ...}]`
//
// @return {Array<any>}
// 插值，你需要返回以下内容：
// - 当使用 `$t` 或 `$tc` 数组中应该是字符串。
// - 当使用 `i18n` 函数式组件时 数组中应包含 VNode 对象。
//
interpolate (message, values) {
// 在这里实现插值逻辑
// ...
// 返回插值数组
return ['resolved message string']
}
}
// 注册 `formatter` 选项
const i18n = new VueI18n({
locale: 'en-US',
formatter: new CustomFormatter(/* 这里是构造函数选项 */),
messages: {
'en-US': {
// ...
},
// ...
}
})
// 启动!
new Vue({ i18n }).$mount('#app')
复数
- 定义具有管道 | 分隔符的语言环境，并在管道分隔符中定义复数
- 模板将需要使用 $tc() 而不是 $t()
const messages = {
en: {
car: 'car | cars',
apple: 'no apples | one apple | {count} apples'
}
}
<p>{{ $tc('car', 1) }}</p>
<p>{{ $tc('car', 2) }}</p>
<p>{{ $tc('apple', 0) }}</p>
<p>{{ $tc('apple', 1) }}</p>
<p>{{ $tc('apple', 10, { count: 10 }) }}</p>
- 无需明确指定复数的数字。可以通过预定义的命名参数 {count} 和/或 {n} 在语言环境信息中访问该数字。如有必要，你可以覆盖这些预定义的命名参数。
- 注释：$tc 会自动把第二个参数作为具名参数 count 或 n 传入语言环境信息
- 注释：$ts 提供了第3个，使用方式跟具名参数一致，优先级高于预定义的参数
const messages = {
en: {
apple: 'no apples | one apple | {count} apples',
banana: 'no bananas | {n} banana | {n} bananas'
}
}
<p>{{ $tc('banana', 1) }}</p>
<p>{{ $tc('banana', 100, { n: 'too many' }) }}</p>
<p>1 banana</p>
<p>too many bananas</p>
- 注释：默认规则
- 如果语言环境信息传入 2 个值，当传入 1 时采用第 1 个值，当传入大于 1 的值时采用第 2 个
- 如果语言环境信息传入 3 个值，当传入 0 时采用第 1 个值，当传入 1 时采用第 2 个值，其余采用第 3 个值
- $tc 的第 3 个参数优先级高于第 2 个参数
- 这种多元化并不适用于所有语言（例如，斯拉夫语言具有不同的多元化规则）
- 为了实现这些规则，您可以将可选的 pluralizationRules 对象传递给VueI18n 构造函数选项。
new VueI18n({
// Key - 在这种情况下，用于规则 `'ru'` 的语言
// Value - 选择正确的复数形式的功能
pluralizationRules: {
/**
* @param choice {number} 输入给$的选择索引 $tc：`$tc('path.to.rule', choiceIndex)`
* @param choicesLength {number} 可用选择总数
* @returns 最终选择索引以选择复数单词
*/
'ru': function(choice, choicesLength) {
// this === VueI18n 实例，因此本地属性也存在于此
if (choice === 0) {
return 0;
}
const teen = choice > 10 && choice < 20;
const endsWithOne = choice % 10 === 1;
if (choicesLength < 4) {
return (!teen && endsWithOne) ? 1 : 2;
}
if (!teen && endsWithOne) {
return 1;
}
if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
return 2;
}
return (choicesLength < 4) ? 2 : 3;
}
}
})
日期时间本地化
const dateTimeFormats = {
'en-US': {
short: {
year: 'numeric',
month: 'short',
day: 'numeric'
},
long: {
year: 'numeric',
month: 'long',
day: 'numeric',
weekday: 'long',
hour: 'numeric',
minute: 'numeric'
}
},
'ja-JP': {
short: {
year: 'numeric',
month: 'short',
day: 'numeric'
},
long: {
year: 'numeric',
month: 'long',
day: 'numeric',
weekday: 'long',
hour: 'numeric',
minute: 'numeric',
hour12: true
}
}
}
const i18n = new VueI18n({
dateTimeFormats
})
<div id="app">
<p>{{ $d(new Date(), 'short') }}</p>
<p>{{ $d(new Date(), 'long', 'ja-JP') }}</p>
</div>
<div id="app">
<p>Jan 18, 2021</p>
<p>2021年1月18日日曜日 午前5:47</p>
</div>
- 你可以定义具名的 (例如：short、long 等) 日期时间格式，并需要使用 ECMA-402 Intl.DateTimeFormat 的选项
- 注释：Intl 对象是 ECMAScript 国际化 API 的一个命名空间，它提供了精确的字符串对比、数字格式化，和日期时间格式化。
- 注释：不同语言对字母的大小写敏感程度不同，所以字符串对比需要国际化，英语中字母A和a是大小写不敏感的，即A == a，但是德语中字母A和a是大小写敏感的，即A != a
- 注释：不同语言对数字的格式标识不同，法语中数字123456.78用空格作为千分位分隔符，用逗号作为小数点
数字本地化
const numberFormats = {
'en-US': {
currency: {
style: 'currency',
currency: 'USD'
}
},
'ja-JP': {
currency: {
style: 'currency',
currency: 'JPY',
currencyDisplay: 'symbol'
}
}
}
const i18n = new VueI18n({
numberFormats
})
<div id="app">
<p>{{ $n(100, 'currency') }}</p>
<p>{{ $n(100, 'currency', 'ja-JP') }}</p>
</div>
<div id="app">
<p>$100.00</p>
<p>￥100</p>
</div>
- $n 方法返回的结果字符串带有完全格式化的数字，该数字只能作为整体使用。 在需要格式化格式化数字的某些部分（例如小数位）的情况下，$n 是不够的。 在这种情况下，<i18n-n> 功能组件将有所帮助。
- 假设需要用较粗的字体呈现数字的整数部分。 这可以通过指定 integer 作用域的插槽元素来实现：
- 可以通过指定 tag 属性来选择根容器的节点类型。 如果省略，则默认为 'span'。 您也可以将其设置为布尔值 false 以直接插入子节点，而无需创建根元素
<i18n-n :value="1234" :format="{ key: 'currency', currency: 'EUR' }" locale="ja-JP">
<span v-slot:currency="slotProps" styles="color: green">{{ slotProps.currency }}</span>
<span v-slot:integer="slotProps" styles="font-weight: bold">{{ slotProps.integer }}</span>
<span v-slot:group="slotProps" styles="font-weight: bold">{{ slotProps.group }}</span>
<span v-slot:fraction="slotProps" styles="font-size: small">{{ slotProps.fraction }}</span>
</i18n-n>
语言环境信息的语法
{
"en": { // 'en' Locale
"key1": "this is message1", // 基本的
"nested": { // 嵌套
"message1": "this is nested message1"
},
"errors": [ // 数组
"this is 0 error code message",
{ // 数组嵌套对象
"internal1": "this is internal 1 error message"
},
[ // 数组嵌套数组
"this is nested array error 1"
]
]
},
"ja": { // 'ja' Locale
// ...
}
}
- 如果有一个翻译关键字总是与另一个具有相同的具体文本，你可以链接到它。要链接到另一个翻译关键字，你所要做的就是在其内容前加上一个 @: 符号后跟完整的翻译键名，包括你要链接到的命名空间。
const messages = {
en: {
message: {
the_world: 'the world',
dio: 'DIO:',
linked: '@:message.dio @:message.the_world !!!!'
}
}
}
- 如果语言区分字符大小写，则可能需要控制链接的语言环境消息的大小写。 链接的消息可以用修饰符 @.modifier:key 格式化。
- upper: 链接消息中的所有字符均大写
- lower: 小写链接消息中的所有字符
- capitalize: 大写链接消息中的第一个字符
const messages = {
en: {
message: {
homeAddress: 'Home address',
missingHomeAddress: 'Please provide @.lower:message.homeAddress'
}
}
}
- 可以添加修饰符或覆盖将 modifiers 选项传递给 VueI18n 构造函数的现有修饰符。
const i18n = new VueI18n({
locale: 'en',
modifiers: {
snakeCase: (str) => str.split(' ').join('-')
},
messages: {
// ...
},
})
- 链接到的语言环境信息的键名也可以形如 @:(message.foo.bar.baz)，其中链接到另一段翻译的键名在括号 () 里
- 如果链接 @:message.something 后紧跟着一个点 .，则此选项非常有用，因为它本不该成为但却成为了链接的一部分
const messages = {
en: {
message: {
dio: 'DIO',
linked: 'There\'s a reason, you lost, @:(message.dio).'
}
}
}
- 由于复杂的语言语法，您确实需要JavaScript的全部编程功能。 因此，您可以使用 message function 来代替基于字符串的消息。
const messages = {
en: {
greeting: (ctx) => `hello, ${ctx.named('name')}!`
}
}
<p>{{ $t('greeting', { name: 'DIO' }) }}</p>
const messages = {
en: {
greeting: (ctx) => `hello, ${ctx.list(0)}!`
}
}
<p>{{ $t('greeting', ['DIO']) }}</p>
- 在消息功能中，以下基于字符串提供的功能无法通过消息上下文使用：
回退本地化
- 如果给出的 locale 包含领土和可选的方言，则隐式回退将自动激活
- 对于 de-DE-bavarian，以下内容将被视为备用：
- de-DE-Bavarian
- de-DE
- de
- 要禁止自动回退，请添加后缀感叹号 !，例如 de-DE!
- 默认情况下回退到 fallbackLocale 会产生两个控制台警告：
- 为了避免这些警告 (同时保留那些完全没有翻译给定关键字的警告)，需初始化 VueI18n 实例时设置 silentFallbackWarn：true
- 注释：旧版本 silentTranslationWarn: true 用于关闭警告
const i18n = new VueI18n({
locale: 'ja',
fallbackLocale: 'en',
messages
})
- 由于翻译的键值是字符串，因此也可以作为翻译的值：
- 为了实现此功能，可以通过设置formatFallbackMessages为true
- 注释：同样支持具名格式，感觉应该也支持链接
- fallbackRoot的优先级高于formatFallbackMessages
- 注释：fallbackRoot 在组件本地化中，当本地化失败时是否回退到根级别 (全局) 本地化。如 locale: ‘en’ 表示使用 messages.en 作为根级别本地化
const messages = {
ru: {
'Hello {name}': 'Здравствуйте {name}'
}
}
const i18n = new VueI18n({
locale: 'ru',
fallbackLocale: 'en',
formatFallbackMessages: true,
messages
})
<p>{{ $t('Hello {name}', { name: 'John' }}) }}</p>
<p>{{ $t('The weather today is {condition}!', { condition: 'sunny' }) }}</p>
<p>Здравствуйте John</p>
<p>The weather today is sunny!</p>
基于组件的本地化
- 面向 Vue 组件的设计，你也可以更方便的分别控制每个组件的语言环境信息
const Component1 = {
template: `
<div class="container">
<p>Component1 locale messages: {{ $t("message.hello") }}</p>
<p>Fallback global locale messages: {{ $t("message.greeting") }}</p>
</div>`,
i18n: { // `i18n` 选项，为组件设置语言环境信息
messages: {
en: { message: { hello: 'hello component1' } },
ja: { message: { hello: 'こんにちは、component1' } }
}
}
}
- 如果组件没有语言环境信息，它将回退到全局定义的本地化信息。
- 在默认情况下，回退到根语言环境会在控制台中生成两个警告
- 为避免以上警告 (同时保留那些完全没有翻译给定关键字的警告) 需初始化 VueI18n 实例时设置 silentFallbackWarn：true
- 如果你希望在组件语言环境中进行本地化，可以在 i18n 选项中用 sync: false 和 locale
- 为某些组件导入共享的语言环境消息
- 如果将 sharedMessages 选项与 messages 选项一起指定，则这些消息将被合并为语言环境消息，并进入目标组件的VueI18n实例
// locales/common.js
export default {
en: {
buttons: {
save: "Save",
// ...
}
},
ja: {
buttons: {
save: "保存",
// ...
}
}
}
import commonMessage from './locales/common' // 导入通用语言环境消息
export default {
name: 'ServiceModal',
template: `
<div class="modal">
<div class="body">
<p>This is good service</p>
</div>
<div class="footer">
<button type="button">
{{ $t('buttons.save') }}
</button>
</div>
</div>
`,
i18n: {
messages: { ... },
sharedMessages: commonMessages
}
}
- 在函数式组件上使用 vue-i18n 时，你必须将 $t 称为 parent.$t
自定义指令本地化
<div id="string-syntax">
<!-- 字符串 -->
<p v-t="'hello'"></p>
<!-- 通过数据进行键名路径绑定 -->
<p v-t="path"></p>
</div>
<div id="object-syntax">
<!-- 文字 -->
<p v-t="{ path: 'hello', locale: 'ja', args: { name: 'kazupon' } }"></p>
<!-- 通过 `data` 绑定数据 -->
<p v-t="{ path: path, args: { name: nickName } }"></p>
</div>
- 在过渡开始之前 ，<transition> 组件内消失元素中的所有指令都将被销毁。此行为可能导致内容在短过渡时闪烁，但在长过渡时最明显。
- 为了确保在转换期间指令内容不会被触及，只需将.preserve 修饰符添加到 v-t 指令定义中
- 也可以在 VueI18n 实例本身设置全局设置 preserveDirectiveContent: true，这将对没有修饰符的所有 v-t 指令产生影响
<div id="in-transitions">
<transition name="fade">
<span v-if="toggle" v-t.preserve="'preserve'"></span>
</transition>
<button @click="toggle = !toggle">Toggle</button>
</div>
// 或者
new Vue({
i18n: new VueI18n({
locale: 'en',
messages: {
en: { preserve: 'with preserve' },
},
preserveDirectiveContent: true
}),
data: { toggle: true }
}).$mount('#in-transitions')
- $t 在每次重新渲染时都会被执行，因此它确实有翻译成本。
- v-t 比 $t 方法具有更好的性能，因为在一次翻译时自定义指令会进行缓存。此外可以使用由 vue-i18n-extensions 提供的 Vue 编译器模块进行预翻译。
- 注释：vue-i18n-extensions 是一个为vue-i18n提供扩展功能的插件，它主要有两个特点：服务器端渲染（SSR）支持v-t自定义指令。在构建时将语言包中的文本资源翻译成目标语言，并生成新的语言包文件，从而减少运行时的翻译开销和网络请求。
- 使用服务器渲染时，你需要设置自定义指令到 createRenderer 函数的 directives 选项。
- v-t 的翻译内容会被插入到元素的 textContent 中
组件插值
- 使用了 v-html="$t('term')" 进行本地化而存在被 XSS 攻击的可能性
- 可以使用 i18n 函数式组件来避免它
- 组件插值遵循列表格式。i18n 函数式组件的子项按其出现顺序进行插值。
<div id="app">
<!-- ... -->
<i18n path="term" tag="label" for="tos">
<a :href="url" target="_blank">{{ $t('tos') }}</a>
</i18n>
<!-- ... -->
</div>
const messages = {
en: {
tos: 'Term of Service',
term: 'I accept xxx {0}.'
},
}
<div id="app">
<!-- ... -->
<label for="tos">
I accept xxx <a href="/term" target="_blank">Term of Service</a>.
</label>
<!-- ... -->
</div>
单文件组件
- 为了使用 <i18n> 自定义块，你需要安装 vue-i18n-loader
- 注释：vue-i18n-loader 在打包工具的配置方法
- 注释：Laravel-Mix 一个用于Laravel应用的webpack封装工具，它可以让你用简洁的语法来定义你的前端资源的编译和压缩步骤
- i18n 自定义块需要指定为 JSON 格式，你也可以通过使用 vue-loader 预加载器功能来使用 YAML 格式。
<i18n>
{
"en": {
"hello": "hello world!"
},
"ja": {
"hello": "こんにちは、世界！"
}
}
</i18n>
- 可以使用具有多个 i18n 自定义块的语言环境信息。
<i18n src="./common/locales.json"></i18n>
<i18n>
{
"en": {
"hello": "hello world!"
},
"ja": {
"hello": "こんにちは、世界！"
}
}
</i18n>
- 当使用带有 scoped style vue-i18n 时，重要的是要记住使用深度选择器 (opens new window)来设置嵌套转换的样式。
<i18n>
{
"en": {
"hello": "hello<span>world!</span>"
},
}
</i18n>
<template>
<div class="parent">
<p v-html="$t('hello')"></p>
</div>
</template>
<!-- 可行 ::v-deep -->
<style scoped>
.parent p {
color: #42b883;
}
::v-deep .parent p span {
color: red;
}
</style>
- 如果单个文件组件具有使用函数式组件的模板，并且你已经定义了 i18n 自定义块，请注意你无法使用语言环境信息进行本地化。
<i18n>
{
"en": {
"hello": "hello world"
},
"ja": {
"hello": "こんにちは、世界"
}
}
</i18n>
<template functional>
<!-- 'hello' 的父实例的语言环境信息 -->
<p>{{ parent.$t('hello') }}</p>
</template>
热重载
语言环境变更
- 动态更改语言环境。在这种情况下，你可以更改 VueI18n 实例的 locale 属性的值
- 每个组件都包含一个引用为 $i18n 属性的 VueI18n 实例，该实例也可用于更改语言环境。
const i18n = new VueI18n({
locale: 'ja', // 设置语言环境
...
})
// 更改为其它的 locale
i18n.locale = 'en'
延迟加载翻译
//i18n-setup.js
import Vue from 'vue'
import VueI18n from 'vue-i18n'
import messages from '@/lang/en'
import axios from 'axios'
Vue.use(VueI18n)
export const i18n = new VueI18n({
locale: 'en', // 设置语言环境
fallbackLocale: 'en',
messages // 设置语言环境信息
})
const loadedLanguages = ['en'] // 我们的预装默认语言
function setI18nLanguage (lang) {
i18n.locale = lang
axios.defaults.headers.common['Accept-Language'] = lang
document.querySelector('html').setAttribute('lang', lang)
return lang
}
export function loadLanguageAsync(lang) {
// 如果语言相同
if (i18n.locale === lang) {
return Promise.resolve(setI18nLanguage(lang))
}
// 如果语言已经加载
if (loadedLanguages.includes(lang)) {
return Promise.resolve(setI18nLanguage(lang))
}
// 如果尚未加载语言
return import(/* webpackChunkName: "lang-[request]" */ `@/i18n/messages/${lang}.js`).then(
messages => {
i18n.setLocaleMessage(lang, messages.default)
loadedLanguages.push(lang)
return setI18nLanguage(lang)
}
)
}
工具
- vue-cli-plugin-i18n是官方提供的 Vue Cli 插件。
- eslint-plugin-vue-i18n 是为 Vue I18n 编写的 ESLint 插件。
- BabelEdit可以翻译 json 文件，也可以翻译单文件组件的 i18n 自定义块。
- 注释：BabelEdit可以让你在一个友好的界面中管理和修改你的翻译文件，无需手动编辑JSON代码
- i18n Ally是 VSCode 的 i18n 扩展。
- vue-i18n-extract对基于 vue-i18n 的 Vue.js 项目执行静态分析，并报告以下信息：
- 注释：一个工具包，提供了命令来实现以下功能
- 所有 未使用的 vue-i18n 键的列表（在语言文件中找到但在项目中未使用的条目）
- 所有 缺失键 的列表（在项目中使用但在语言文件中不存在的条目）
- 可以在控制台中显示输出或将其写入json文件
- 丢失的键也可以自动添加到给定的语言文件中
——————————
i18n-ally
- 可以设置当前文件 key 对应显示的语言
- 悬浮窗显示 key 对应的所有语言的值、自动翻译、编辑、跳到文件
- 左侧菜单栏统一管理
- CURRENT FILE：当前文件使用了哪些 key
- PROGRESS：整个项目每种语言的完成情况
- TREE：树形结构的语言信息
- USAGE REPORT：使用情况报告
- HELP & FEEDABCK：帮助和反馈
- 可视化编辑器：针对某个 key 所有语言的编辑
- 如果你更喜欢将此编辑器用于大部分工作，而不是 VS Code 提供的接口，则可以设置
"i18n-ally.editor.preferEditor": true
- 审阅系统
- 对某个 key 的反应提出修改请求和建议
- 审阅注释将存储在 .vscode/i18n-ally-reviews.yml 中
- 默认情况下，您的姓名和电子邮件是从本地 git 设置中读取的。您可以通过以下方式更改它们
"i18n-ally.review.user.name": "Your Name","i18n-ally.review.user.email": "hi@example.com"
- 如果您希望再有一层控制机器翻译的内容，您可以通过以下方式启用翻译候选系统
- 使用候译版本，您可以在将译文写入区域设置文件之前查看和编辑译文。
"i18n-ally.translate.saveAsCandidates": true,
- 从代码中提取翻译：选择一段文本直接插入语言文件
- 在 vscode 控制台的问题 tab 报告缺少的翻译
- 弹窗提供机器翻译
- 支持 JSON 和 YAML 文件的注释？
- 支持多根工作区
- 支持远程开发？vscode支持远程开发
- 支持众多流行的框架
- 支持语言信息中进行链接
浙公网安备 33010602011771号