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中实际锁定的版本为库版本要求CONVENTIONS.md仓库实际依赖package.jsoni18nextv24^24.2.2react-i18nextv15^15.4.0i18next-browser-languagedetectorv8^8.0.3项目共支持三种语言每种语言对应一份完整的 JSON 翻译文件enEnglish→ src/frontend/client/src/locales/en/translation.json约 2374 行zh-Hans简体中文→ src/frontend/client/src/locales/zh-Hans/translation.json约 2303 行jaJapanese→ 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/两个目录下职责划分如下表文件用途src/locales/i18n.tsi18next 初始化与配置语言检测、fallback 链、插值变量src/locales/en/translation.json英文翻译src/locales/zh-Hans/translation.json简体中文翻译src/locales/ja/translation.json日文翻译src/hooks/useLocalize.ts封装useTranslation的自定义 Hook绑定 Recoil 语言状态这种初始化 资源文件 业务 Hook的三层结构使得翻译数据的加载、运行时语言切换和组件消费解耦翻译内容只存在于 JSON 中组件从不直接书写文案字符串而是通过 Hook 拿到翻译函数localize(key, options)。三、Key 命名规范域名命名空间与命名规则3.1 域名命名空间Domain Namespaces翻译 Key 按业务域domain组织。每个业务域对应 JSON 中的一个顶层对象CONVENTIONS.md 定义了如下命名空间及其覆盖范围命名空间覆盖范围com_ui通用 UI 元素按钮、标签、状态文本com_nav导航、侧边栏、顶栏、菜单com_auth认证登录、注册、密码com_endpointLLM 端点配置com_sopSOP / 任务执行功能com_knowledge知识库管理com_tools工具面板与工具相关功能com_agentAgent 相关功能com_app应用中心 / Agent 市场com_invite邀请功能com_linsightLinsight灵思专属功能com_label标签 / 打标功能com_search搜索相关功能com_file文件管理com_message聊天消息相关com_segment模式分段Mode Segment功能从仓库实际资源文件看除上述定义外随着版本演进还出现了额外的嵌套命名空间例如com_subscription订阅/频道配额、com_permission权限、com_approval审批以及api_errorsAPI 错误码文案、workstation工作台等均在 en/translation.json 中作为顶层嵌套对象存在。这说明命名空间体系是开放、可扩展的新增业务域时遵循同样的com_前缀 业务名模式即可。3.2 Key 命名规则新增 Key 时必须遵守四条硬性规则snake_case全部小写单词间用下划线连接如space_create_success描述性且精简长度控制在 25 个单词同类操作使用统一后缀_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即体现了这一约定禁止把翻译文本写进 Key 名Key 是稳定的标识符文案变化只改 JSON 值不改 Key。3.3 实例验证真实资源文件中的命名空间布局通过解析仓库实际 JSONpython json.load统计可以看到当前状态en 翻译文件顶层共 1355 个 Key其中 1348 个为扁平legacyKey7 个为嵌套命名空间对象api_errors、com_app、com_knowledge、com_subscription、com_permission、com_approval、workstationzh-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 行起的扁平 Keyadmin: 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 } }三条布局规则旧的扁平 Key 停留在根层级保持原样新 Key 放入各自的命名空间对象如com_knowledge.space_create_success组件中以点号dot notation访问每个命名空间对象内部按字母序排序命名空间对象整体排在所有扁平 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 定义了项目统一的插值语法仓库资源文件中均有大量真实用例模式示例值组件调用位置参数Positional已选择 {{0}} 个文件共 {{1}} 个文件localize(key, { 0: selected, 1: total })命名参数NamedFile: {{name}} exceeds {{size}}MBlocalize(key, { name, size })嵌套引用Nested ref$t(linsight)正在规划...由 i18next 自动解析复数计数Plural / count剩余任务次数 {{count}}次localize(key, { count: remaining })实测统计显示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 atomstore.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 前端新增一个文案的推荐操作路径如下定位业务域确认文案属于哪个域名命名空间如知识库功能归属com_knowledge若为新业务域则新建com_xxx顶层对象起 Key按 snake_case 命名25 词使用统一后缀_success/_error/_placeholder/_title等Key 内不含译文文本落值在 en、zh-Hans、ja 三份文件中同步添加保持三语言 Key 结构一致嵌套命名空间内按字母序插入命名空间整体排在全部扁平 Key 之后变量处理需要动态内容时选择位置参数{{0}}、命名参数{{name}}或复数{{count}}引用其他 Key 用$t(keyName)品牌名直接用{{bisheng}}/{{linsight}}等默认变量组件消费通过import { useLocalize } from ~/hooks获取localize新 Key 用点号访问localize(com_knowledge.space_create_success)旧扁平 Key 保持原样调用遵守红线绝不重构/移动任何 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考