OpenResearch国际化实现全解三语文案目录与校验脚本【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearchOpenResearchorx是一款把编程智能体变成科研智能体的开源工具其前端界面内置了完整的国际化i18n体系6 种语言的文案目录 一套自动化校验脚本保证任何语言下界面文案都不会出现缺字、错键。这篇文章带你完整看懂它的三语文案目录结构、Paraglide 运行时接入方式以及那个把关文案一致性的 lint 脚本是怎么工作的。一、先看文案目录6 份语言文件1175 个键所有可翻译文案都集中存放在 ui/messages/ 目录下每个语言一个 JSON 文件语言文件语言文案键数en.json英语基准语言1175zh-CN.json简体中文1175fa.json波斯语RTL 从右到左1175ar.json阿拉伯语RTL1175es.json西班牙语1175hi.json印地语1175语言清单由 ui/project.inlang/settings.json 统一定义其中baseLocale: en声明英语为基准语言——所有其他语言都要和它对齐这正是后面校验脚本的工作基准。文案键名采用模块前缀_语义的命名规范例如common_save: Save, settings_cpu_cores: CPU cores: {count}, workspace_tools_heading: Workspace带{count}这样的花括号表示占位符会被真实数据动态填充。以简体中文为例settings_cpu_cores对应{count} 个 CPU 核心——数字与文字的位置可以随语言自由调整而不用像字符串拼接那样硬拼。上图这类科研图表正是 OpenResearch 的典型产物当用户在设置中切换语言后界面标题、按钮、状态提示等文本会即时换成对应语言而数据图表保持不变。二、运行时Paraglide 类型安全调用文案目录本身只是静态数据真正让它跑起来的是 ui/package.json 中引入的Paraglideinlang/paraglide-js。构建时会执行paraglide-js compile把 6 份 JSON 编译成类型安全的m消息对象组件中这样使用import { m } from ./paraglide/messages.js; m.settings_language_heading(); // 当前语言下返回 Language / 语言 等好处在于键名写错在编译期就会报错而不必等到某位波斯语用户打开界面才发现。语言切换逻辑在 ui/src/locale.ts 中核心就三件事调用 Paraglide 的setLocale并设置reload: false——切换语言无需刷新页面同步更新html lang属性让屏幕阅读器与 CSS 方向规则正确工作通知所有订阅组件重新渲染。用户在 SettingsPage.tsx 的Language行点击下拉框即可切换选中后立即生效。此外ui/src/i18n.ts 还提供了两个贴心的小工具fmtNumber()用Intl.NumberFormat按当前语言格式化数字不同语言千分位符号不同ltr()/autoDir()向文本中嵌入 Unicode 方向控制符解决波斯语、阿拉伯语这类RTL从右到左排版中英文数字或变量名被拽乱方向的经典难题。三、校验脚本check-i18n.mjs 的 5 道关卡手动维护 6 份 × 1175 个键的文案稍有疏漏就会出现中文缺键显示英文或占位符丢失。OpenResearch 的答案是 ui/scripts/check-i18n.mjs它作为构建链的第一环运行pnpm lint:i18n paraglide-js compile ... vite build即lint 不通过构建直接中止。脚本逻辑清晰共五道关卡关卡检查内容示例报错1. 文件可读每个语言的 JSON 能否正常加载fa: ... ENOENT2. 键缺失相对英语基准是否有 key 没译zh-CN: missing keys: common_save3. 键漂移是否出现基准中不存在的多余 keyfa: unexpected keys: ...4. 值合法值必须是非空字符串empty or non-string values: ...5. 占位符一致 HTML 实体{xxx}集合需与英语完全一致不允许残留amp;等未解码实体placeholder mismatch: ...其中占位符一致性是最容易被忽视的坑如果中文写成CPU 核心数漏掉{count}运行时数字就永远显示不出来——脚本通过正则提取两侧占位符并排序比对一眼揪出。脚本的健壮性本身也有一层测试保障ui/tests/i18nCatalog.test.mjs 用node:test构造了 4 组故障场景删掉 fa.json、删除common_save键、塞入陌生键、把值改成空串和数字断言脚本每种情况都必须以非零码退出并输出对应错误信息。四、新手贡献翻译的实操清单 如果你想为 OpenResearch 增加一种语言或补译缺失文案流程很直接在 ui/project.inlang/settings.json 的locales数组中登记语言码复制一份en.json到 ui/messages/ 作为新语言文件逐键翻译保留所有{placeholder}占位符不要翻译、不要删除值中直接写 Unicode 字符如、é不要写 HTML 实体运行node scripts/check-i18n.mjs全绿即可提交。这套目录 类型化运行时 构建期 lint的组合是中小规模前端项目做多语言最省心的一条路线文案集中在 messages/ 目录可整体交给译者机器负责兜底一致性。【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考