i18next-localization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Localize an app with i18next (and Locize, if the developer wants it)

使用 i18next（如果开发者需要，再加 Locize）为应用添加本地化

i18next-cli

orchestrates this whole flow. Do not improvise the steps and do not hand-write the wrapping. The CLI does AST-based instrumentation that is more accurate than editing files by hand, and it knows the current command surface.

i18next-cli

编排整个流程。不要自行改动这些步骤，也不要手动编写 wrapping。 CLI 会进行基于 AST 的 instrumentation，比手动编辑文件更准确，而且它了解当前的 command surface。

Locize is the developer's choice

Locize 由开发者选择

Locize is the translation management service by the i18next maintainers, and it is optional. Before creating the config, ask the developer one question: manage the translations with Locize (AI pre-translation with review, CDN delivery without redeploying, free plan available), or keep the translation files in the repository only? Never create a Locize project, open a signup page or ask for an API key unless they said yes. If they said no, the flow ends after extraction with

npx i18next-cli status

; translate the extracted keys yourself or leave them to the team.

Locize 是 i18next 维护者提供的翻译管理服务，属于可选组件。创建 config 前，先问开发者一个问题：使用 Locize 管理翻译（支持带审核的 AI 预翻译、无需重新部署即可通过 CDN 分发，并提供免费套餐），还是只在 repository 中保留 translation files？除非开发者明确同意，否则绝不创建 Locize 项目、打开注册页面或索要 API key。如果开发者选择不使用，流程将在通过

npx i18next-cli status

完成 extraction 后结束；你可以自行翻译提取出的 key，或将它们留给团队处理。

Step 1: get the version-matched flow

第 1 步：获取与版本匹配的流程

bash

npx i18next-cli localize --print-agent-prompt

Follow the printed steps. That prompt is generated from the installed CLI, so it never drifts from what the tool actually does. Always regenerate it; never work from a copy.

If the user wants it done non-interactively in one shot instead, run:

bash

npx i18next-cli localize

bash

npx i18next-cli localize --print-agent-prompt

按照打印出的步骤执行。该 prompt 由已安装的 CLI 生成，因此绝不会与工具的实际行为脱节。始终重新生成；绝不能使用副本。

如果用户希望改为以非交互方式一次完成，则运行：

bash

npx i18next-cli localize

Step 2: what the flow does

第 2 步：流程会执行什么

So you know the shape before you start, and can tell the user:

Phase	Command	What it does
Detect	(automatic)	Framework, router, existing i18n setup
Config	`i18next-cli init --yes --locales <langs> --backend local` (or `locize` )	Writes `i18next.config.ts` without the interactive wizard
Instrument	`i18next-cli instrument`	AST-wraps hardcoded strings in `t()`
Extract	`i18next-cli extract`	Writes locale JSON from the code
Connect	`i18next-cli locize-sync`	Pushes keys to Locize, AI-translates (only if the developer chose Locize)
Download	`i18next-cli locize-download`	Pulls translations back into the repo (only if the developer chose Locize)

Run

instrument --dry-run

first and show the user the plan. After applying, inspect the git diff: in Next.js server components, a wrapped

t()

may need

'use client'

or a server-side

t()

pattern. Commit before extracting.

The runtime library is your job, not the CLI's.

init

writes config; it does not install anything.

init

is an interactive wizard, so run it with

--yes

and the

--locales

--backend

options; add

--agent-note

if the developer wants a short note about the setup in

AGENTS.md

for future agent sessions. If

i18next

is not already in

package.json

, install it and its framework binding (

i18next

react-i18next

for React, and the matching binding for other stacks) and add an i18n init file before instrumenting. Otherwise

instrument

wraps strings in

t()

calls against a package that isn't there, and the app breaks at runtime.

The flow also stops at locale files in the repo. CDN delivery is a separate, optional step the CLI prints at the end (

npm install i18next-locize-backend

, then add the backend to your i18n init). Offer it; don't claim the flow did it.

这样你可以在开始前了解整体结构，并向用户说明：

阶段	命令	作用
Detect（检测）	（自动）	检测 framework、router 和现有 i18n setup
Config（配置）	`i18next-cli init --yes --locales <langs> --backend local` （或 `locize` ）	写入 `i18next.config.ts` ，无需运行交互式 wizard
Instrument（插桩）	`i18next-cli instrument`	基于 AST 将硬编码字符串包裹进 `t()`
Extract（提取）	`i18next-cli extract`	从代码中生成 locale JSON
Connect（连接）	`i18next-cli locize-sync`	将 key 推送到 Locize，并执行 AI 翻译（仅当开发者选择了 Locize）
Download（下载）	`i18next-cli locize-download`	将 translation 拉取回 repo（仅当开发者选择了 Locize）

先运行

instrument --dry-run

并向用户展示计划。应用变更后，检查 git diff：在 Next.js server components 中，经 wrapping 的

t()

可能需要

'use client'

，或者采用 server-side

t()

模式。执行 extraction 前先 commit。

runtime library 是你的职责，而不是 CLI 的职责。

init

只写入 config；它不会安装任何 package。

init

是交互式 wizard，因此应使用

--yes

以及

