BISHENG 前端 i18n 国际化规范与实践：基于 i18next 的三语言架构与命名体系解析

BISHENG 前端 i18n 国际化规范与实践：基于 i18next 的三语言架构与命名体系解析

【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng

导读

本文聚焦开源 LLM DevOps 平台 BISHENG 前端客户端的国际化（i18n）工程实践，以仓库内.agents/skills/i18n-localizer/resources/CONVENTIONS.md规范文档为核心骨架，结合 i18n 初始化源码、useLocalize 钩子实现 以及三份真实的翻译资源文件，系统讲解该项目的语言技术栈、翻译文件组织、Key 命名约定、嵌套命名空间格式、插值与复用机制，以及组件中的标准调用方式。读完本文，你将掌握 BISHENG 前端国际化约定的全貌，能够在src/frontend/client中正确新增翻译 Key、组织命名空间，并理解其在运行时如何完成语言检测、品牌变量注入与语言热切换。

一、技术栈与多语言支持范围

BISHENG 前端客户端（src/frontend/client）的国际化方案基于i18next生态，仓库package.json中实际锁定的版本为：

项目共支持三种语言，每种语言对应一份完整的 JSON 翻译文件：

• en（English）→ src/frontend/client/src/locales/en/translation.json（约 2374 行）
• zh-Hans（简体中文）→ src/frontend/client/src/locales/zh-Hans/translation.json（约 2303 行）
• ja（Japanese）→ src/frontend/client/src/locales/ja/translation.json

三份文件均挂在resources对象下，并在 i18n.ts 中以{ language: { translation: <json> } }的结构注册到 i18next 实例，命名空间（namespace）统一为translation，这也是defaultNS的取值。

二、文件位置与职责分工

项目将国际化相关文件集中在src/frontend/client/src/locales/与src/frontend/client/src/hooks/两个目录下，职责划分如下表：

这种"初始化 + 资源文件 + 业务 Hook"的三层结构，使得翻译数据的加载、运行时语言切换和组件消费解耦：翻译内容只存在于 JSON 中，组件从不直接书写文案字符串，而是通过 Hook 拿到翻译函数localize(key, options)。

三、Key 命名规范：域名命名空间与命名规则

3.1 域名命名空间（Domain Namespaces）

翻译 Key 按业务域（domain）组织。每个业务域对应 JSON 中的一个顶层对象，CONVENTIONS.md 定义了如下命名空间及其覆盖范围：

从仓库实际资源文件看，除上述定义外，随着版本演进还出现了额外的嵌套命名空间，例如com_subscription（订阅/频道配额）、com_permission（权限）、com_approval（审批）以及api_errors（API 错误码文案）、workstation（工作台）等，均在 en/translation.json 中作为顶层嵌套对象存在。这说明命名空间体系是开放、可扩展的，新增业务域时遵循同样的"com_前缀 + 业务名"模式即可。

3.2 Key 命名规则

新增 Key 时必须遵守四条硬性规则：

1. snake_case：全部小写，单词间用下划线连接，如space_create_success；
2. 描述性且精简：长度控制在 2～5 个单词；
3. 同类操作使用统一后缀：_success、_error、_failed、_confirm、_placeholder、_title、_desc。例如 zh-Hans 的 com_knowledge 命名空间 中，web_link_import_success、web_link_import_failed、web_link_url_placeholder、web_link_import_title即体现了这一约定；
4. 禁止把翻译文本写进 Key 名：Key 是稳定的标识符，文案变化只改 JSON 值，不改 Key。

3.3 实例验证：真实资源文件中的命名空间布局

通过解析仓库实际 JSON（python json.load统计）可以看到当前状态：

• en 翻译文件顶层共 1355 个 Key，其中 1348 个为扁平（legacy）Key，7 个为嵌套命名空间对象（api_errors、com_app、com_knowledge、com_subscription、com_permission、com_approval、workstation）；
• zh-Hans 与 ja 的结构与 en 保持一致（同样 7 个嵌套命名空间），保证了三种语言 Key 集合的对齐。

