企业官网建设流程全解析

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

【免费下载链接】cabinetAI-first knowledge base and startup OS项目地址: https://gitcode.com/gh_mirrors/cabinet3/cabinet

Cabinet 是一款 AI 优先的知识库与创业操作系统（AI-first knowledge base and startup OS），它的i18n 国际化系统原生支持 40 种语言，并对希伯来语等文字从右向左书写的语言提供完整的RTL 布局支持。本文带你用最少代码看懂这套多语言方案是如何工作的——无论你是想切换界面语言的普通用户，还是想给项目添加新语言的开发者，都能在 5 分钟内上手。🌍

Cabinet 的多语言版图：40 种语言一览表

Cabinet 支持的 40 种语言按全球使用人数排序，完整清单定义在 src/i18n/index.ts 的SUPPORTED_LOCALES中：

其中希伯来语是首个内置 RTL（Right-to-Left，从右向左）能力的语言。Cabinet 预留了RTL_LOCALE_PREFIXES = ["he", "ar", "fa", "ps", "ur"]前缀表，未来阿拉伯语、波斯语等右起语言一旦补齐翻译，会自动进入 RTL 渲染通道——架构上早已铺好路。💡

还没支持你的语言？Cabinet 内置了"语言请求面板"：REQUESTABLE_LOCALES里列出了 40+ 种可请求语言，点击即可向团队提交需求，团队会按需求量排期翻译。

i18n 三大核心组件：翻译文件、Hook、首屏引导

Cabinet 选择了react-i18next+i18next作为国际化框架（选型理由见 docs/I18N_RTL_HEBREW_PRD.md：Electron 桌面应用以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.ts：

• t()：翻译函数，直接取自react-i18next
• locale/setLocale()：读写语言偏好，持久化到localStorage（键名cabinet-locale），并通过自定义事件广播，界面无需重启即时切换
• dir：由localeToDir()自动推导"ltr" | "rtl"，可直接用于 JSX 与 CSS

切换希伯来语时，applyDocumentLocale()会同时更新<html lang="he">与<html dir="rtl">，并触发loadCjkFonts()（见 src/lib/themes.ts）按需加载 CJK 字体。

3️⃣ 首屏引导脚本：消灭 RTL "闪烁"

在 src/app/layout.tsx 中，一段内联脚本在水合之前读取localStorage里的语言偏好，第一时间把lang和dir写到<html>上。这样希伯来用户首次打开应用就不会看到"先左到右、再弹跳成右到左"的视觉闪烁（FOUC），首帧即是正确的 RTL 方向。🎯

希伯来语 RTL 布局：整屏镜像的四个细节

RTL 不是简单把文字调个头，Cabinet 在四个层面做了处理：

1. <html dir="rtl">整站镜像：Tailwind 中约 73% 的方向工具类已使用逻辑属性（ms-*/me-*），布局随方向自动翻转。
2. 组件库方向提供者：src/components/layout/locale-direction-provider.tsx 包裹整个应用，把当前方向喂给 Base UI 的DirectionProvider——所有菜单、弹层、工具提示的展开方向与键盘导航随语言一次翻齐。
3. 希伯来字体回退：15 套主题全部配备希伯来字符集回退；品牌 Logo 在 RTL 下切换为支持希伯来斜体的 Cardo 衬线字体（见 src/app/layout.tsx 中--font-logo-rtl的定义）。
4. AI Agent 也切换语言：会话运行器会把当前 locale 注入系统提示词，Agent 用你的语言回复；生成的笔记在dir缺省时继承应用语言方向，用户仍可对单篇文档单独指定dir: "ltr" | "rtl"，希伯来用户照样能写英文笔记。📝

日期与数字本地化：Intl 原生格式器

多语言不止是"换词"。src/i18n/formatters.ts 基于浏览器原生IntlAPI 提供四个格式器：

每个语言都会映射到一个精确的 BCP-47 标签（如he → he-IL、zh-TW → zh-TW），确保"以色列希伯来"与"中国台湾中文"各自得到地道格式。📅

翻译工作流四步：提取、检查、报告、生成

Cabinet 把 i18n 工程化到了流水线级别，四条 npm 脚本（定义于 package.json）：

希伯来语是团队内母语者主导的"人工质量"语言，其余语言为机器翻译生成 + 逐键英文兜底——贡献者流程详见 docs/CONTRIBUTING_I18N.md。

如何切换语言 & 如何添加新语言

普通用户：在设置或首次运行向导中选择语言即可，界面即时翻转、偏好自动保存；应用还会通过 src/i18n/detect-system-locale.ts 读取操作系统首选语言，开箱即用本地化引导——但用户的选择永远优先，自动检测不会覆盖你的手动选择。

开发者：新增一种语言的完整路径是：

1. 在SUPPORTED_LOCALES与LOCALE_LABELS中登记新语言（src/i18n/index.ts）
2. 为 RTL 语言确认前缀已列入RTL_LOCALE_PREFIXES，并同步src/app/layout.tsx中的内联引导脚本
3. 在formatters.ts的LOCALE_TO_BCP47中补一个 BCP-47 标签
4. 放置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