Claude Code Router 多语言 i18n 配置：新增一门语言只动 2 个文件的完整指南-平芜编程栈

Claude Code Router 多语言 i18n 配置：新增一门语言只动 2 个文件的完整指南

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

Claude Code Router 是统一管理多个 AI Agent 的本地控制平面，其管理界面内置了中英文国际化（i18n）多语言能力。如果你的需求是"给界面加一门日语或韩语"，最短路径是：2 个文件、2 行配置、0 处组件改动。下面从一个真实问题讲起——到底要动哪几处，动到什么程度算够。

一、先定位：界面里的文字是从哪来的

这一步你会得到一个明确结论：界面文案只集中在两个 JSON 文件和一个初始化文件里，组件本身不存任何翻译。

Claude Code Router 的国际化基于 i18next 框架。运行时的逻辑链条只有三段：

LanguageDetector插件读取浏览器语言偏好，决定当前语言；
resources对象把各语言 JSON 文件挂载进 i18next；
组件通过useTranslation钩子拿到t函数，用键名换取对应语言的文案。

组件里不写死任何界面文字，写死的只有键名。这决定了改语言的边界：翻译在数据文件里，逻辑在初始化文件里，组件永远不用碰。

二、新增一门语言的最短路径：只加不改

这一步你会拿到从零到可用的完整操作清单——以日语为例，全程不修改任何现有代码。

第 1 步：创建语言文件。新建ui/src/locales/ja.json。先完整复制ui/src/locales/en.json的键结构，再逐条替换 value 为日语。注意：键照抄，只改值，任何一条键的增删都会导致界面出现未翻译的裸键名。

第 2 步：在初始化文件里注册。打开ui/src/i18n.ts，改动只有 2 行——一段 import，加上 resources 里的一行登记：

import ja from "./locales/ja.json"; resources: { en: { translation: en }, zh: { translation: zh }, ja: { translation: ja }, // 新增的 1 行 },

第 3 步：构建验证。把浏览器语言环境切到日语（或在地址栏手动指定语言），刷新页面。LanguageDetector会自动识别到已注册的ja并启用，无需额外配置。

这条路径的价值在于"只加不改"：en.json、zh.json和所有 React 组件一行不动，现有中英文用户零感知。

三、翻译键地图：键怎么组织、怎么安全地新增与改名

这一步你会看清键的层级规则，以及一个改名操作前后要同步的完整清单。

翻译键是两层结构：

第一层：功能模块，如common、app、login；
第二层：模块内的具体文案，如title、description、save。

命名用 snake_case，且同一把键在所有语言文件里必须完全一致——i18next 靠键对齐来切换语言，键不一致等于这条文案在该语言下失踪。

新增键很简单：在app下加一行"welcome": "欢迎回来，{{name}}"，然后组件里t("app.welcome")即可。但改名是另一回事，改前 / 改后对比：

// 改前：扁平命名 { "login": { "api_key_input": "API Key" } }

// 改后：按语义归位 { "login": { "apiKey": "API Key" } }

一次改名要同步 3 处：en.json、zh.json（以及你新加的任何语言文件）、所有引用t("login.api_key_input")的组件。所以规则只有一条：上线后不轻易改键名，宁可新增同义键，也不批量重命名。

四、让它更聪明：自动检测、回退与参数化

这一步你会用到 3 个进阶能力：不用用户手动选语言、缺翻译不露馅、一句话模板适配多个值。

语言自动检测。LanguageDetector从浏览器的navigator.language读取偏好，用户装好日语环境后无需任何设置。个别场景需要强制指定时，1 行代码：

i18n.changeLanguage("zh");

回退语言fallbackLng。初始化时配置了fallbackLng: "en"，意味着日语文件里哪怕漏了一条app.save，界面会显示英文 "Save" 而不是键名app.save。新增小语种时这层兜底非常关键——你可以先交付一个"日语 + 英文补丁"的半成品，不阻塞上线。

参数化翻译。动态内容不要拼接字符串，用 i18next 的{{name}}占位符：

{ "app": { "welcome": "欢迎回来，{{name}}" } }

t("app.welcome", { name: userName });

模板写在语言文件里、变量写在调用处，各语言可以按自己的语法调整语序和敬语，代码侧完全不用分支判断。

五、🔍 i18n 排错速查表

这一步你得到一个对照表：90% 的国际化问题都能在这里对号入座。

现象	可能原因	解法
界面显示裸键名（如`app.save`）	组件里的键与语言文件中的键拼写不一致	对照`en.json`逐字符核对键名
新语言切了不生效，仍显示英文	新语言没在`resources`里注册	检查`i18n.ts`的 import 与登记行
某条新文案是英文	只在部分语言文件里加了条目	以`en.json`为基准补齐所有语言
切换语言后布局溢出、换行错乱	中日英文本长度差异大	容器用自适应宽度，不要写死像素
界面原样显示`{{name}}`	调用`t()`时参数名与占位符不一致	对齐`t("app.welcome", { name: ... })`的变量名
改完语言文件后界面不更新	浏览器缓存或构建产物未刷新	强制刷新页面或重新构建