vue-i18n-skilld

vue-i18n 11.4.12（Vue 3）

Vue.js 国际化插件。

• 同级依赖：vue ^3.0.0（package.json:44）。不支持 Vue 2；Vue 2 请使用 vue-i18n v8。
• Node 引擎版本：>= 22（package.json:47）。
• 对于 Nuxt 3，请使用 @nuxtjs/i18n，而不是直接安装此插件（https://vue-i18n.intlify.dev/guide/integrations/nuxt3.html）。

核心规则

1. 默认使用 Composition API 模式。 将 legacy: false 传给 createI18n，并使用 useI18n()。Legacy API 模式（legacy: true，默认值）在 v11 中已弃用，并将在 v12 中移除（dist/vue-i18n.d.ts:1728）。
2. 新代码中不要使用 v-t 指令。 它在 v11 中已弃用，并将在 v12 中移除（dist/vue-i18n.d.ts:2138）。请使用 t()、$t 或 <i18n-t> 组件。
3. tc 和 $tc 已不存在。 它们在 v11 中已移除；t/$t 通过复数选项处理复数形式（已验证：dist/vue-i18n.d.ts 中没有 tc 导出）。
4. 插值使用 {name} 语法。 v8 的取模 % 语法已在 v10 中移除（https://vue-i18n.intlify.dev/guide/migration/breaking10.html#drop-modulo-syntax）。
5. 从 v10 开始，消息默认在运行时编译（JIT）。 对于严格执行 CSP 的环境或追求最佳性能的场景，请使用 @intlify/unplugin-vue-i18n 预编译（https://vue-i18n.intlify.dev/guide/advanced/optimization.html）。
6. 使用 v-html 渲染消息时，切勿将用户输入插入消息中，除非设置了 escapeParameter: true；应翻译内容，不要拼接 HTML。

设置

// i18n.js
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false, // Composition API mode
  locale: 'ja',
  fallbackLocale: 'en',
  messages: {
    en: { message: { hello: 'hello world' } },
    ja: { message: { hello: 'こんにちは、世界' } }
  }
})

export default i18n

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'

createApp(App).use(i18n).mount('#app')

app.use(i18n) 会安装 $t/$d/$n/$rt 全局属性（globalInjection: true 时启用，默认为 true）、启用 useI18n，并全局注册 i18n-t、i18n-d、i18n-n（globalInstall: true 时启用，默认为 true；dist/vue-i18n.d.ts:1810-1822）。

在组件中翻译

<script setup>
import { useI18n } from 'vue-i18n'
const { t, locale } = useI18n()
</script>

<template>
  <h1>{{ t('message.hello') }}</h1>
  <p>{{ t('greeting', { name: 'Kyoko' }) }}</p>
  <p>{{ $t('message.hello') }}</p>
</template>

只能在 setup 内调用 useI18n()。否则会抛出错误：“Must be called at the top of a setup function”。

常见任务

复数形式。 消息：'no apples | one apple | {count} apples'（以竖线分隔的形式，根据当前语言环境的复数规则选择）。

t('apple', count, { count }) // or t('apple', { count }, choice)

自定义规则：在 Composer 选项中使用 pluralRules（Composition），或使用 pluralizationRules（Legacy）。

格式化日期和数字。

const { d, n } = useI18n()
d(new Date(), 'long') // named format from datetimeFormats option, else Intl fallback
n(1234567, 'currency') // named format from numberFormats option

插值组件。 使用 <i18n-t keypath="..." tag="p">，并为每个占位符提供插槽子项；参见组件。

切换语言环境。 在 Composer 中设置 locale.value = 'en'；同时更新文档的 lang 属性，并在 SSR 中处理 Accept-Language（https://vue-i18n.intlify.dev/guide/advanced/lazy.html）。

延迟加载语言环境。 使用动态 import()，并调用 setLocaleMessage / mergeLocaleMessage；参见优化。

类型安全的键

扩展全局 DefineLocaleMessage、DefineDateTimeFormat、DefineNumberFormat 接口，即可在 useI18n 中获得键补全和类型推断，无需使用泛型；参见 typescript。

注意事项

• useI18n({ messages: ... }) 会创建本地作用域；如果不设置 useScope: 'global'，本地消息不会与全局消息合并（https://vue-i18n.intlify.dev/guide/essentials/scope.html）。
• 在 Composition 模式下，模板中的 $t 需要设置 globalInjection: true（dist/vue-i18n.d.ts:1735-1746）。
• 缺少 locale 消息时，Vue 会发出警告，并将键本身作为回退值；可配置 missing/missingWarn/fallbackWarn 来控制提示。
• 链接消息（@:key）、字面量 { } 以及消息中的 @ | 都需要转义；参见 message-syntax。
• 在打包器项目中，不要从 vue-i18n/dist/* 等深层路径导入；请从包根路径导入，以便解析到正确的构建版本（package.json:63-83）。

迁移状态

变更	版本	操作
弃用旧版 API 模式	v11	在 v12 之前改为 legacy: false（dist/vue-i18n.d.ts:1728）
弃用 v-t 指令	v11	替换为 t()/$t/<i18n-t>（dist/vue-i18n.d.ts:2138）
移除 tc/$tc	v11	使用 t/$t 的复数选项
默认启用 JIT 消息编译	v10	对严格 CSP 进行预编译
移除 % 命名插值	v10	使用 {name}
更改 $t 位置参数重载	v10	通过选项对象传递复数形式

详情：migration。

参考资料

• composition-api：createI18n、useI18n、Composer 成员、作用域、区域设置切换
• message-syntax：插值、复数形式、关联消息、HTML 安全性
• components：i18n-t、i18n-n、i18n-d
• formats：日期时间和数字格式化、自定义格式定义
• typescript：架构类型、生成的区域设置类型
• optimization：摇树优化标志、预编译、延迟加载、dist 文件
• migration：v9、v10、v11 的破坏性变更和 v12 的移除项
• legacy-api：v11 中仍保留的旧版 API 模式接口

官方文档：https://vue-i18n.intlify.dev/ API 参考：https://vue-i18n.intlify.dev/api/general.html 变更日志（引用，未复制）：https://github.com/intlify/vue-i18n/blob/master/CHANGELOG.md