这印证了 CONVENTIONS.md 的核心设计：扁平旧 Key 保持原样，新 Key 全部进入嵌套命名空间，且三语言文件结构严格同步。

四、JSON 文件格式：扁平旧 Key 与嵌套新 Key 的共存

4.1 不可回写的 Legacy Key

[!IMPORTANT]Legacy keys（扁平格式，如"com_ui_cancel": "Cancel"）必须原样保留，禁止重构为嵌套格式。

这是最重要的兼容性红线。历史遗留 Key 散落在根层级，例如 en/translation.json 第 1 行起的扁平 Key：

"admin": "Administrator", "bisheng": "{{bisheng}}", "cancel": "Cancel", "com_a11y_ai_composing": "The AI is still composing.", "com_account_info_basic_info": "Basic information",

如果重构这些 Key，会导致所有仍在以旧 Key 调用翻译的组件出现文案丢失（回退到 Key 本身）或测试失败。因此新增与迁移的边界非常清晰：旧的不动，新的走嵌套。

4.2 新增 Key 的嵌套格式

新 Key 必须使用按域名命名空间分组的多层对象：

{ "com_ui_cancel": "Cancel", "com_ui_delete": "Delete", "com_knowledge": { "space_create_success": "Knowledge space created", "space_deleted": "Space has been dissolved", "folder_max_depth": "Folder depth limit reached (10 levels)", "drop_to_upload": "Drop files here to upload" } }

三条布局规则：

1. 旧的扁平 Key 停留在根层级，保持原样；
2. 新 Key 放入各自的命名空间对象（如com_knowledge.space_create_success），组件中以点号（dot notation）访问；
3. 每个命名空间对象内部按字母序排序；命名空间对象整体排在所有扁平 Key 之后，也按字母序排列。

仓库中 com_app 命名空间 的center_title、empty_go_explore、explore_more、recent_apps_hint、service_maintenance_title、refresh即按字母序排列的典型实例；com_knowledge 命名空间 中web_link_*系列则展示了同一业务对象下用后缀区分场景的密集命名。

五、插值（Interpolation）与 Key 复用

5.1 三种插值模式

CONVENTIONS.md 定义了项目统一的插值语法，仓库资源文件中均有大量真实用例：

实测统计显示，en 资源文件中{{0}}位置参数出现 74 处、{{count}}出现 8 处、{{name}}出现 5 处，$t(...)内联引用（如$t(bisheng)、$t(linsight)）也已被实际使用，说明这几种模式都是生产代码中的"活"语法。

5.2 品牌变量注入：defaultVariables

除了常规插值，i18n.ts 在interpolation.defaultVariables中注入了全局默认变量，使所有语言文件都能直接引用品牌名而不写死：

interpolation: { escapeValue: false, defaultVariables: { bisheng: config.brandName?.en || 'BISHENG', bishengZh: config.brandName?.zh || 'BISHENG', linsight: config.linsightAgentName?.en || 'Linsight', linsightZh: config.linsightAgentName?.zh || '灵思', linsightFull: 'Linsight', linsightFullZh: '灵思 Linsight', dailyFullName: 'Daily Mode', dailyFullNameZh: '日常模式', } }

其中config取自window.BRAND_CONFIG，允许品牌定制（如自定义产品名）在运行时注入。这正是 en 资源文件中"bisheng": "{{bisheng}}"这类 Key 能正常渲染的原因：{{bisheng}}由默认变量在运行时替换为实际品牌名。注意escapeValue: false是 react-i18next 与 React 组合时的标准配置（React 本身负责 XSS 转义）。

六、组件中的标准用法

6.1 导入方式

// 推荐：从 barrel 导出统一引入 import { useLocalize } from "~/hooks"; // 备选：直接导入 import useLocalize from "~/hooks/useLocalize";

6.2 组件内调用

function MyComponent() { const localize = useLocalize(); return ( <div> {/* 新嵌套 Key —— 使用点号访问 */} <h1>{localize("com_knowledge.title")}</h1> {/* 旧扁平 Key —— 用法不变 */} <button>{localize("com_ui_cancel")}</button> {/* 带插值 */} <p>{localize("com_knowledge.files_count", { 0: fileCount })}</p> </div> ); }

