vue-i18n-skilld

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vue-i18n 11.4.12 (Vue 3)

Internationalization plugin for Vue.js.

Peer dependency:
```
vue
```
```
^3.0.0
```
(package.json:44). No Vue 2 support; use vue-i18n v8 for Vue 2.
Node engines:
```
>= 22
```
(package.json:47).
For Nuxt 3, use
```
@nuxtjs/i18n
```
instead of installing this directly (https://vue-i18n.intlify.dev/guide/integrations/nuxt3.html).

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）。

Core rules

核心规则

Default to Composition API mode. Pass
```
legacy: false
```
to
```
createI18n
```
and use
```
useI18n()
```
. Legacy API mode (
```
legacy: true
```
, the default) is deprecated in v11 and removed in v12 (dist/vue-i18n.d.ts:1728).
Do not use the
v-t
directive in new code. Deprecated in v11, removed in v12 (dist/vue-i18n.d.ts:2138). Use
```
t()
```
,
```
$t
```
, or the
```
<i18n-t>
```
component.
tc
and
$tc
no longer exist. Dropped in v11;
```
t
```
/
```
$t
```
handle pluralization via the plural option (verified: no
```
tc
```
export in dist/vue-i18n.d.ts).
Interpolation uses
{name}
syntax. The v8 modulo
```
%
```
syntax was dropped in v10 (https://vue-i18n.intlify.dev/guide/migration/breaking10.html#drop-modulo-syntax).
Messages are compiled at runtime (JIT) by default since v10. For CSP-strict environments or best performance, pre-compile with
```
@intlify/unplugin-vue-i18n
```
(https://vue-i18n.intlify.dev/guide/advanced/optimization.html).
Never interpolate user input into messages rendered with
v-html
without
```
escapeParameter: true
```
; translate content, do not concatenate HTML.

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

Setup

设置

// 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)

installs the

$t

$d

$n

$rt

global properties (when

globalInjection: true

, the default), enables

useI18n

, and globally registers

i18n-t

i18n-d

i18n-n

(when

globalInstall: true

, the default; dist/vue-i18n.d.ts:1810-1822).

// 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

时，默认启用），启用

useI18n

，并全局注册

i18n-t

、

i18n-d

、

i18n-n

（当

globalInstall: true

时，默认启用；dist/vue-i18n.d.ts:1810-1822）。

Translate in a component

在组件中翻译

vue

<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><!-- works in templates via globalInjection -->
</template>

Call

useI18n()

inside

setup

only. It throws "Must be called at the top of a

setup

function" otherwise.

vue

<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><!-- works in templates via globalInjection -->
</template>

只能在

setup

内部调用

useI18n()

。否则会抛出 "Must be called at the top of a

setup

function"。

Common tasks

常见任务

Pluralize. Message:

'no apples | one apple | {count} apples'

(pipe-separated forms, selected by plural rules for the locale).

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

Custom rules:

pluralRules

Composer

options (Composition),

pluralizationRules

(Legacy).

Format dates and numbers.

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

Interpolate components. Use

<i18n-t keypath="..." tag="p">

with slot children per placeholder; see components.

Switch locale.

locale.value = 'en'

from a Composer; also update the document

lang

attribute and, on SSR, the

Accept-Language

handling (https://vue-i18n.intlify.dev/guide/advanced/lazy.html).

Lazy load locales. Dynamic

import()

plus

setLocaleMessage

mergeLocaleMessage

; see optimization.

复数化。 消息：

'no apples | one apple | {count} apples'

（使用竖线分隔各种形式，并根据 locale 的复数规则进行选择）。

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

自定义规则：Composition 模式在

Composer

选项中使用

pluralRules

，Legacy 模式使用

pluralizationRules

。

格式化日期和数字。

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">

，并通过 slot 子节点提供各占位符对应的内容；请参阅组件。

切换 locale。 通过 Composer 设置

locale.value = 'en'

；同时更新文档的

lang

属性。在 SSR 环境中，还需要处理

Accept-Language

（https://vue-i18n.intlify.dev/guide/advanced/lazy.html）。

懒加载 locale。 使用动态

import()

，配合

setLocaleMessage

mergeLocaleMessage

；请参阅优化。

Type-safe keys

类型安全的键

Augment the global

DefineLocaleMessage

DefineDateTimeFormat

DefineNumberFormat

interfaces to get key completion and inference in

useI18n

without generics; see typescript.

扩展全局

DefineLocaleMessage

、

DefineDateTimeFormat

、

DefineNumberFormat

接口，无需使用泛型即可在

useI18n

中获得键补全和类型推断；请参阅 TypeScript。

Pitfalls

常见问题

```
useI18n({ messages: ... })
```
creates a local scope; without
```
useScope: 'global'
```
local messages do not merge with global ones (https://vue-i18n.intlify.dev/guide/essentials/scope.html).
```
$t
```
in templates requires
```
globalInjection: true
```
in Composition mode (dist/vue-i18n.d.ts:1735-1746).
Vue warns about a missing
```
locale
```
message with key fallback to the key itself; configure
```
missing
```
/
```
missingWarn
```
/
```
fallbackWarn
```
to control noise.
Linked messages (
```
@:key
```
), literal
```
{
```
```
}
```
, and
```
@
```
```
|
```
in messages need escaping; see message-syntax.
Do not import from deep paths such as
```
vue-i18n/dist/*
```
in bundler projects; use the package root so the correct build resolves (package.json:63-83).

```
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
```
）以及消息中的字面量
```
{
```
```
}
```
、
```
@
```
、
```
|
```
需要转义；请参阅消息语法。
在打包项目中，不要从
```
vue-i18n/dist/*
```
等深层路径导入；应从包根目录导入，以确保正确解析对应的构建产物（package.json:63-83）。

Migration status

迁移状态

Change	Version	Action
Legacy API mode deprecated	v11	Move to `legacy: false` before v12 (dist/vue-i18n.d.ts:1728)
`v-t` directive deprecated	v11	Replace with `t()` / `$t` / `<i18n-t>` (dist/vue-i18n.d.ts:2138)
`tc` / `$tc` removed	v11	Use `t` / `$t` plural option
JIT message compilation default	v10	Pre-compile for strict CSP
`%` named interpolation removed	v10	Use `{name}`
`$t` positional overload changed	v10	Pass plural via options object

Details: migration.

变更	版本	操作
Legacy 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` 的 plural 选项
默认启用 JIT 消息编译	v10	为严格 CSP 环境进行预编译
已移除 `%` 命名插值	v10	使用 `{name}`
`$t` 位置参数重载发生变化	v10	通过选项对象传入复数选项

详细信息：迁移。

References

参考资料

composition-api: createI18n, useI18n, Composer members, scopes, locale switching
message-syntax: interpolation, pluralization, linked messages, HTML safety
components: i18n-t, i18n-n, i18n-d
formats: datetime and number formatting, custom format definitions
typescript: schema typing, generated locale types
optimization: tree shaking flags, pre-compilation, lazy loading, dist files
migration: v9, v10, v11 breaking changes and v12 removals
legacy-api: Legacy API mode surface still present in v11

Official documentation: https://vue-i18n.intlify.dev/ API reference: https://vue-i18n.intlify.dev/api/general.html Changelog (cited, not copied): https://github.com/intlify/vue-i18n/blob/master/CHANGELOG.md

composition-api：createI18n、useI18n、Composer 成员、作用域、locale 切换
message-syntax：插值、复数化、链接消息、HTML 安全
components：i18n-t、i18n-n、i18n-d
formats：日期时间和数字格式化、自定义格式定义
typescript：模式类型定义、生成的 locale 类型
optimization：tree shaking 标志、预编译、懒加载、dist 文件
migration：v9、v10、v11 的破坏性变更和 v12 的移除项
legacy-api：v11 中仍然保留的 Legacy 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