# @fiverr/i18n 中文文档

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

版本：1\.9\.2
npm 元数据更新时间：2026-08-23T11:26:38.453Z
中文译文更新时间：2026-11-14T20:42:42.340Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：38.4 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=6\.9\.4
- 运行依赖：4 个
- 首次发布：2017-08-03T10:55:54.103Z
- 最新版本发布：2024-11-05T15:46:19.620Z
- 近 30 天下载量：4495（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 0 个）

## 中文简介

翻译助手

## 安装

```sh
npm install @fiverr/i18n
```

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

## README

# ![](https://user-images.githubusercontent.com/516342/57133825-b03b7580-6dac-11e9-803b-0564d12ee13d.png) i18n (英语) [![](https://img.shields.io/npm/v/@fiverr/i18n.svg)](https://www.npmjs.com/package/@fiverr/i18n) [![](https://img.shields.io/circleci/project/github/fiverr/i18n.js.svg)](https://circleci.com/gh/fiverr/i18n.js) ![](https://img.shields.io/node/v/@fiverr/i18n.svg)

异形翻译引擎. mics Rails的i18n接口.

## 使用量

```js
const I18n = require('@fiverr/i18n');
const translations = require('./translations.json');

const i18n = new I18n({translations});
```

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `translations` | 对象 | 翻译结构的代表性 **一定是JSON服从** 否则会被当成空物体对待 |
| `missing` | 函数 | 缺少密钥时调用此函数 。 函数接受参数: 密钥、 范围、 翻译 对象 |
| `empty` | 函数 | 当值为空时调用此函数 。 函数接受参数:密钥、值、范围、翻译 对象 |
| `$scope` | 字符串 | 缩写前缀. 见 [范围](https://npmcn.com/package/%40fiverr/i18n/#readme-instance-with-a-scope) **基础是翻译密钥根** |

```js
const i18n = new I18n({
    translations: {...},
    missing: key => logMissingKeyEvent({key: `missing_translation.${key.replace(/\W/g, '_')}`}),
    empty: key => logEmptyValueEvent({key: `empty_translation.${key.replace(/\W/g, '_')}`}),
    $scope: 'my_app.en'
});
```

### 翻译

```js
i18n.t('my.key'); // I'm a sentence
```

### 寻找替代品

```js
i18n.t(['my.missing.key', 'my.key']); // I'm a sentence
```

### 处理缺失

默认情况下, 缺少的密钥或空值返回密钥的最后一部分

```js
i18n.t('this.is.a.missing_key'); // missing key
```

但是,从“ 丢失” 和“ 空” 调回返回一个真实值, 将允许自定义回落

```js
const i18n = new I18n({
    translations: {...},
    empty: (key, value, scope) => {
        if (scope.startsWith('en-US')) {
            return; // default fallback
        }
        return i18n.t(key, { $scope: 'en-US' }); // Try English
    },
    $scope: 'en-US'
});
```

### 即时处理后添加更多翻译

```js
i18n.add({yet: {another: {key: 'I\'m here, too!'}}});
Use:
i18n.translate('yet.another.key'); // I'm here, too!
Or:
i18n.t('yet.another.key'); // I'm here, too!
```

## 特征

### 带有数据的内插

```js
const i18n = new I18n({
    translations: {
        my: { string: 'a dynamic %{thing} in a static string' }
    }
});
i18n.t('my.string', {thing: 'value'}); // a dynamic value in a static string
```

### 一个/另一个

```js
const i18n = new I18n({
    translations: {
        it_will_take_me_days: {
            one: 'It\'ll take me one day',
            other: 'It\'ll take me %{count} days'
        }
    }
});
i18n.t('it_will_take_me_days', {count: 1}); // It'll take me one day
i18n.t('it_will_take_me_days', {count: 3}); // It'll take me 3 days
i18n.t('it_will_take_me_days', {count: 'a lot of'}); // It'll take me a lot of days
```

### 有范围的案例

优先级 :

1.  发现结果,范围已过(如适用)
2.  确定实例范围的结果(如适用)
3.  发现结果w/o 范围

```js
// Global scope setup
const i18n = new I18n({
    translations: {
        key: 'Top',
        child: {
            key: 'Child'
        },
        something: {
            key: 'Something'
        }
    }
});
const child = i18n.spawn('child');

i18n.t('key'); // Top
child.t('key'); // Child
child.t('key', { $scope: 'something' }); // Something
```

### 范围较大的儿童案件

这对应用程序的封闭部分来说是一个很好的简称选择.

译名商店是共享的,这样如果在命名空间前加了前缀,则父母可以找到密钥,而孩子不需要.

孩子还可以找到"全球"译名(一个在它的命名空间之外)

```js
const usersI18n = i18n.spawn('users.get');

// Add translations under the scope
usersI18n.add({introduction: 'Hi, my name is %{username}'});

// Use translations
usersI18n.t('introduction', {username: 'Martin'}); // Hi, my name is Martin
i18n.t('users.get.introduction', {username: 'Martin'}); // Hi, my name is Martin
```

### 实例

显示一个 i18n 的空实例

```js
const i18n = require('@fiverr/i18n/instance');

i18n.add({...});
```

特别用作外部网络包装

```js
externals: {
  '@fiverr/i18n/instance': 'i18n'
}
```

> 名称可以替换 :
> 
> ```js
> import phraser from '@fiverr/i18n/instance';
> ```
> 
> ```js
> externals: {
>   '@fiverr/i18n/instance': 'phraser'
> }
> ```

### 单子(i18n)

确定你在全球范围内只有一次I18n

```js
const i18n = I18n.singleton;

// Optional:
i18n.$scope = 'my.scope';
i18n.onmiss((key, scope) => console.error(`Missing key "${key}" ${scope ? `In scope: "${scope}"`}`));
i18n.onempty((key, value, scope) => console.warn(`Empty value "${value}" for key "${key}" ${scope ? `In scope: "${scope}"`}`));
i18n.add({...});
```

快捷键 :

```js
const i18n = require('@fiverr/i18n/singleton');
```

或者简单

```js
require('@fiverr/i18n/singleton');

// i18n is defined globally
```

### 辅助功能

检查是否有可用的密钥

#### 已经

```js
i18n.has('key');
i18n.has(['key', 'other_key']);
i18n.has('namespace.key');
i18n.has('key', { $scope: 'namespace' });
```

## 常见问题

### @fiverr/i18n 是什么？

翻译助手

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

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

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

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fiverr\_\_i18n 是否存在。

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

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

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

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

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

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

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