6.3 Toast 消息

showToast({ message: localize("com_knowledge.space_create_success"), severity: NotificationSeverity.SUCCESS });

useLocalize在整个前端被广泛消费——对src/frontend/client/src的检索显示，ConfirmContext.tsx、LiveAnnouncer.tsx、AccountInfoDialog.tsx、Artifacts/*、Audio/TTS.tsx等大量组件均在使用该 Hook，说明它是全站唯一的翻译入口。

6.4 useLocalize 的底层实现

useLocalize.ts 的核心逻辑如下：

export default function useLocalize() { const lang = useRecoilValue(store.lang); const { t, i18n } = useTranslation(); useEffect(() => { if (i18n.language !== lang) { i18n.changeLanguage(lang); } }, [lang, i18n]); return (phraseKey: TranslationKeys, options?: TOptions) => t(phraseKey, options); }

关键点：

• 语言状态由Recoil atom（store.lang，定义于 store/language）持有，useLocalize通过useRecoilValue订阅；
• 当 Recoil 语言与 i18next 当前语言不一致时，useEffect内调用i18n.changeLanguage(lang)触发运行时切换，从而实现不刷新页面的语言热切换；
• 返回的t函数类型为TOptions，兼容位置参数、命名参数、count等所有插值选项。

七、初始化配置与语言回退链

i18n.ts 完成了完整的 i18next 初始化，除了resources注册外，还包含值得注意的 fallback 链设计：

fallbackLng: { 'zh-TW': ['zh-Hant', 'en'], 'zh-HK': ['zh-Hant', 'en'], 'zh': ['zh-Hans', 'en'], ...(jaDisabled ? { ja: ['en'], 'ja-JP': ['en'] } : {}), default: ['en'], },

解读：

• 繁体中文（zh-TW/zh-HK）回退到zh-Hant，再回退到英文；简体中文环境（zh）回退到zh-Hans再英文；兜底语言始终是en；
• 支持运行时禁用日语：当window.APP_CONFIG.disableJa为真时，初始化前会清除localStorage中保存的i18nextLng（避免语言检测器自动恢复日语），并且把ja/ja-JP的回退链改写为直接落到英文。这使企业版可以通过配置开关（config.js 中的APP_CONFIG.disableJa）关闭日语界面而不必移除资源文件。

八、实际操作清单：新增一条翻译的完整流程

综合以上约定，在 BISHENG 前端新增一个文案的推荐操作路径如下：

1. 定位业务域：确认文案属于哪个域名命名空间（如知识库功能归属com_knowledge），若为新业务域则新建com_xxx顶层对象；
2. 起 Key：按 snake_case 命名，2～5 词，使用统一后缀（_success/_error/_placeholder/_title等），Key 内不含译文文本；
3. 落值：在 en、zh-Hans、ja 三份文件中同步添加（保持三语言 Key 结构一致），嵌套命名空间内按字母序插入，命名空间整体排在全部扁平 Key 之后；
4. 变量处理：需要动态内容时选择位置参数{{0}}、命名参数{{name}}或复数{{count}}；引用其他 Key 用$t(keyName)；品牌名直接用{{bisheng}}/{{linsight}}等默认变量；
5. 组件消费：通过import { useLocalize } from "~/hooks"获取localize，新 Key 用点号访问（localize("com_knowledge.space_create_success")），旧扁平 Key 保持原样调用；
6. 遵守红线：绝不重构/移动任何 legacy 扁平 Key。

九、总结

BISHENG 前端客户端的国际化体系可以概括为三句话：一套 i18next 三语言资源 + 一条域名命名空间约定 + 一个统一翻译 Hook。CONVENTIONS.md规范文档为贡献者划定了清晰的增量边界——旧 Key 冻结、新 Key 进命名空间、三语言同步、插值统一——而 i18n.ts 与 useLocalize.ts 则从运行时层面保证了语言检测、品牌变量注入与热切换的落地。对于需要在 BISHENG 前端新增界面文案或维护多语言资源的开发者，遵循本文梳理的命名、格式与调用规范，即可无缝融入现有国际化体系。

【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng