如何实现多语言i18n：Cabinet 40语言+希伯来语RTL支持完整指南

如何实现多语言i18nCabinet 40语言希伯来语RTL支持完整指南【免费下载链接】cabinetAI-first knowledge base and startup OS项目地址: https://gitcode.com/gh_mirrors/cabinet3/cabinetCabinet 是一款 AI 优先的知识库与创业操作系统AI-first knowledge base and startup OS它的i18n 国际化系统原生支持 40 种语言并对希伯来语等文字从右向左书写的语言提供完整的RTL 布局支持。本文带你用最少代码看懂这套多语言方案是如何工作的——无论你是想切换界面语言的普通用户还是想给项目添加新语言的开发者都能在 5 分钟内上手。Cabinet 的多语言版图40 种语言一览表Cabinet 支持的 40 种语言按全球使用人数排序完整清单定义在 src/i18n/index.ts 的SUPPORTED_LOCALES中分类语言 中文简体中文、繁体中文 亚洲印地语、孟加拉语、日语、韩语、越南语、泰语、泰米尔语、泰卢固语、马拉地语、古吉拉特语、旁遮普语、卡纳达语、马拉雅拉姆语 欧洲西班牙语、法语、葡萄牙语、俄语、印尼语印尼/马来圈、德语、波兰语、荷兰语、乌克兰语、罗马尼亚语、希腊语、捷克语、匈牙利语、瑞典语 RTL 右起书写希伯来语、阿拉伯语、波斯语 其他斯瓦希里语、菲律宾语、豪萨语、约鲁巴语、英语默认其中希伯来语是首个内置 RTLRight-to-Left从右向左能力的语言。Cabinet 预留了RTL_LOCALE_PREFIXES [he, ar, fa, ps, ur]前缀表未来阿拉伯语、波斯语等右起语言一旦补齐翻译会自动进入 RTL 渲染通道——架构上早已铺好路。还没支持你的语言Cabinet 内置了语言请求面板REQUESTABLE_LOCALES里列出了 40 种可请求语言点击即可向团队提交需求团队会按需求量排期翻译。i18n 三大核心组件翻译文件、Hook、首屏引导Cabinet 选择了react-i18nexti18next作为国际化框架选型理由见 docs/I18N_RTL_HEBREW_PRD.mdElectron 桌面应用以file://加载静态导出页面路由前缀式方案不可靠而 Provider 式方案零路由假设。整个系统由三块拼成1️⃣ 每个语言一份 JSON 翻译文件每种语言对应src/i18n/locales/下一个文件按业务模块agents、sidebar、editor、settings、tour、errors 等分层组织英文基准src/i18n/locales/en.json约 2100 行希伯来语src/i18n/locales/he.json约 2000 行翻译缺失时逐键回退到英文任何漏翻的键都不会让界面出现空白——这是桌面应用稳定性的关键设计。2️⃣ useLocale 钩子一行代码切换语言与方向核心逻辑在 src/i18n/use-locale.tst()翻译函数直接取自react-i18nextlocale/setLocale()读写语言偏好持久化到localStorage键名cabinet-locale并通过自定义事件广播界面无需重启即时切换dir由localeToDir()自动推导ltr | rtl可直接用于 JSX 与 CSS切换希伯来语时applyDocumentLocale()会同时更新html langhe与html dirrtl并触发loadCjkFonts()见 src/lib/themes.ts按需加载 CJK 字体。3️⃣ 首屏引导脚本消灭 RTL 闪烁在 src/app/layout.tsx 中一段内联脚本在水合之前读取localStorage里的语言偏好第一时间把lang和dir写到html上。这样希伯来用户首次打开应用就不会看到先左到右、再弹跳成右到左的视觉闪烁FOUC首帧即是正确的 RTL 方向。希伯来语 RTL 布局整屏镜像的四个细节RTL 不是简单把文字调个头Cabinet 在四个层面做了处理html dirrtl整站镜像Tailwind 中约 73% 的方向工具类已使用逻辑属性ms-*/me-*布局随方向自动翻转。组件库方向提供者src/components/layout/locale-direction-provider.tsx 包裹整个应用把当前方向喂给 Base UI 的DirectionProvider——所有菜单、弹层、工具提示的展开方向与键盘导航随语言一次翻齐。希伯来字体回退15 套主题全部配备希伯来字符集回退品牌 Logo 在 RTL 下切换为支持希伯来斜体的 Cardo 衬线字体见 src/app/layout.tsx 中--font-logo-rtl的定义。AI Agent 也切换语言会话运行器会把当前 locale 注入系统提示词Agent 用你的语言回复生成的笔记在dir缺省时继承应用语言方向用户仍可对单篇文档单独指定dir: ltr | rtl希伯来用户照样能写英文笔记。日期与数字本地化Intl 原生格式器多语言不止是换词。src/i18n/formatters.ts 基于浏览器原生IntlAPI 提供四个格式器函数作用示例希伯来语 he-ILformatDate日期本地化日期样式formatTime时间12/24 小时制随语言formatNumber数字千位分隔符本地化formatRelative相对时间3 天前式表达每个语言都会映射到一个精确的 BCP-47 标签如he → he-IL、zh-TW → zh-TW确保以色列希伯来与中国台湾中文各自得到地道格式。翻译工作流四步提取、检查、报告、生成Cabinet 把 i18n 工程化到了流水线级别四条 npm 脚本定义于 package.json命令脚本用途npm run i18n:extractscripts/i18n-extract.mjs从组件源码提取所有t()键生成/更新语言 JSONnpm run i18n:check同上--check校验键完整性缺失即报错npm run i18n:reportscripts/i18n-find-hardcoded.mjs扫描仍硬编码在 JSX 里的英文字符串揪出漏网之鱼npm run i18n:translatescripts/i18n-translate.mjs以en.json为基准批量生成其余 39 种语言译文Gemini JSON 模式希伯来语是团队内母语者主导的人工质量语言其余语言为机器翻译生成 逐键英文兜底——贡献者流程详见 docs/CONTRIBUTING_I18N.md。如何切换语言 如何添加新语言普通用户在设置或首次运行向导中选择语言即可界面即时翻转、偏好自动保存应用还会通过 src/i18n/detect-system-locale.ts 读取操作系统首选语言开箱即用本地化引导——但用户的选择永远优先自动检测不会覆盖你的手动选择。开发者新增一种语言的完整路径是在SUPPORTED_LOCALES与LOCALE_LABELS中登记新语言src/i18n/index.ts为 RTL 语言确认前缀已列入RTL_LOCALE_PREFIXES并同步src/app/layout.tsx中的内联引导脚本在formatters.ts的LOCALE_TO_BCP47中补一个 BCP-47 标签放置src/i18n/locales/code.json译文可先用i18n:translate生成骨架再润色小结一套可扩展的 i18n 架构Cabinet 的多语言方案值得借鉴的地方在于分层清晰翻译文件只管文案useLocale钩子只管切换DirectionProvider只管镜像Intl只管格式。希伯来语 RTL 是最难的一块骨头——啃下它之后再增加中文、西班牙语等左起语言基本只需一份翻译文件。如果你想深入了解设计决策的来龙去脉建议阅读 docs/I18N_RTL_HEBREW_PRD.md它完整记录了从英文硬编码到 40 语言 RTL 的演进路线。【免费下载链接】cabinetAI-first knowledge base and startup OS项目地址: https://gitcode.com/gh_mirrors/cabinet3/cabinet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考