localize

构建并维护国际化界面，让每种受支持的语言区域都拥有原生体验，而不只是完成翻译。

本地化不只是替换字符串。它还需要调整布局、格式、内容和交互模式，让每个市场的用户都觉得产品是专为他们打造的，而不是事后才勉强适配。

设计语言选择器、国家选择器、货币选择器或地区偏好控件时，请参阅语言和语言区域选择参考文档。 本地化自定义组件时，如果需要确保其在不同语言区域都支持键盘导航且便于屏幕阅读器使用，请参阅组件无障碍设计参考文档。 本地化验证消息、错误状态和恢复流程时，请参阅错误恢复参考文档。 将日期、时间和日历模式适配到语言区域惯例时，请参阅日期输入 UX和日期时间选择器 UX参考文档。

强制准备

用户通过 /localize 启动此工作流。此技能启用后，加载 $frontend-design——其中包含设计原则、反模式和上下文收集协议。继续之前，请遵循该协议；如果尚无设计上下文，必须先加载 $setup。此外，还需了解：当前及后续计划覆盖哪些市场和语言，产品是内容密集型还是 UI 密集型，以及翻译由内部团队、代理机构还是 TMS 完成。

评估本地化范围

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

1. 内容覆盖范围：

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

2. 格式和惯例：

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

3. 布局和结构适配：

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

4. 内容和法律差异：

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

本地化架构

字符串管理策略

基于键的提取：

• 使用描述性分层键：checkout.shipping.title、errors.email.required
• 避免使用英文句子作为键；源文案变更时，这类键也会失效
• 为译者添加上下文注释：// 用作配送表单上的按钮标签
• 按功能或路由划分命名空间，便于管理文件

消息格式：

• 使用 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；用户再次访问时应尊重该设置
• 绝不以自动检测结果覆盖用户明确选择

库和工具选择

需求	优质选项	适用场景
React / 现代框架	react-i18next、Lingui、FormatJS (react-intl)	使用 hooks/context 在组件级别翻译
Vue	vue-i18n	使用组合式或选项式 API 的 Vue 2/3
Svelte	svelte-i18n、typesafe-i18n	轻量、基于 store 的响应式
原生 JS / 与框架无关	i18next、FormatJS IntlMessageFormat	跨技术栈共享，插件生态丰富
构建时提取	Lingui、typesafe-i18n	减小打包体积，无需运行时解析
运行时提取	i18next、react-i18next	动态加载，由 CMS 驱动内容
翻译管理	Phrase、Lokalise、Crowdin、Smartling	团队协作、TMS 工作流、上下文内编辑

务实规则：

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

实现维度

文本扩展与布局适应性

空间预算：

• 为德语、芬兰语及其他文本扩展较多的语言预留额外 30-40% 的水平空间
• 针对文本较短的语言（中文、日语）进行测试，避免出现过多空白或视觉节奏不协调
• 按钮、标签和导航项应使用最小/最大宽度，而非固定宽度

容器行为：

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

RTL 与双向文本

CSS 逻辑属性：

/* Use logical properties for margins, padding, borders */
margin-inline-start: 1rem;
padding-inline: 1rem;
border-inline-end: 1px solid;

方向感知变换：

[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
• 阿拉伯语有六种复数形式，波兰语有四种，威尔士语有六种
• 使用消息格式处理性别语法和序数（第 1、第 2、第 3），不要通过代码逻辑处理

字符串之外的内容

图像和媒体：

• 尽可能将图像中的文字替换为可选择的文本
• 当视觉内容包含特定文化元素时，维护针对不同地区的图像集
• 图标和图表使用 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 注释
• 法律与合规文案因地区而异，并经过认证
• 已记录翻译工作流，并将其纳入发布节奏
• 在开始实际翻译前，通过伪本地化检查布局和文本截断问题