localize

构建并维护国际化界面，让每种受支持的语言区域都能获得原生体验，而不只是翻译了文字。

本地化不只是替换字符串。还要调整布局、格式、内容和交互模式，让每个市场的用户都觉得产品是专为他们设计的，而不是事后才考虑到他们。

设计语言选择器、国家选择器、货币选择器或地区偏好控件时，请参阅语言和语言区域选择参考文档。 本地化自定义组件时，请参阅组件无障碍参考文档，确保组件在不同语言区域中仍可通过键盘操作，并兼容屏幕阅读器。 本地化验证消息、错误状态和恢复流程时，请参阅错误恢复参考文档。 调整日期、时间和日历模式以适应语言区域惯例时，请参阅日期输入 UX和日期时间选择器 UX参考文档。

必须完成的准备工作

阅读 frontend-design，并遵循其中的上下文收集协议。复用已有上下文，只针对影响重大的信息缺口提问。此外，还需了解：当前和下一阶段的目标市场与语言、产品是内容密集型还是 UI 密集型，以及翻译将由内部团队、代理机构还是 TMS 完成。

评估本地化范围

了解需要更改的内容以及适配的深度：

1. 内容范围：

   • 静态 UI 字符串（标签、按钮、标题、空状态）
   • 动态用户生成内容（姓名、描述、评论）
   • 营销和法律文案（条款、隐私、合规）
   • 错误消息和验证反馈
   • 通知、电子邮件及产品外消息

2. 格式和惯例：

   • 日期、时间和日历格式（ISO 格式与本地化显示）
   • 数字格式（小数分隔符、分组符号、货币）
   • 计量单位（公制与英制、货币符号）
   • 地址和电话号码格式
   • 姓名顺序（名在前还是姓在前）
   • 排序和排序规则

3. 布局和结构适配：

   • 文本扩展和收缩（德语 +30%，日语 -10%）
   • 从右向左（RTL）文字的要求
   • 竖排文字或混合文字布局
   • 阅读方向和浏览模式

4. 内容和法律差异：

   • 特定地区的功能或目录可用性
   • 法律要求（GDPR、CCPA、当地税务、年龄限制）
   • 支付方式和货币支持
   • 文化相关的图像、颜色和象征意义

本地化架构

字符串管理策略

基于键的提取：

• 使用描述性、分层的键：checkout.shipping.title、errors.email.required
• 避免使用英文句子作为键；源文案变更时，这类键也会失效
• 添加供译者参考的上下文注释：// Used as button label on shipping form
• 按功能或路由划分命名空间，方便管理文件

消息格式：

• 使用 ICU MessageFormat 处理插值、复数和性别
• 避免在代码中拼接字符串；译者需要看到完整句子

