# @cepharum/vue3-i18n 中文文档

规范地址：https://npmcn.com/package/%40cepharum/vue3-i18n/

版本：3\.0\.1
npm 元数据更新时间：2026-11-01T13:05:43.790Z
中文译文更新时间：2026-11-09T07:58:19.151Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cepharum/vue3-i18n
原文对照：https://npmcn.com/package/%40cepharum/vue3-i18n/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：140 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.13
- 运行依赖：0 个
- peer 依赖：vue 3
- 首次发布：2023-06-03T20:34:12.214Z
- 最新版本发布：2026-11-01T13:05:43.606Z
- 近 30 天下载量：5943（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 4 个）

## 中文简介

vue3 应用程序的简单 i18n 库

## 安装

```sh
npm install @cepharum/vue3-i18n
```

也可以使用：`pnpm add @cepharum/vue3-i18n`、`yarn add @cepharum/vue3-i18n`、`bun add @cepharum/vue3-i18n`

## README

# @cepharum/vue3-i18n (英语)

vue3 应用程序的简单 i18n 库

## 许可证

[麻省理工学院](https://npmcn.com/package/%40cepharum/vue3-i18n/LICENSE)

## 警卫

报告可疑弱点 [安全性@ cepharum.de](mailto:security@cepharum.de) 而不是在公众中 问题。 见 [警卫](https://npmcn.com/package/%40cepharum/vue3-i18n/SECURITY.md) 政策、支持的版本和 图书馆攻击表面的笔记.

## 法学硕士和法学硕士

该存储库包括为AI助理设计的全面文件:

-   **[阿根特·姆德(签名)](https://npmcn.com/package/%40cepharum/vue3-i18n/AGENT.md)** - 涵盖全部API、结构和使用模式的详细技术文件
-   **[QUICK START.md (中文(简体) )](https://npmcn.com/package/%40cepharum/vue3-i18n/QUICK_START.md)** - 附有表格和简明实例的快速参考指南

这些文件的结构是专门用来帮助LLMs理解这个库是如何工作的,以及如何在消耗应用程序时使用它.

## 关于

这个库执行一个组件和帮助器功能,将国际化的密钥被动地映射成本地化字符串,其基础是每个地方翻译的分级树,每个都作为普通Javascript对象执行,例如从JSON文件中读取.

它支持数据内插和一些有限的Markdown语法用于样式翻译.

由于其反应性方法,所有翻译都自动得到更新,比如在切换地语和获取其一组翻译时. 要使用的语言由当前文档或浏览器自动读取. 从文档或浏览器读取的自定义地块可以被明确选中来覆盖地块.

## 所需资源

节点18.13+或常绿浏览器. 图书馆以运行时间为基础 `Intl` API - (英语) `PluralRules` 包括 `selectRange`, (中文(简体) ), `NumberFormat`, (中文(简体) ), `DateTimeFormat`, (中文(简体) ), `RelativeTimeFormat`, (中文(简体) ), `ListFormat` 财务报告和审定财务报表 `Locale` - 和船舶 **无运行时间 依赖关系** 属于自己的。 Vue 3是同级依赖.

## 安装

在耗用 Vue3 工程中, 此库是使用 npm 这样安装的 :

```bash
npm install @cepharum/vue3-i18n
```

## 使用量

您必须提供翻译的加载器 。 它应尽早建立起来,例如将您的项目的根视图安装在 **src/App.vue (英语)** 组件.

```vue
<script setup>
import { useL10n } from "@cepharum/vue3-i18n";

useL10n().setLoader( locale => import(`./l10n/${locale}.json`) );
</script>
```

创建文件夹 **锡克/l10nn** 在您的工程中设置一个文件名 **en.json (英语)** 在这里。 它将提供所有这样的翻译:

```json
{
  "COMMON": {
    "confirm": "Okay",
    "cancel": "Cancel"
  },
  "FEATURE": {
    "title": "Info",
    "text": "This is the feature!"
  }
}
```

使用此库的组件 `<L10n>` 将文本:

```vue
<script setup>
import { L10n } from "@cepharum/vue3-i18n";
</script>

<template>
  <h1><L10n i18n="FEATURE.title" /></h1>
  <p><L10n i18n="FEATURE.text" /></p>
  <button><L10n i18n="COMMON.confirm" /></button>
</template>
```

### 虚拟新闻

在维特普雷斯 [必须扩展默认主题](https://vitepress.dev/guide/extending-default-theme#registering-global-components) 或一个 [必须设置自定义主题](https://vitepress.dev/guide/extending-default-theme#registering-global-components) 登记 **vue3-i18n (英语)**在文件中 **.vitepress/主题/索引.js**,方法增强App必须扩展:

```javascript
import { L10n, useL10n } from "@cepharum/vue3-i18n";

enhanceApp( ctx ) {
    const l10n = useL10n();

    // set up loader for fetching translations per locale
    l10n.setLoader( locale => import( ( `./l10n/${locale}.json` ) ) );
    
    // globally register L10n component for use in content pages
    ctx.app.component( "L10n", L10n );
}
```

每个地方的翻译文件预计将存放在文件夹中 **.视频/主题/l10n** 在这里.

> 在v0.5.0之前的版本中,必须明确设置文件的地块观察员. 从v0.5.0开始,观察员自动设置.

### 更多信息

有关该图书馆如何运作的详细文件见:

-   **[阿根特·姆德(签名)](https://npmcn.com/package/%40cepharum/vue3-i18n/AGENT.md)** - 完整的技术文件
-   **[QUICK START.md (中文(简体) )](https://npmcn.com/package/%40cepharum/vue3-i18n/QUICK_START.md)** - 快速参考指南

### 插件

从v. 4.1开始,可以注册单独的加载器来提供专用命名空间的翻译. 这使得基于 Vue3 的应用程序能够提供自己的子集翻译的国际化插件.

```javascript
// in a plugin's setup code:
import { L10n, useL10n } from "@cepharum/vue3-i18n";

const l10n = useL10n();

// set up loader for fetching plugin's translations per locale
l10n.setNamespaceLoader( "@my-plugin", locale => import( ( `./l10n/${locale}.json` ) ) );
```

在此,命名空间是非空白字符串,其前缀为 `@`。由命名空间加载器获取的所有翻译的密钥都会自动被前缀该命名空间。 例如,一个翻译文件可能像这样:

```json
{
  "FOO": {
    "bar": "translated"
  }
}
```

要查找它, 命名空间必须在插件代码中预留 :

```javascript
const translation = useL10n().lookup( "@my-plugin.FOO.bar" );
```

通过 `setLoader()` 不受此自动前缀的影响。 因此,它也可以为任一命名空间提供自定义翻译。 为此,常规加载器总是在编译一个地语系的一组译名后最后处理.

### 内插

您可以在翻译中使用附加标记来取自附加数据对象的值来替换。 翻译可以像这样:

```json
{
  "COMMON": {
    "confirm": "Okay",
    "cancel": "Cancel"
  },
  "FEATURE": {
    "title": "About {mode.label}",
    "text": "This is the feature!"
  }
}
```

`<L10n>` 组件支持另一个属性 `data` 接受一些带有与上面卷曲括号所包裹的名称相匹配的属性的对象 :

```vue
<script setup>
import { ref } from "vue";
import { L10n } from "@cepharum/vue3-i18n";

const data = ref({
    mode: {
        label: "Interpolation",
    },
});
</script>

<template>
  <h1><L10n i18n="FEATURE.title" :data="data" /></h1>
  <p><L10n i18n="FEATURE.text" /></p>
  <button><L10n i18n="COMMON.confirm" /></button>
</template>
```

`data` 联 合 国 `<L10n>` 接受一个函数,在每次更新时都会被引用以获取实际数据:

```vue
<script setup>
import { L10n } from "@cepharum/vue3-i18n";

const data = () => ({
  mode: {
    label: "Interpolation",
  },
});
</script>

<template>
  <h1><L10n i18n="FEATURE.title" :data="data" /></h1>
  <p><L10n i18n="FEATURE.text" /></p>
  <button><L10n i18n="COMMON.confirm" /></button>
</template>
```

组件使生成的翻译不包含任何 HTML 元素,除非 [已启用标记下支持](https://npmcn.com/package/%40cepharum/vue3-i18n/#readme-markdown)通过设定可选财产 `tag` 转到 HTML 元素的名称,翻译为 _永远_ 用这个名字的元素包裹 以下例子产出与上一个相同:

```vue
<script setup>
import { L10n } from "@cepharum/vue3-i18n";

const data = () => ({
  mode: {
    label: "Interpolation",
  },
});
</script>

<template>
  <L10n i18n="FEATURE.title" :data="data" tag="h1" />
  <L10n i18n="FEATURE.text" tag="p"/>
  <L10n i18n="COMMON.confirm" tag="button" />
</template>
```

### 甄选:复数、性别和以后

译出不必为一一串. 也许是 **选择 节点** 根据插入数据从几个分支中选择一个. 这就是语法不正确的翻译方式 遵循德国模式.

#### 多元

写出分枝,匹配的分枝按照 QQR 规则选择 名称:

```json
{
  "FILES": {
    "removed": {
      "one": "{count} file removed",
      "other": "{count} files removed"
    }
  }
}
```

```vue
<L10n i18n="FILES.removed" :data="{ count: numFiles }" />
```

不需要控制密钥:如果一个复数选择是全部选择的节点 密钥是 QQR 复数类 (`zero`, (中文(简体) ), `one`, (中文(简体) ), `two`, (中文(简体) ), `few`, (中文(简体) ), `many`, (中文(简体) ), `other`(中文(简体) ) 默认分支 `*`,其中至少有一个超出 `one`编辑 选择值为属性 `count` 默认的插入数据.

**树枝集属于目标语言,而不是来源 语言.** 同样的钥匙和电话 可能是两个分支 英语,波兰语4个,日语平话:

```json
{
  "FILES": {
    "removed": {
      "one": "Usunięto {count} plik",
      "few": "Usunięto {count} pliki",
      "many": "Usunięto {count} plików",
      "other": "Usunięto {count} pliku"
    }
  }
}
```

```json
{ "FILES": { "removed": "{count}件のファイルを削除しました" } }
```

使用 `$plural` 由另一财产选择,以及 `$ordinal` 数字 数字,许多语言通过自己的规则来体现:

```json
{
  "CART": { "$plural": "amount", "one": "{amount} item", "other": "{amount} items" },
  "RANK": { "$ordinal": "rank", "one": "{rank}st", "two": "{rank}nd", "few": "{rank}rd", "other": "{rank}th" }
}
```

`$range` 按数字范围的类别选择,例如“ 1–5 天” :

```json
{ "DAYS": { "$range": [ "from", "to" ], "one": "{from}–{to} day", "other": "{from}–{to} days" } }
```

#### 性别和其他任何区别

`$select` 用任意的值来选择分支,例如一个人的性别, 插入名词的语法性别、动画或名词类:

```json
{
  "INVITE": {
    "$select": "actor.gender",
    "f": "{actor.name} invited you to her project.",
    "m": "{actor.name} invited you to his project.",
    "*": "{actor.name} invited you to their project."
  }
}
```

处 `*` 当没有其他分支匹配时,即使用,包括 缺少或未知值,因此应使用有效配方 毫无区别 一个完全不区分的语言 只是写一个简单的字符串代替.

#### 缠绕

分支可能自行选择节点. 这包括斯拉夫语言, 动画适用于哪些复数形式:

```json
{
  "SELECTED": {
    "$select": "item.animacy",
    "personal": { "one": "…", "few": "…", "many": "…", "other": "…" },
    "*":        { "one": "…", "few": "…", "many": "…", "other": "…" }
  }
}
```

#### 退缩和选择退出

如果没有树枝匹配, `other` 尝试,然后 `*` (另一边) `$select`),最终键本身被还原,就像丢失一样 翻译.

从键开始 `$` 预留。 一条普通的密钥线程 被误认为是一个选择—— 一个实际命名的 `one`, (中文(简体) ), `few`, (中文(简体) ), `other`. . . . 是 . 标记为 `$literal`数字 :

```json
{ "ROUND": { "$literal": true, "one": "First round", "other": "Any other round" } }
```

> **说明:** 数字是内插的。 包起来 `Intl.NumberFormat` 如果你需要组合分离器,或者通过 格式化字符串为数据.

### 术语:插入反射词

在 **插入单词本身** 必须 改变形式——德国需要4个病例,抛光7个,芬尼15个。 自兹 这个库从不反映一个单词, 翻译文件提供 表格,且占位符请求一个.

术语是提供 `forms`,加上您想要的任何语法特性 树枝。 根据《公约》规定 `TERMS`数字 :

```json
{
  "TERMS": {
    "file": {
      "gender": "f",
      "forms": { "nom": "Datei", "gen": "Datei", "dat": "Datei", "acc": "Datei", "nom.pl": "Dateien" }
    },
    "folder": {
      "gender": "m",
      "forms": { "nom": "Ordner", "gen": "Ordners", "dat": "Ordner", "acc": "Ordner" }
    }
  },
  "MOVE": "{file:acc} nach {folder:dat} verschieben"
}
```

```javascript
import { term, useL10n } from "@cepharum/vue3-i18n";

useL10n().translate( "MOVE", { file: term( "file" ), folder: term( "folder" ) } );
// "Datei nach Ordner verschieben"
```

窗体名称是您的: 提供了 finish 文件 `nom`, (中文(简体) ), `gen`, (中文(简体) ), `part`, (中文(简体) ), `iness`,... 和一个抛光一 `nom`, (中文(简体) ), `gen`, (中文(简体) ), `dat`, (中文(简体) ), `acc`, (中文(简体) ), `instr`, (中文(简体) ), `loc`, (中文(简体) ), `voc` 加上他们的复数. `{file}` 不插入该术语的默认表单, 这是 `nom` 除非该术语在 `default`。 。 。 .

因为一个术语带有它的特征,所以选择可以在它们上分支——这就是 文章和参与者如何同意插入的名词:

```json
{
  "DELETED": {
    "$select": "obj.gender",
    "m": "Der {obj:nom} wurde gelöscht.",
    "f": "Die {obj:nom} wurde gelöscht.",
    "n": "Das {obj:nom} wurde gelöscht."
  }
}
```

土耳其语在这里写一个分支,西班牙语2个,和一班图语一样多 按照它的名词类要求——调用代码在每一个情况下都保持不变.

条款也可以通过 内线,没有任何词汇, 适合记录您的 应用程序已持有 :

```javascript
translate( "DELETED", { obj: { gender: "n", forms: { nom: "Bild" } } } );
```

注释:

-   普通字符串继续作为插值数据工作. 申请的表格是 完全无视.
-   一个不可解的名词被插入作为它的密钥,就像一个缺失的翻译.
-   `configure( { terms: "WORDS" } )` 将词典移动到另一个键上.
-   格式名称优先于形式名称,因此避免命名形式 `number`, (中文(简体) ), `date`, (中文(简体) ), `time`, (中文(简体) ), `datetime`, (中文(简体) ), `relative` 或者说 `list`。 。 。 .

#### 斯拉夫语参考案例

案件、数字和动画同时出现,而且电话编码不变:

```json
{
  "TERMS": {
    "plik": {
      "gender": "m", "animacy": "inanimate",
      "forms": { "nom": "plik", "acc": "plik", "nom.pl": "pliki", "gen.pl": "plików" }
    }
  },
  "REMOVED": {
    "one":   "Usunięto {count} {item:acc}",
    "few":   "Usunięto {count} {item:nom.pl}",
    "many":  "Usunięto {count} {item:gen.pl}",
    "other": "Usunięto {count} {item:gen.pl}"
  }
}
```

```javascript
translate( "REMOVED", { count, item: term( "plik" ) } );
// 1 → "Usunięto 1 plik"      2 → "Usunięto 2 pliki"
// 5 → "Usunięto 5 plików"   22 → "Usunięto 22 pliki"
```

### 格式化值

数字、日期和清单在每一个地区都遵循自己的惯例,因此 占位符可以指定一个前题:

```json
{
  "CART": {
    "total": "{count:number} items, {sum:number(currency=EUR)}",
    "due": "due {when:date(long)}, updated {ago:relative(hour)}",
    "who": "shared with {names:list}"
  }
}
```

```javascript
translate( "CART.total", { count: 12345, sum: 79.9 } );
// en: "12,345 items, €79.90"
// de: "12.345 items, 79,90 €"
```

格式由 `Intl` 和决心 **满** 语言标记,所以 `de-CH` 千人组别 `de-DE`。 。 。 .

| 主题 | 参数 | 后卫 |
| --- | --- | --- |
| `number` | `currency=EUR`, (中文(简体) ), `unit=kilometer`, (中文(简体) ), `percent`, (中文(简体) ), `compact`, (中文(简体) ), `min=`, (中文(简体) ), `max=` | `Intl.NumberFormat` |
| `date`, (中文(简体) ), `time`, (中文(简体) ), `datetime` | `full`, (中文(简体) ), `long`, (中文(简体) ), `medium`, (中文(简体) ), `short` | `Intl.DateTimeFormat` |
| `relative` | 单位`day`, (中文(简体) ), `hour`,(......), `always` | `Intl.RelativeTimeFormat` |
| `list` | `or`, (中文(简体) ), `unit`, (中文(简体) ), `long`, (中文(简体) ), `short`, (中文(简体) ), `narrow` | `Intl.ListFormat` |

不符合其物料的值——或不存在的物料—— 被插入到未格式化的文本中,所以译出时不会中断.

使用 `registerFormatter()`,并在 之后的占位符 :

```javascript
useL10n().registerFormatter( "file", ( value, { locale } ) => prettyBytes( value, locale ) );
```

渲染时 [标记](https://npmcn.com/package/%40cepharum/vue3-i18n/#readme-markdown),一个前题的输出像任何 其他插值。 返回时 [`html()`](https://npmcn.com/package/%40cepharum/vue3-i18n/#readme-html-in-interpolated-values) 改为 提供标记.

### 选项而不是位置参数

`translate()` 接受一组选项作为其第二个参数:

```javascript
translate( "CART.total", { data, markdown: true, locale: "de-AT", bidi: "auto" } );
```

紧凑的形式 `translate( key, data, markdown, locale )` 继续支助 而对于普通案件来说更方便 对象为 选项 **全部** 属性为选项名称,所以 `translate( key, { data: x, name: y } )` 仍然通过内插数据.

### 隔离插值

在阿拉伯语中插入一个拉丁名——或者换句话说—— 重排周围的分点, 除非该值被隔离 。 启用 每个上下文或每个翻译的隔离:

```javascript
useL10n().configure( { bidi: "auto" } );
```

其方向与地方方向相冲突的价值是 包起来 `U+2068`编号 :`U+2069`。与方向相匹配的值是单独存在的,所以 拉丁文本没有变化。 默认是 `"off"` 保留现有产出 无所未有.

### 地区

BCP-47 语言标记全版处理地方性,并查找翻译 沿着一条从赤裸的语言到最具体变体的链子:

```
de-AT       →  de
zh-Hant-TW  →  zh-Hant  →  zh
```

装填器被用在链子的每一个环节上,从赤裸起 语言,以及每项结果 **覆盖** 上一个。 区域文件 因此,只有下列偏离情况:

```json
// l10n/de.json
{ "COMMON": { "ok": "Okay", "cancel": "Abbrechen" } }
```

```json
// l10n/de-AT.json
{ "COMMON": { "cancel": "Zurück" } }
```

```javascript
useL10n().setLoader( locale => import( `./l10n/${locale}.json` ) );
useL10n().setLocale( "de-AT" );
```

**提供这些文件是可选的.** 一个加载器在任何链接上都失败了 比赤裸的语言更具体被默默地忽略——上面的例子有效 同样的,在应用运输中 `de.json`仅此而已。 只装入器失败 在赤裸裸的语言上是一个错误,就像以前一样.

没有区域或脚本的地方不会引起额外的浏览 : 选择 `de` 引用装入器一次,与前几个版本完全相同.

区分问题不在于措辞,而在于: `pt` 财务报告和审定财务报表 `pt-PT` 它们的差别 复数规则,和 `zh-Hans` 财务报告和审定财务报表 `zh-Hant` 是不同的脚本。 选择是 因此通过满分标签解决.

上下文的相关属性:

-   `locale` 继续提供 **语言**,比如说. `de`总是这样.
-   `tag` 提供完整的犬科标记,例如:. `de-AT`。 。 。 .
-   `script` 财务报告和审定财务报表 `region` 提供部分,或 `null`。 。 。 .
-   `defaultTag` 提供默认语言的完整标记.

设定 `configure( { regional: false } )` 以禁用额外的搜索和地址 鲜活的语言,只有:

```javascript
useL10n().configure( { regional: false } );
```

> **说明:** 被贬损的语言代码被保留而不是被替换,所以 选择 `iw` 不断取取 `iw`没有 `he`。 。 。 .

### 验证翻译

一个俄罗斯文件丢失了它 `few` 分支不会失败——它悄悄地倒下 改为 `other` 并且读错了2、3和4. `validateTranslations()` 认定:

```javascript
import { validateTranslations } from "@cepharum/vue3-i18n";

validateTranslations( await import( "./l10n/ru.json" ), "ru", {
    reference: await import( "./l10n/en.json" ),
} );
// [ { path: "FILES.removed", severity: "error", code: "missing-category",
//     message: "selection at FILES.removed lacks few, many required for locale ru" } ]
```

检查每个地方 :

| 代码 | 严重性 | 含义 |
| --- | --- | --- |
| `missing-category` | 错误 | 复数选择缺少本地语言使用的分类 |
| `unused-category` | 警告 | 复数选择提供了语言不使用的类别 |
| `missing-default-branch` | 错误 | (单位:千美元) `$select` 节点缺乏其 `*` 分支 |
| `missing-form` | 警告 | 占位符请求该术语未提供的表格 |
| `empty-term` 编号 : `missing-default-form` | 错误 | 一个术语不提供表格, 或者它命名为默认的 |
| `missing-translation` | 警告 | 缺少引用树的密钥(只有 `reference`(中文(简体) ) |

所需类别来自 `Intl.PluralRules( locale ).resolvedOptions().pluralCategories`因此没有规则 在任何地方维护——在这个库中增加一个地块不需要改动.

用它来测试,所以不完全的翻译会失败构建:

```javascript
import { describe, it } from "vitest";
import { validateTranslations } from "@cepharum/vue3-i18n";

describe( "translations", () => {
    for ( const locale of [ "de", "ru", "pl" ] ) {
        it( `are complete for ${locale}`, async() => {
            const findings = validateTranslations(
                ( await import( `./l10n/${locale}.json` ) ).default, locale,
                { reference: ( await import( "./l10n/en.json" ) ).default } );

            findings.filter( finding => finding.severity === "error" ).should.be.empty();
        } );
    }
} );
```

在开发模式中,翻译在加载和发现时得到验证 在控制台上报告。 关掉它 `configure( { validate: false } )`。背景也暴露了 `validate( locale?, options? )` 对于它已经加载的翻译.

### 标记

有人支持一些基本的Markdown翻译.

```json
{
  "COMMON": {
    "confirm": "Okay",
    "cancel": "Cancel"
  },
  "FEATURE": {
    "title": "About",
    "text": "This is **the** feature!"
  }
}
```

`<L10n>` 默认忽略任何Markdown。 通过设置 `markdown` 属性,但支持的 Markdown 转换为 HTML。 但翻译中额外发现的任何HTML都会被逃脱.

支持的语法是 `*italic*` 或者说 `_italic_`, (中文(简体) ), `**bold**` 或者说 `__bold__`,在换行符前的两个空格 `<br>`,用于启动另一个段落并 `[label](href)` 链接。 链接仅作为标签提供, 除非其目标为相对的 URL 或带有方案的绝对 URL `http`, (中文(简体) ), `https`, (中文(简体) ), `mailto` 或者说 `tel`。 。 。 .

```vue
<script setup>
import { L10n } from "@cepharum/vue3-i18n";
</script>

<template>
  <h1><L10n i18n="FEATURE.title" markdown /></h1>
  <p><L10n i18n="FEATURE.text" /></p>
  <button><L10n i18n="COMMON.confirm" /></button>
</template>
```

#### 插值中的 HTML

当Markdown逃脱时,将数值插入翻译中,与翻译本身中发现的HTML一样。 这也适用于格式化的值、术语的形式和插入链接目标的值。 在插值中发现的Markdown也没有处理.

标记一个值 `html()` 将其插入到当前,例如用于包含图标:

```javascript
import { html, useL10n } from "@cepharum/vue3-i18n";

// translation: "Status: {icon} **{label}**"
useL10n().translate( "JOB.status", {
    icon: html( '<i class="fa-solid fa-check"></i>' ),
    label: job.label,
}, true );
```

物料可能还原 `html()`缩写:

```javascript
import { escapeHtml, html, useL10n } from "@cepharum/vue3-i18n";

useL10n().registerFormatter( "icon", name => html( `<i class="fa-solid fa-${escapeHtml( name )}"></i>` ) );
```

> \[尖叫声\] 绝不将用户提供的内容传递给 `html()`。标记已存在,用于标记您的应用程序已组装。 它不能作为数据的一部分提供,例如从JSON解析,因为它是一个类的例子而不是一个平庸的对象.

无 `markdown`,翻译的结果是文本 `<L10n>` 做成这样。 因为Vue正在逃离整个文本 内入值是无法逃脱的 因此, `html()` 并显示为文字文本。 如果你通过的结果 `translate()` 改为 `v-html` 自己,总是让 `markdown` 对于它.

### 其他 API 特性

获取的背景 `useL10n()` 披露其他属性和行动:

-   `locale` 反应性地提供当前地语作为字符串,例如. `en` 或者说 `de`,与 `tag` 提供完整的语言标记,例如:. `en-US`。两者默认都来源于浏览器的语言.
    
    -   当前区域 `document` 优先选择.
    -   如果语言 `document` 缺少或没有 `document`,当前浏览器在 `navigator.language` 已使用.
    -   如果缺少浏览器的语言, 或者没有浏览器, 默认的语言会被用作倒置, 即 `en` 最初.
-   方法 `setLocale( locale )` 选择一个自定义的地块来选择作为当前地块,而不是从上述其它来源读取的任何地块。 这使得该地块的翻译被取出并全部使用 `<L10n>` 待更新组件.
    
    这种方法会回报一个承诺,一旦拿到这些译文,承诺就立即解决。 等待是可选的,但可以避免你选择一个地方和等待 `loadTranslations()` 单独:
    
    ```javascript
    await useL10n().setLocale( "de" );
    ```
    
    提供一个无效的地盘仍然会同步投出,而不是拒绝这一承诺.
    
    ```vue
    <script setup>
    import { useL10n } from "@cepharum/vue3-i18n";
      
    useL10n().setLocale( "fr" );
    </script>
    ```
    
    方法 `setLocale()` 可用于丢弃任何先前选择的自定义地块,并恢复上文所述当前地块的发现.
    
    ```vue
    <script setup>
    import { useL10n } from "@cepharum/vue3-i18n";
      
    useL10n().setLocale();
    </script>
    ```
    
-   `defaultLocale` 反应性地暴露了上述最后一步中使用的倒背地语. 方法 `setDefaultLocale()` 可以用来调整它.
    
    ```vue
    <script setup>
    import { useL10n } from "@cepharum/vue3-i18n";
    
    useL10n().setDefaultLocale( "de" );
    </script>
    ```
    
-   除了在发现当前地语时起到倒置的作用外,当没有为当前地语提供翻译时,这个默认地语在查找i18n密钥的翻译时也被认为是被考虑的.
    
-   您可以使用方法获取被动翻译 `lookup()`。 。 。 .
    
    ```vue
    <script setup>
    import { useL10n } from "@cepharum/vue3-i18n";
    
    const translation = useL10n().lookup( "SOME.KEY.FOR.firstField" );
    </script>
    ```
    
    由此而来的翻译不是插入的,而是取自从取来的现有翻译. 如果密钥也涉及整个翻译线索.
    
-   此外,您还可以使用方法获取多个被动翻译 `translate()` 带有可选插值和Markdown支持.
    
    ```vue
    <script setup>
    import { ref } from "@vue/reactivity";
    import { useL10n } from "@cepharum/vue3-i18n";
    
    const { translate } = useL10n();
    
    const data = ref( { count: 23, foo: "test" } );
    
    // translates and interpolates single string supporting Markdown, too
    const single = translate( "SOME.KEY.FOR.firstField", data, true );
    
    // translates multiple strings at once and returns object with
    // same properties each providing related key's translation
    const multi = translate( {
      first: "SOME.KEY.FOR.firstField",
      second: "SOME.KEY.FOR.secondField",
    }, data );
    </script>
    ```
    
-   默认情况下, 翻译会被查询到上面描述的当前选择的地块 。 但是,可以明确选择一个自定义语言,以查找该特定语言的译名 `lookup()` 财务报告和审定财务报表 `translate()`。 。 。 .
    
    ```vue
    <script setup>
    import { ref } from "@vue/reactivity";
    import { useL10n } from "@cepharum/vue3-i18n";
    
    const { translate, lookup } = useL10n();
    
    const data = ref( { count: 23, foo: "test" } );
    
    // translates single string to French explicitly
    const translation = lookup( "SOME.KEY.FOR.firstField", null, "fr" );
    
    // translates multiple strings at once to French
    const multi = translate( {
      first: "SOME.KEY.FOR.firstField",
      second: "SOME.KEY.FOR.secondField",
    }, data, false, "fr" );
    </script>
    ```
    
    同样的作品 `locale` 财产 `L10n` 组件.
    
-   考虑到文档的语言可以被禁用 . _(profile to v0.5.0, 这是默认的, 发现当前本地工作的方式更加简单。 )_
    
    ```javascript
    import { useL10n } from "@cepharum/vue3-i18n";
    
    useL10n().unobserveDocument();
    </script>
    ```
    
    考虑文档语言后可以重新启用:
    
    ```javascript
    import { useL10n } from "@cepharum/vue3-i18n";
    
    useL10n().observeDocument();
    </script>
    ```
    
    还可以看到其他文件。 然而,它正在控制通常以
    
    ```javascript
    import { useL10n } from "@cepharum/vue3-i18n";
    
    useL10n().observeDocument( customDocument );
    </script>
    ```
    
    然而,这并没有取代对当前文档地语的监控,而是选择给定文档地语作为自定义地语,就像引用 `setLocale( locale )` 当给定的文档的区位在改变时,该方法会改变。 因此,观察多份补充文件是可能的,但没有什么意义.
    
    停止观察额外文件的工作:
    
    ```javascript
    import { useL10n } from "@cepharum/vue3-i18n";
    
    useL10n().unobserveDocument( customDocument );
    </script>
    ```
    
    这将恢复上文第一项所述发现当前地块的过程。 任何选中的自定义地盘都会被删除 .

## 常见问题

### @cepharum/vue3-i18n 是什么？

vue3 应用程序的简单 i18n 库

### 如何安装 @cepharum/vue3-i18n？

在项目目录运行 npm install @cepharum/vue3-i18n，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cepharum/vue3-i18n 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cepharum/vue3-i18n 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cepharum/vue3-i18n 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.13。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cepharum/vue3-i18n 可以商用吗？

@cepharum/vue3-i18n 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cepharum/vue3-i18n 的下载量有多少？

根据 npm 官方下载统计，@cepharum/vue3-i18n 在 2026/10/10 – 2026/11/08 这 30 天内被下载 5,943 次，日均约 198 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cepharum/vue3-i18n 还在维护吗？

最新版本 3\.0\.1 发布于 2026/11/01（7 天前）；至今共发布 21 个版本，其中过去 12 个月发布了 4 个；首次发布于 2023/06/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。