Back to Details

i18n

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
You make an app ready for any language and region, so adding a language later is translation work, not a refactor. Use the platform's own localisation and formatting APIs as the source of truth — never a custom framework around them.
让应用做好支持任何语言和地区的准备，这样以后添加语言就属于翻译工作，而不是重构。应以平台自身的本地化和格式化 API 为唯一依据——绝不要在其外围构建自定义框架。

1. Pick the Mode

1. 选择模式

Decide from the request; do not ask.
  • Build mode — the task creates or changes UI or formatting code. Apply the rules as constraints while writing it. Mention a rule only when it changed a decision, in one line.
  • Adopt mode — the user asks to internationalise, prepare for translation, or fix i18n across the app. Work through Step 4.
Ship no new languages unless asked. Making strings localisable and adding translations are separate jobs.
根据请求自行判断；不要询问。
  • 构建模式 — 任务需要创建或修改 UI 或格式化代码。编写代码时，将以下规则作为约束条件。只有当某条规则影响了决策时，才用一行提及该规则。
  • 采用模式 — 用户要求对整个应用进行国际化、做好翻译准备或修复 i18n 问题。按照步骤 4 执行。
除非用户明确要求，否则不要交付新语言。将字符串改为可本地化和添加翻译是两件不同的工作。

2. Detect the Platform

2. 检测平台

Read the manifest as prose and load only the matching guide:
PlatformDetected byLoad
Web / JS / TS
package.json
references/js.md
Apple platforms
*.xcodeproj
, 
Package.swift
with an app target
references/apple.md
Android
build.gradle(.kts)
references/android.md
If the project already uses an i18n library (
next-intl
, 
react-i18next
, 
vue-i18n
, 
FormatJS
, …), keep it and follow its conventions; the guide covers what to check, not which library to swap to. React Native/Expo uses 
references/js.md
for strings and formatting. Other stacks: apply the rules using that platform's ICU/CLDR-backed APIs.
阅读项目清单并据此判断，只加载匹配的指南：
平台检测依据加载
Web / JS / TS
package.json
references/js.md
Apple 平台
*.xcodeproj
、包含应用 target 的 
Package.swift
references/apple.md
Android
build.gradle(.kts)
references/android.md
如果项目已经使用某个 i18n 库（
next-intl
、
react-i18next
、
vue-i18n
、
FormatJS
等），则保留该库并遵循其约定；本指南介绍的是需要检查的内容，而不是应该替换成哪个库。React Native/Expo 的字符串和格式化处理使用 
references/js.md
。对于其他技术栈，应使用相应平台基于 ICU/CLDR 的 API 应用这些规则。

3. Rules

3. 规则

RuleImpactApplies toFile
Localisable stringsCRITICALevery user-facing string, plurals, interpolation
rules/localisable-strings.md
Time zones and timestampsCRITICALstored events, history, timelines, schedules
rules/time-zones.md
Locale-aware formattingHIGHdates, times, numbers, percentages, currency, durations
rules/locale-formatting.md
Units and measurementsHIGHdistance, speed, weight, temperature
rules/units.md
Text and layoutHIGHuser-generated text, layout, RTL, long translations
rules/text-and-layout.md
Deterministic testsMEDIUMtests touching dates, numbers, or strings
rules/deterministic-tests.md
规则影响程度适用范围文件
可本地化字符串关键所有面向用户的字符串、复数形式、插值
rules/localisable-strings.md
时区和时间戳关键存储的事件、历史记录、时间线、计划任务
rules/time-zones.md
区域设置感知格式化高日期、时间、数字、百分比、货币、持续时间
rules/locale-formatting.md
单位和测量值高距离、速度、重量、温度
rules/units.md
文本和布局高用户生成内容、布局、RTL、过长翻译
rules/text-and-layout.md
确定性测试中涉及日期、数字或字符串的测试
rules/deterministic-tests.md

4. Adopt Mode

4. 采用模式

  1. Inventory — find hardcoded user-facing strings, hand-rolled date/number formats, string concatenation, fixed units, and 
    left
    /
    right
    layout. Report the counts before editing
  2. Set up the resource — one string catalog or message file in the platform's native format, English (or the project's development language) only
  3. Fix in impact order — CRITICAL first. Change only what international correctness needs; keep the existing design and behaviour
  4. Never change persisted data semantics (timestamp meaning, stored units) without an explicit migration the user has approved — propose it instead
  5. Test — add the deterministic tests from 
    rules/deterministic-tests.md
    ; build and run the suite, and report real results
  6. Validate the UI — pseudolocalisation, the longest text expansion, RTL, and the largest text size, using the tools in the platform guide
End with what changed, what is still hardcoded and why, and any migration you proposed but did not apply.
  1. 盘点 — 找出硬编码的用户可见字符串、手写的日期或数字格式、字符串拼接、固定单位以及 
    left
    /
    right
    布局。编辑前先报告各项数量
  2. 设置资源 — 创建一个采用平台原生格式的字符串目录或消息文件，且只包含英语（或项目的开发语言）
  3. 按影响程度修复 — 先处理关键项。只进行确保国际化正确性所必需的更改；保留现有设计和行为
  4. 绝不改变持久化数据的语义（时间戳含义、存储单位），除非用户明确批准迁移；此时应先提出迁移方案
  5. 测试 — 根据 
    rules/deterministic-tests.md
    添加确定性测试；构建并运行测试套件，并报告实际结果
  6. 验证 UI — 使用平台指南中的工具验证伪本地化、最长文本扩展、RTL 和最大字号
最后说明改了什么、哪些内容仍为硬编码及其原因，以及提出了但未应用的迁移。

Boundaries

边界

  • Accessibility labels must be localisable like any string; what they should say belongs to 
    accessibility
    .
  • User-generated content (names, notes, place names) is never translated, transliterated, or normalised unless the user asks.
  • Translation itself — machine translation, translation services, and translator workflow are out of scope. Do not send app strings or user content to an external service.
  • 辅助功能标签必须像其他字符串一样支持本地化；标签的具体措辞属于 
    accessibility
    的范畴。
  • 用户生成内容（姓名、备注、地点名称）绝不进行翻译、转写或规范化，除非用户提出要求。
  • 翻译本身——机器翻译、翻译服务和译员工作流——不在范围内。不要将应用字符串或用户内容发送到外部服务。