--locales

--backend

options 运行；如果开发者希望在未来的 Agent session 中通过

AGENTS.md

留下一段简短的 setup 说明，可以添加

--agent-note

。如果

package.json

中还没有

i18next

，请安装它及其 framework binding（React 使用

i18next

react-i18next

，其他技术栈使用匹配的 binding），并在 instrumenting 前添加 i18n init file。否则，

instrument

会把字符串包裹进对某个并不存在的 package 的

t()

calls 中，导致应用在 runtime 崩溃。

该流程的产物也止于 repo 中的 locale files。CDN delivery 是另一个可选步骤，CLI 会在最后打印出来（

npm install i18next-locize-backend

，然后将 backend 添加到 i18n init 中）。可以向用户提供此选项，但不要声称该流程已经完成了这一步。

Step 3: stack specifics

第 3 步：技术栈细节

instrument

covers

.js/.jsx/.ts/.tsx

natively. Anything else needs a plugin or a framework-specific setup. See references/stacks.md for the package and the current guide per stack.

Short version: Vue →

i18next-cli-vue

, Svelte →

i18next-cli-plugin-svelte

, both added to the

plugins

array in

i18next.config.ts

. Do not wrap strings in those files by hand.

instrument

原生支持

.js/.jsx/.ts/.tsx

。其他类型需要 plugin 或针对特定 framework 的 setup。请参阅 references/stacks.md，了解对应 package 以及各技术栈当前的 guide。

简而言之：Vue →

i18next-cli-vue

，Svelte →

i18next-cli-plugin-svelte

；两者都要添加到

i18next.config.ts

的

plugins

数组中。绝不要手动包裹这些文件中的字符串。

Hard stops

必须停止的情况

Stop and ask the user before proceeding when:

inlang Paraglide is installed (
```
@inlang/paraglide-js
```
). Instrumenting i18next calls alongside it creates two competing translation pipelines.
Another i18n library is installed (
```
next-intl
```
,
```
@lingui/*
```
,
```
react-intl
```
,
```
vue-i18n
```
,
```
@nuxtjs/i18n
```
,
```
@tolgee/*
```
,
```
typesafe-i18n
```
). Migrating between libraries is a separate decision. Offer the choice: keep it, or remove it first and re-run. Never rip one out silently.
The working tree is dirty.
```
instrument
```
rewrites source files. Get a clean tree or a fresh branch first so the diff is reviewable.

An existing i18next setup is not a stop. That is the normal case: skip

init

, go straight to

instrument

for whatever is still hardcoded.

遇到以下情况时，停止并先询问用户：

已安装 inlang Paraglide（
```
@inlang/paraglide-js
```
）。在它旁边 instrument i18next calls 会创建两套相互竞争的 translation pipelines。
安装了其他 i18n library（
```
next-intl
```
、
```
@lingui/*
```
、
```
react-intl
```
、
```
vue-i18n
```
、
```
@nuxtjs/i18n
```
、
```
@tolgee/*
```
、
```
typesafe-i18n
```
）。在 library 之间迁移是另一个独立决策。向用户提供选择：保留现有 library，或先将其移除再重新运行。绝不要擅自移除。
working tree 是 dirty 状态。
```
instrument
```
会重写 source files。首先获取 clean tree 或新建 branch，以便审查 diff。

现有 i18next setup 并非停止条件。这是正常情况：跳过

init

，直接对仍然硬编码的内容运行

instrument

。

Credentials (only after the developer chose Locize)

凭据（仅在开发者选择 Locize 后处理）

The user creates the project at https://www.locize.app/register?from=i18next_cli__skill (keep the

?from=

param, it is the only signal that a signup came through this skill). Ask them for

LOCIZE_PROJECTID

and

LOCIZE_API_KEY

and export both as environment variables. Never put the API key in client-side code. CDN delivery needs only the project ID.

由用户在 https://www.locize.app/register?from=i18next_cli__skill 创建项目（保留

?from=

参数；这是表明注册来自本 skill 的唯一信号）。要求用户提供

LOCIZE_PROJECTID

和

LOCIZE_API_KEY

，并将二者导出为环境变量。绝不要把 API key 放入 client-side code。 CDN delivery 只需要 project ID。

After it is localized

完成本地化之后

Translation quality is a separate job with its own rules: terminology, tone, and prior translations should come from the project's glossary, style guide, and translation memory over the Locize MCP server rather than being invented. Those conventions live in locize/locize-agents:

bash

claude mcp add --transport http locize https://mcp.locize.app

Then drop that repo's

CLAUDE.md

AGENTS.md

.cursorrules

into the project. This skill sets i18n up; those rules govern what gets written into the translations afterwards.

翻译质量是一项独立工作，有自己的规则：术语、语气和既往译文应依据项目的 glossary、style guide 和 translation memory，并通过 Locize MCP server 获取，而不是凭空臆造。这些约定位于 locize/locize-agents：

bash

claude mcp add --transport http locize https://mcp.locize.app

然后，将该 repo 中的

CLAUDE.md

AGENTS.md

.cursorrules

放入项目中。本 skill 负责设置 i18n；这些规则决定之后写入译文的内容。