# @draggable/i18n 中文文档

规范地址：https://npmcn.com/package/%40draggable/i18n/

版本：1\.2\.2
npm 元数据更新时间：2026-11-06T09:47:43.626Z
中文译文更新时间：2026-11-12T21:53:57.268Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40draggable/i18n
原文对照：https://npmcn.com/package/%40draggable/i18n/?lang=original
项目主页：https://github.com/Draggable/i18n
源码仓库：https://github.com/Draggable/i18n

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

- 包体积（解压后）：284 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-10-30T05:06:48.233Z
- 最新版本发布：2026-11-06T09:47:43.293Z
- 近 30 天下载量：4388（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 6 个）

## 中文简介

通用JavaScript应用的简单而坚固的i18n解决方案.

## 安装

```sh
npm install @draggable/i18n
```

也可以使用：`pnpm add @draggable/i18n`、`yarn add @draggable/i18n`、`bun add @draggable/i18n`

## README

# i18n (英语) ![NPM Version](https://img.shields.io/npm/v/@draggable/i18n)

在 JavaScript 应用程序或模块中添加多语言支持,使用此轻量级包. 用于 [形式](https://formeo.io/)。 。 。 .

### 特征 :

-   Isomorphic/Universal:在浏览器和节点工作(无) `fetch` 语言预装时需要)
-   静态文本文件的简单翻译
    -   好处:任何人都可以翻译,不再使用 xliff
    -   减少出错幅度.
-   可变支持
-   后退地块和复数
-   包含类型脚本
-   无依赖性
-   快点

## 安装

```sh
npm install @draggable/i18n
```

## 使用量

默认导出是一个共享的单通实例, `I18N` 是班级.

```javascript
import i18n, { I18N } from '@draggable/i18n'

const i18nOptions = {
  extension: '.lang', // extension used by your language files, defaults to ".lang"
  location: 'https://location.of/language/files/', // absolute or relative url to language files
  langs: [
    // locales you would like to be active
    'en-US',
    'pt-BR',
    'de-DE', // will attempt to load `https://location.of/language/files/de-DE.lang` with current config
  ],
  locale: 'en-US', // default locale
  override: {
    'en-US': {
      autocomplete: 'Autofinish', // override individual keys or provide entire language definition
    },
  },
}

// configure the singleton and load the current locale
await i18n.init(i18nOptions)