// Good: complete sentence with interpolation
{count, plural, =0 {No items} one {# item} other {# items}} in your cart

// Bad: concatenated fragments
t('items_prefix') + count + t('items_suffix')

源语言规范：

• 将源语言（通常是英语）视为开发约定
• 编写适合翻译的源字符串：使用完整句子，明确代词指代，不使用习语
• 将源文案交给译者之前，先检查其是否易于翻译

区域设置协商与路由

URL 策略（选择一种并坚持使用）：

• 子目录：/en/products、/de/products——对 SEO 友好、便于分享、清晰明了
• 子域名：en.example.com、de.example.com——划分清晰，但维护难度较高
• 查询参数：?lang=de——实现最简单，但对 SEO 和分享最不友好

区域设置检测顺序：

1. 用户明确设置的偏好（存储在账户或 Cookie 中）
2. URL 路径或子域名
3. 浏览器的 Accept-Language 标头
4. 地理位置（仅用作宽松的默认值，绝不强制重定向）

区域设置持久化：

• 已验证身份的用户，需将明确选择存储在用户资料中
• 匿名访客使用 Cookie；用户再次访问时应遵循 Cookie 中的设置
• 绝不要用自动检测结果覆盖用户明确选择的设置

库与工具选择

需求	优选方案	适用场景
React 框架	react-i18next、Lingui、FormatJS (react-intl)	通过 hooks/context 实现组件级翻译
Next.js	next-intl、next-international、Lingui、FormatJS	感知 App Router 的区域设置路由，以及服务端/客户端边界处理
带 React 岛屿的 Astro	Astro i18n 路由，以及岛屿中的 React i18n	静态内容保留 Astro 原生形式，交互式岛屿中的文案兼容 React
构建时提取	Lingui	包体积更小，无需运行时解析
运行时提取	i18next、react-i18next	动态加载、由 CMS 驱动的内容
翻译管理	Phrase、Lokalise、Crowdin、Smartling	团队协作、TMS 工作流、上下文内编辑

务实原则：

• 每个项目优先使用一个 i18n 库。使用多个库会导致键名约定和加载行为碎片化。
• 如果项目规模较小且内容静态，使用 JSON/PO 文件进行构建时提取即可满足需求。
• 如果翻译经常变更，或由非开发人员编辑，应尽早集成 TMS。

实现要点

文本扩展与布局适应性

空间预留：

• 为德语、芬兰语等扩展较多的语言预留额外 30-40% 的水平空间
• 使用最短的语言（中文、日语）进行测试，检查是否存在过多留白或视觉节奏失衡
• 按钮、标签和导航项使用最小/最大宽度，不要设置固定宽度

容器行为：

• 优先使用能适应内容长度的 flexbox 和 grid
• 允许文本换行；不要强制标签保持单行布局
• 测试扩展后的内容超出可用空间时的截断行为

RTL 与双向文本

Tailwind 逻辑间距和边框工具类：

• 条件允许时，优先使用逻辑工具类和感知方向的变体
• 仅当项目需要的逻辑属性尚未被现有工具类覆盖时，才使用 Tailwind 任意属性

感知方向的变换：

[dir="rtl"] .arrow { transform: scaleX(-1); }
[dir="rtl"] .timeline { flex-direction: row-reverse; }

镜像处理注意事项：

• 对导航、面包屑和返回按钮进行镜像
• 不要镜像表示实体物品的图标（时钟、文本光标）
• 应镜像方向性图标（箭头、尖括号、进度指示器）
• 使用母语为 RTL 语言的人员进行测试；机械镜像往往会忽略文化习惯

格式与数据展示

日期和时间：

• 使用 Intl.DateTimeFormat 或等效库；绝不要硬编码格式字符串
• 遵循各区域设置的 12 小时制或 24 小时制惯例
• 在相关场景下，考虑不同历法系统（公历、佛教历、伊斯兰历）

数字与货币：

• 使用 Intl.NumberFormat 处理分组、十进制和货币符号
• 根据区域设置，货币符号可能位于金额前缀或后缀（$1,234.56 与 1.234,56 €）
• 在多币种场景中，为清晰起见，应同时显示货币代码（USD、EUR）和符号

复数、序数与语法：

• 使用 ICU MessageFormat 的复数规则；不要假设只有英文的 one/other
• 阿拉伯语有六种复数形式；波兰语有四种；威尔士语有六种
• 通过消息格式处理性别语法和序数（1st、2nd、3rd），不要在代码逻辑中处理

字符串之外的内容

图像和媒体：

• 尽可能将图像中的文字替换为可选择的文本
• 当视觉内容包含特定文化元素时，维护针对不同地区的图像集
• 图标和图表使用 SVG；它们更容易缩放和镜像

URL 和 SEO：

• 使用 hreflang 注释标明语言／地区变体
• 在规范 URL 中包含地区信息
• 本地化 meta 标题和描述，而不只是页面内容
• 避免在 URL 路径中使用不适合当地语言环境的关键词

法律与合规内容：

• 维护针对不同地区的法律文本（条款、隐私政策、Cookie 通知）
• 不要自动翻译法律文本；应使用经过认证的法律译者
• 按司法管辖区对合规内容进行版本管理

翻译工作流

开发者交接：

1. 将代码中的字符串提取到翻译文件（JSON、PO、YAML）中
2. 添加上下文注释和截图引用，以说明含义不明确的字符串
3. 在提交翻译前冻结源字符串，避免翻译过程中发生变更
4. 随代码版本发布一同管理翻译文件版本

质量保证：

• 检查译文是否存在截断、溢出和布局错乱
• 确认占位符和 HTML 标签均得到保留
• 检查带有性别标记的译文是否符合预期语境
• 在正式翻译前运行伪本地化（扩展字符），及早发现布局问题

持续本地化：

• 将 TMS 与版本控制集成（GitHub/GitLab Webhook）
• 在拉取请求时自动执行提取
• 设置翻译记忆库，以降低成本并提高一致性
• 及时通知译者新增或变更的键

测试本地化 UI

布局测试：

• 使用支持语言中长度最长和最短的语言进行测试
• 通过浏览器原生的方向切换功能验证 RTL 布局
• 在最小和最大视口宽度下检查截断、换行和溢出

功能测试：

• 验证插值变量在所有语言区域中都能正确填充
• 确认复数规则正确呈现（0、1、2、5、11、21 项）
• 在适用情况下，测试切换语言区域时是否无需完整重新加载页面
• 验证退出并重新登录后，已保存的语言区域偏好仍然有效

内容测试：

• 抽查译文，确认准确性和语气一致性
• 确认法律和合规文本与认证版本一致
• 确保存在本地化 URL 和 SEO 元数据

反模式

• 拼接翻译片段：译者需要完整句子。t('you_have') + count + t('messages') 在大多数语言中都会出问题。
• 硬编码语言区域假设：不要假设文本从左向右排列、采用 12 小时制、使用 MM/DD/YYYY 日期格式，或遵循英语复数规则。
• 未经审核就自动翻译 UI：用于 UI 字符串的机器翻译会导致术语不一致和语法错误。
• 忽视文本扩展：固定宽度的按钮和标签在德语等文本容易扩展的语言中会出问题。
• 使用旗帜代表语言：旗帜代表国家，而非语言。西班牙语对应 20 多个国家；英语对应数十个国家。应使用语言名称或中性图标。
• 仅根据 IP 重定向：旅行者、VPN 用户和外籍人士可能会被困在错误的语言区域。应提供建议，而非强制切换。
• 跳过伪本地化：在正式翻译前运行伪语言区域测试，能在布局和截断问题仍易于修复时将其发现。
• 在版本控制中存储翻译，却不进行版本管理：翻译文件应与代码一同打标签和发布，以便回滚。
• 忘记本地化错误消息：未翻译的验证错误经常会导致用户困惑并放弃操作。
• 将本地化视为一次性项目：语言不断演变，产品不断增加功能，市场也会发生变化。本地化需要持续维护。

验证本地化就绪情况

发布本地化产品前：

• 已提取所有面向用户的字符串并为其分配键，而非硬编码
• 已审核源文案，确保其便于翻译（使用完整句子，不含习语）
• 已使用最长和最短的目标语言测试布局
• 已通过逻辑属性和方向性测试支持 RTL 脚本
• 日期、数字和货币格式均使用支持区域设置的 API
• 复数形式处理正确涵盖所有目标语言的复数规则
• 切换区域设置时保留用户上下文和状态
• URL 包含区域设置，并使用 hreflang 注释
• 法律与合规文案因地区而异，并经过认证
• 已记录翻译工作流，并将其纳入发布节奏
• 在开始实际翻译前，通过伪本地化检查布局和文本截断问题