Tolaria国际化实现指南：JSON语言目录与Lara CLI同步机制一文讲透

Tolaria国际化实现指南JSON语言目录与Lara CLI同步机制一文讲透【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 是一款用于管理 Markdown 知识库的跨平台桌面应用其**国际化i18n**体系围绕“JSON 语言目录 Lara CLI 自动同步”两大核心构建。本文将带你走通从翻译目录组织、机器翻译同步、键位校验到运行时语言回退的完整链路帮你快速看懂 Tolaria 是如何支撑 21 种界面语言的 。为什么Tolaria自研国际化层而不是引入重型框架Tolaria 的国际化分两步演进ADR-0084本地化地基建立了一个零依赖的前端本地化层 src/lib/i18n.ts。英文作为权威回退语言canonical fallback缺失的翻译键自动回退到英文因此“部分翻译”的语言也不会让界面崩溃。详见 docs/adr/0084-app-localization-foundation.md。ADR-0087JSON目录 Lara CLI为了让翻译扩展到更大的语言矩阵并支持机器辅助翻译工作流翻译数据源从 TypeScript 对象迁移到扁平 JSON 目录flat JSON catalogs。详见 docs/adr/0087-json-catalogs-and-lara-cli-localization.md。这个取舍非常务实JSON 是翻译工具链的标准交换格式diff 对译者更友好且不引入额外运行时依赖。JSON语言目录en.json是唯一事实来源所有翻译文案存放在 src/lib/locales/ 目录下一个语言一个文件en.json、zh-CN.json、fr-FR.json……共 21 个目录。以简体中文目录 src/lib/locales/zh-CN.json 为例内容就是扁平的“键 → 字符串”映射{ command.noMatches: 没有匹配的命令, command.aiMode: {agent} 模式, menu.file.save: 保存 }两条硬性约定由校验脚本强制执行值必须是纯字符串不允许嵌套对象或数组占位符必须与英文源一致例如{agent}、{zoom}、{language}、{count}等变量在翻译中不能被删改或重排。Lara CLI 配置一条命令同步 20 种目标语言Lara CLI 的项目配置位于仓库根目录的 lara.yaml核心只有三段instruction给翻译引擎的指令要求保留产品名、CLI 名称、wikilink、frontmatter 键、文件路径以及{agent}等占位符原样不动locales声明source: en并列出 20 个目标语言——zh-CN、zh-TW、ja-JP、ko-KR、fr-FR、de-DE、es-ES、es-419、pt-BR、pt-PT等files通过src/lib/locales/[locale].json通配规则告诉 Lara 翻译目录的位置。实际执行通过 package.json#L18-L20 中定义的脚本完成脚本命令作用pnpm l10n:translatelara-cli translate同步翻译增量pnpm l10n:translate:forcelara-cli translate --force强制全量重译pnpm l10n:validatenode scripts/validate-locales.mjs校验所有语言目录翻译结果直接写回仓库中的 JSON 文件与使用它们的 UI 代码同版本管理、一起发布。运行时解析语言别名归一化与英文回退运行时逻辑集中在 src/lib/i18n.ts几个关键机制值得新手了解目录按需加载import.meta.glob(./locales/*.json)在构建期把所有 JSON 目录加载进内存新增语言文件即自动生效语言别名归一化normalizeLocaleCode()把zh-hans、zh-Hans、zh等写法统一映射到规范代码zh-CN历史遗留的zh-Hans偏好也会被自动迁移系统语言回退用户偏好ui_language是安装级设置存于~/.config/com.tolaria.app/settings.json取值为空时表示“跟随系统语言”resolveEffectiveLocale()会依次尝试系统语言列表最终兜底到英文props-down 传值locale 从App.tsx逐层向下传给组件遵循 docs/adr/0026-props-down-no-global-state.md 的无全局状态架构切换语言无需重开仓库、立即生效。语言校验键位与占位符一致性把关scripts/validate-locales.mjs 是本地化工作流的“质量闸门”它逐语言检查目录是否为扁平字符串对象与en.json相比是否缺少键missing或多出键extra每个键的占位符集合是否与英文源完全一致。任何一项不通过脚本都会列出具体错误并以非零码退出可挂进 CI 或作为提交前检查。快速上手新增一种语言的完整流程在 src/lib/i18n.ts 的APP_LOCALES和LOCALE_DEFINITIONS中登记语言代码、别名与搜索关键词在 lara.yaml 的locales.target中加入目标语言运行pnpm l10n:translate生成翻译 JSON人工审校 JSON 输出专有名词、占位符运行pnpm l10n:validate确认通过即可发布。整个流程对使用者同样简单打开 Tolaria 的设置面板或命令面板执行“打开语言设置 / 使用系统语言”相关命令即可切换界面语言所有未翻译的文案都会自动显示英文体验不受影响 ✅。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考