// or create a separate instance
const myI18n = new I18N(i18nOptions)
await myI18n.init()
```

`I18N(options)` (无) `new`)返回单通,与默认导出相同。 这样的选项 仅在单子尚未创建的情况下使用; 使用 `i18n.init(options)` 要重新配置它.

在你的应用中

```jsx
<label>{i18n.get('addOption')}</label>
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `extension` | `string` | `'.lang'` | 远程语言文件扩展名 |
| `location` | `string` | `'assets/lang/'` | 包含语言文件的目录的url 或路径 |
| `langs` | `string[]` | `['en-US']` | 可用语言选择器的本地语言, 方便使用 |
| `locale` | `string` | `'en-US'` | 初始区域,回到第一个区域 `langs` 空时 |
| `preloaded` | `{ [locale]: { [key]: string } }` | `{}` | 不获取而可用语言 |
| `override` | `{ [locale]: { [key]: string } }` | `{}` | 优先于已装入和预装语言的密钥 |
| `fallbackLocale` | `string | string[]` | – 说吧 – | 返回到缺少密钥时的位置,参见 [后退区域](https://npmcn.com/package/%40draggable/i18n/#readme-fallback-locales) |
| `onMissing` | `(info) => string | void` | – 说吧 – | 请求缺少密钥和参数,参见 [缺少密钥](https://npmcn.com/package/%40draggable/i18n/#readme-missing-keys-and-arguments) |

### 翻译

```javascript
// languages: { 'en-US': { greeting: 'Hello {name}', total: '{count} of {count}' } }

i18n.get('greeting', { name: 'Ana' }) // 'Hello Ana'
i18n.get('total', 3) // '3 of 3', a primitive replaces every placeholder
i18n.get('greeting') // 'Hello {name}', no args: no replacement
i18n.get('missing') // undefined

// t() always returns a string, falling back to the key
i18n.t('greeting', { name: 'Ana' }) // 'Hello Ana'
i18n.t('missing') // 'missing'

// per-call locale, without changing the current locale
i18n.get('greeting', { name: 'Ana' }, 'de-DE') // 'Hallo Ana'
i18n.t('greeting', { name: 'Ana' }, 'de-DE') // 'Hallo Ana'
i18n.getValue('greeting', 'de-DE') // 'Hallo {name}', raw string

// t() bound to a locale, handy on servers handling several locales at once
const t = i18n.forLocale('de-DE')
t('greeting', { name: 'Ana' }) // 'Hallo Ana'
```

缺少的占位符参数被空字符串所取代 .

### 后退区域

无 `fallbackLocale` 缺少的密钥会用任何装入的语句( 遗留行为) 查找 . 与 `fallbackLocale` 设置查询顺序为:

1.  请求的地块, 例如 . `pt-BR`
2.  其基础语言,如果装入,例如:. `pt`
3.  按顺序排列
4.  `t()` 返回密钥, `get()` 返回时 `undefined`

```javascript
const i18n = new I18N({
  locale: 'pt-BR',
  fallbackLocale: ['pt', 'en'],
  preloaded: {
    'pt-BR': { save: 'Salvar' },
    pt: { cancel: 'Cancelar' },
    en: { save: 'Save', cancel: 'Cancel', help: 'Help' },
  },
})

i18n.t('save') // 'Salvar'
i18n.t('cancel') // 'Cancelar'
i18n.t('help') // 'Help'
i18n.getLocaleChain('pt-BR') // ['pt-BR', 'pt', 'en']
```

何时 `fallbackLocale` 设置,其值为空字符串的密钥(`''`) 计为已翻译,返回为 `''` 而不是掉下来。 没有它,空字符串就被视为缺失.

`init()` 还装入尚未装入的后退方位 .

### 复数

键缺失时 `args` 是数字还是数字 `count`,则使用密钥的复数形式. 选择表单时 [`Intl.PluralRules`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) 语言: `key.zero` (仅用于计算) `0`,则 `key.<category>` (单位:千美元)`zero`, (中文(简体) ), `one`, (中文(简体) ), `two`, (中文(简体) ), `few`, (中文(简体) ), `many`, (中文(简体) ), `other`,则 `key.other`。 。 。 . `{count}` 其他占位符照常更换。 若为 `Intl.PluralRules` 不详, `1` 实值 `one` 还有什么是 `other`。 。 。 .

```txt
items.zero = No items
items.one = {count} item
items.other = {count} items
files.other = {count} files in {folder}
```

```javascript
i18n.t('items', 0) // 'No items'
i18n.t('items', { count: 1 }) // '1 item'
i18n.t('items', 5) // '5 items'
i18n.t('files', { count: 2, folder: 'docs' }) // '2 files in docs'
```

一个存在于当前状态的密钥( 如 :. `items`)总是优先于其多元形式.

### 缺少密钥和参数

```javascript
const i18n = new I18N({
  onMissing: ({ key, locale, type, arg }) => {
    console.warn(`missing ${type}`, locale, key, arg)
    if (type === 'key') return `[${key}]` // optional replacement
  },
})
```

`onMissing` 名为 `get()` 财务报告和审定财务报表 `t()` 缺少的密钥 (`type: 'key'`)和缺失的占位符值 (单位:千美元)`type: 'arg'`,与 `arg` 设置到占位符名称。 返回字符串时使用它; 返回时没有保留 默认( e)`undefined` 从 `get()`键 `t()`, (中文(简体) ), `''` (关于辩论).

### 初始化后添加语言

```javascript
i18n.addLanguage('fr-FR', {
  addOption: 'Ajouter une option',
})

// or from the contents of a .lang file
i18n.addLanguage('fr-FR', 'addOption = Ajouter une option')
```

再次添加同一地块会合并密钥; `getLangs` 财务报告和审定财务报表 `loaded` 请不要重复.

### 设置字符串

```javascript
i18n.put('greeting', 'Hi {name}') // current language
i18n.put('greeting', 'Oi {name}', 'pt-BR') // a specific locale
```

### 更改语言

```javascript
await i18n.setCurrent('de-DE') // fetches de-DE.lang unless already loaded or preloaded
```

### 处理一个配置

```javascript
i18n.processConfig({ locale: 'de-DE', override: { 'de-DE': { save: 'Speichern' } } })
```

`processConfig(options)` 应用选项而不获取任何东西; `init(options)` 应用它们并装入电流 语言.

### 服务器侧用法

没有 `fetch` 当语言从字符串中预装或添加时需要:

```javascript
import { readFileSync } from 'node:fs'
import { I18N } from '@draggable/i18n'

const i18n = new I18N({
  locale: 'en-US',
  fallbackLocale: 'en-US',
  preloaded: {
    'en-US': I18N.parse(readFileSync('lang/en-US.lang', 'utf8')),
  },
})
i18n.addLanguage('de-DE', readFileSync('lang/de-DE.lang', 'utf8'))

// per request
const t = i18n.forLocale(request.locale)
t('greeting', { name: user.name })
```

`setCurrent()` 财务报告和审定财务报表 `init()` 不获取预加载或添加的地块 `addLanguage()`。 。 。 . 通用JS也得到支持: `const { I18N } = require('@draggable/i18n')`。 。 。 .

### 类型脚本

类型包括:

```typescript
import i18n, { I18N, type I18NOptions, type I18NInstance } from '@draggable/i18n'

const options: I18NOptions = { locale: 'en-US', fallbackLocale: 'en-US' }
const instance: I18NInstance = new I18N(options)
const label: string = instance.t('addOption')
```

### `.lang` 文件

```txt
# comments start with # or ; at the beginning of a line
de-DE = Deutsch
en-US = German

addOption = Option hinzufügen
allFieldsRemoved = Alle Felder wurden entfernt.
allowMultipleFiles = Upload mehrerer Dateien erlauben
autocomplete = Autovervollständigung

; a trailing backslash continues the value on the next line,
; leading whitespace of the next line is ignored
longText = Dies ist ein langer Text, \
    der über mehrere Zeilen geht.
```

-   一个 `key = value` 每行、按键和值被修剪
-   `\n` 财务报告和审定财务报表 `\r\n` 支持行尾, 忽略空白行
-   `#` 或者说 `;` 仅在行首( 在可选的空白后) 开始注释, 不在数值后
-   一条线索 `\` 加入下一行, `\\` 将行尾保持为-is

解析文件内容 `I18N.parse(text)` (别名: `I18N.processFile(text)`) (中文(简体) ).

## 常见问题

### @draggable/i18n 是什么？

通用JavaScript应用的简单而坚固的i18n解决方案\.

### 如何安装 @draggable/i18n？

在项目目录运行 npm install @draggable/i18n，或使用 pnpm add / yarn add / bun add。

### @draggable/i18n 支持 TypeScript 吗？

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

### @draggable/i18n 支持 ESM 还是 CommonJS？

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

### @draggable/i18n 可以商用吗？

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

### @draggable/i18n 的下载量有多少？

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

### @draggable/i18n 还在维护吗？

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