# @djangocfg/i18n 中文文档

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

版本：2\.1\.655
npm 元数据更新时间：2026-11-12T12:32:34.515Z
中文译文更新时间：2026-11-12T12:10:07.969Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：753 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^19\.0\.0
- 首次发布：2026-01-23T12:27:15.172Z
- 最新版本发布：2026-11-12T12:32:34.274Z
- 近 30 天下载量：19521（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：464（近 12 个月 464 个）

## 中文简介

@djangocfg 软件包的轻量级i18n库,内置英文、俄文和韩文翻译

## 安装

```sh
npm install @djangocfg/i18n
```

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

## README

![@djangocfg/i18n](https://raw.githubusercontent.com/markolofsen/assets/main/libs/djangocfg/i18n.webp)

# @djangocfg/i18n (英语)

轻量级,用于@djangocfg包的型号安全的i18n库.

## 特征

-   **17种语言** - en, ru, ko, ja, de, fr, zh, it, es, nl, ar, tr, pt-BR, pl, sv, no, da - == 翻译: 翻译:
-   **类型安全** – 自动完成的完整类型脚本支持
-   **包括国别学习** ——管理终端的地块
-   **独立工作** - 部件工作没有提供者

## 安装

```bash
pnpm add @djangocfg/i18n
```

## 快速启动

```tsx
import { I18nProvider, useT, ru } from '@djangocfg/i18n'

<I18nProvider locale="ru" translations={ru}>
  <App />
</I18nProvider>

function MyComponent() {
  const t = useT()
  return <span>{t('ui.form.save')}</span>
}
```

## 子路径导入( 服务器组件)

```tsx
// ✅ Server-safe (no React Context)
import { en, ru, ko } from '@djangocfg/i18n/locales'
import { mergeTranslations } from '@djangocfg/i18n/utils'

// ❌ Client-only (has React Context)
import { I18nProvider, useT } from '@djangocfg/i18n'
```

| 路径 | 说明 |
| --- | --- |
| `@djangocfg/i18n` | 完整软件包(客户组件) |
| `@djangocfg/i18n/locales` | 仅限本地化数据( 服务器安全) |
| `@djangocfg/i18n/utils` | 公用事业 `mergeTranslations` (服务器安全) |

## 自足副本

部件运送自己的打字词典并共享一个地块合同:

```ts
import { createCopy, type Locale } from '@djangocfg/i18n/copy'

const DICTIONARIES: Record<Locale, MyCopy> = { en, ru, /* ... */ 'pt-BR': ptBR }
export const useMyCopy = createCopy(DICTIONARIES).useCopy
```

见 [`@docs/SELF_CONTAINED_COPY.md`](https://npmcn.com/package/%40djangocfg/i18n/@docs/SELF_CONTAINED_COPY.md)。 。 。 .

## 国 际

```bash
# Check missing keys across locales
pnpm i18n check

# List / search keys
pnpm i18n list
pnpm i18n list tour        # filter by pattern
pnpm i18n list -v          # with values

# Add key to all locales at once
pnpm i18n add "tools.new" '{"en":"New","ru":"Новый"}'

# Work with app locales in another directory
pnpm i18n check -d ../../apps/hub/i18n/locales
pnpm i18n list -d ../../apps/hub/i18n/locales
```

## 钩子

| 钩子 | 说明 |
| --- | --- |
| `useT()` | 返回翻译功能(建议) |
| `useI18n()` | 完整背景 : `{ t, locale, setLocale, translations }` |
| `useLocale()` | 返回当前区域字符串 |
| `useTypedT<T>()` | 具有编译时键验证的类型安全 |

### 使用T( )

```tsx
function MyComponent() {
  const t = useT()
  return <button>{t('ui.form.save')}</button>
}
```

### 使用I18n( )

```tsx
function LocaleSwitcher() {
  const { t, locale, setLocale } = useI18n()

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="ru">Russian</option>
    </select>
  )
}
```

## 类型安全后置集成

覆盖 `useTranslations` 在你的应用软件 `global.d.ts` 以获取编译时间密钥验证.

```ts
// global.d.ts
type _Messages = import('@djangocfg/i18n').I18nTranslations &
  import('./i18n/locales/types').AppTranslations;

type _NSKeys = import('@djangocfg/i18n').NamespaceKeys<
  _Messages,
  import('@djangocfg/i18n').NestedKeyOf<_Messages>
>;

declare module 'next-intl' {
  export function useTranslations<NS extends _NSKeys>(
    namespace: NS,
  ): import('@djangocfg/i18n').IntlTranslator<_Messages, NS>;
}
```

## 扩展翻译

```ts
// Spread merge (recommended for next-intl)
import { en as baseEn } from '@djangocfg/i18n/locales'
const messages = { ...baseEn, ...appEn }

// Deep merge with overrides
import { mergeTranslations, ru } from '@djangocfg/i18n'
const customRu = mergeTranslations(ru, {
  ui: { select: { placeholder: 'Выберите...' } },
})
```

## 内插

```tsx
t('ui.pagination.showing', { from: 1, to: 10, total: 100 })
// => "1-10 of 100"
```

## 翻译密钥路径

```
ui.*         - UI components (select, form, dialog, table, pagination)
layouts.*    - Layout components (sidebar, auth, profile, theme)
api.*        - API/network messages
tools.*      - Heavy tools (tour, upload, code, image)
```

## 没有提供者的工程

使用组件 `useT()` 回到英语默认值时, 当使用在提供者之外.

## 许可证

麻省理工学院

## 常见问题

### @djangocfg/i18n 是什么？

@djangocfg 软件包的轻量级i18n库,内置英文、俄文和韩文翻译

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

在项目目录运行 npm install @djangocfg/i18n，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 i18n，可以用 npx i18n 直接运行。

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

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

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

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

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

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

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

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