i18n-localization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

i18n Localization

i18n本地化

Use this skill to plan, review, or harden localization work across product UI, documentation, marketing pages, emails, and web/app routing surfaces.

使用此技能来规划、审查或强化产品UI、文档、营销页面、邮件以及网页/应用路由界面的本地化工作。

Canonical Vocabulary

标准术语表

Term	Meaning
locale	Language plus optional regional conventions, such as `en` , `en-US` , or `ar-EG`
message catalog	Source of translated strings and message metadata
ICU message	Message format that models variables, plurals, selects, and ordinals safely
pseudo-locale	Test locale that expands and marks strings to reveal hardcoded text and layout clipping
RTL	Right-to-left layout direction for languages such as Arabic and Hebrew
fallback	Intentional behavior when a locale, key, or translation is missing

术语	含义
locale	语言加上可选的区域约定，例如 `en` 、 `en-US` 或 `ar-EG`
message catalog	翻译字符串和消息元数据的来源
ICU message	可安全处理变量、复数、选择词和序数词的消息格式
pseudo-locale	用于测试的区域设置，会扩展并标记字符串，以暴露硬编码文本和布局截断问题
RTL	适用于阿拉伯语、希伯来语等语言的从右到左布局方向
fallback	当locale、键或翻译缺失时的预设行为

Dispatch

调度规则

`$ARGUMENTS`	Mode	Output
Empty	Localization audit	Inspect the current surface, identify locale risks, and return a prioritized remediation plan.
App, route, feature, or file path	Implementation plan	Map the affected strings, routing, formatting, QA, and release checks for that scope.
Locale or market list	Locale readiness review	Verify language, region, formatting, routing, fallback, and translation handoff requirements.
Existing plan or diff	Review	Check for missed strings, unsafe concatenation, formatting bugs, catalog drift, RTL gaps, and missing tests.
Natural language outside localization	Redirect	Explain the scope boundary and route to the better skill.

When the user gives no arguments, start with a localization audit of the relevant repository or product surface. Do not ask for locale preferences until the codebase and user request leave a real decision unresolved.

`$ARGUMENTS`	模式	输出
空值	本地化审计	检查当前界面，识别locale相关风险，并返回优先级排序的修复计划。
应用、路由、功能或文件路径	实施计划	映射该范围内受影响的字符串、路由、格式化、QA和发布检查项。
区域设置或市场列表	区域设置就绪性审查	验证语言、区域、格式化、路由、回退和翻译交付要求。
现有计划或差异内容	审查	检查是否遗漏字符串、不安全的拼接、格式化错误、目录漂移、RTL缺口以及缺失的测试。
本地化领域外的自然语言	重定向	说明范围边界，并引导至更合适的技能。

当用户未提供参数时，先对相关仓库或产品界面进行本地化审计。在代码库和用户请求未明确要求之前，不要询问区域设置偏好。

Reference File Index

参考文件索引

File	Read When
`references/localization-checklist.md`	Planning, implementing, reviewing, testing, or releasing localization work

文件	读取时机
`references/localization-checklist.md`	规划、实施、审查、测试或发布本地化工作时

Critical Rules

核心规则

Treat localization as a product contract, not a translation pass. Cover routing, formatting, accessibility, search metadata, analytics labels, emails, and support surfaces when they are in scope.
Never concatenate translated fragments to build a sentence. Use full messages with variables, ICU/select/plural forms, or the framework's equivalent message format.
Keep user-visible strings out of business logic and shared constants unless the system already has a catalog abstraction for that layer.
Use locale-aware formatters for dates, times, numbers, currencies, lists, relative times, units, and names. Do not hand-roll formatting with string templates.
Separate language from region.
```
en
```
,
```
en-US
```
, and
```
en-GB
```
can imply different copy, dates, currency, measurement units, and legal content.
Define fallback behavior explicitly. Missing translations should fail visibly in development and degrade intentionally in production.
Include pseudo-locale checks for expansion, accenting, bracket markers, interpolation safety, and truncation.
Include RTL and bidirectional text checks when any Arabic, Hebrew, Persian, Urdu, or mixed-direction user content can appear.
Preserve stable message keys. Do not churn catalogs or invalidate translation memory unless the source message meaning changes.
Keep translators away from code syntax. Provide notes, screenshots, variable descriptions, character constraints, and product context.

将本地化视为产品契约，而非单纯的翻译流程。当涉及相关范围时，需覆盖路由、格式化、可访问性、搜索元数据、分析标签、邮件和支持界面。
切勿拼接翻译片段来构建句子。使用包含变量、ICU/选择/复数形式或框架等效消息格式的完整消息。
将用户可见的字符串从业务逻辑和共享常量中分离出来，除非系统已为该层提供了目录抽象。
使用支持locale的格式化工具处理日期、时间、数字、货币、列表、相对时间、单位和名称。不要使用字符串模板手动实现格式化。
区分语言和区域。
```
en
```
、
```
en-US
```
和
```
en-GB
```
可能对应不同的文案、日期、货币、度量单位和法律内容。
明确定义回退行为。缺失的翻译在开发环境中应明显报错，在生产环境中应按预设逻辑降级显示。
针对扩展、重音、括号标记、插值安全性和截断问题进行伪区域设置检查。
当可能出现阿拉伯语、希伯来语、波斯语、乌尔都语或混合方向的用户内容时，需包含RTL和双向文本检查。
保持稳定的消息键。除非源消息含义发生变化，否则不要频繁修改目录或使翻译记忆失效。
让译者远离代码语法。提供注释、截图、变量说明、字符限制和产品上下文。

Workflow

工作流程

1. Scope The Surface

1. 界定界面范围

Identify the surfaces affected by the request:

UI components, server-rendered pages, native screens, emails, PDFs, docs, notifications, error states, empty states, and transactional copy.
Route structure, locale negotiation, redirects, canonical URLs, hreflang, sitemap entries, and persisted user locale preferences.
Data-driven content, CMS fields, markdown/docs content, legal text, pricing, units, and market-specific availability.

If the request is implementation work, read the existing i18n library, routing conventions, catalog format, and test patterns before proposing changes.

识别请求影响的界面：

UI组件、服务端渲染页面、原生屏幕、邮件、PDF、文档、通知、错误状态、空状态和事务性文案。
路由结构、区域设置协商、重定向、规范URL、hreflang、站点地图条目和持久化的用户区域设置偏好。
数据驱动内容、CMS字段、Markdown/文档内容、法律文本、定价、单位和特定市场的可用性。

如果请求是实施工作，在提出变更前需先了解现有的i18n库、路由约定、目录格式和测试模式。

2. Extract And Model Messages

2. 提取并建模消息

For each string-bearing surface:

Move user-visible strings into the existing catalog or message layer.
Use full-sentence messages with named variables.
Model plural, select, gender, ordinal, and count-sensitive text with ICU-style variants or the framework's native equivalent.
Add translator descriptions for ambiguous labels, product terms, placeholders, and variables.
Keep stable keys tied to semantic meaning, not English wording alone.

Avoid generic keys such as

title

subtitle

, or

buttonText

unless they are nested under a stable feature namespace.

针对每个包含字符串的界面：

将用户可见的字符串移至现有目录或消息层。
使用包含命名变量的完整句子消息。
使用ICU风格变体或框架原生等效格式来建模复数、选择、性别、序数和数量敏感文本。
为模糊标签、产品术语、占位符和变量添加译者说明。
保持与语义含义绑定的稳定键，而非仅依赖英文表述。

避免使用

title

、

subtitle

或

buttonText

等通用键，除非它们嵌套在稳定的功能命名空间下。

3. Localize Formatting

3. 本地化格式化

Check all locale-sensitive values:

Date, time, timezone, relative time, and calendar assumptions.
Number, decimal, percent, currency, accounting, compact notation, and unit formatting.
Lists, names, addresses, phone numbers, postal codes, sorting, casing, and search normalization.
Form validation, parsing, masks, and server/client round-trip behavior.

Prefer platform formatters such as

Intl.*

, framework helpers, or vetted library APIs.

检查所有对locale敏感的值：

日期、时间、时区、相对时间和日历假设。
数字、小数、百分比、货币、会计格式、紧凑表示法和单位格式化。
列表、姓名、地址、电话号码、邮政编码、排序、大小写和搜索规范化。
表单验证、解析、掩码和服务端/客户端往返行为。

优先使用平台格式化工具，如

Intl.*

、框架助手或经过验证的库API。

4. Route And Persist Locale

4. 路由并持久化区域设置

Verify:

How the app chooses a locale: URL prefix, domain, account setting, cookie, browser language, or explicit selector.
Whether redirects are deterministic and cache-safe.
Whether canonical URLs, alternate links, metadata, Open Graph, sitemap, robots rules, and docs navigation match the locale strategy.
Whether APIs, background jobs, and emails receive the same locale context as the visible app.

Do not mix locale negotiation and authentication or billing policy unless the product already couples those concepts.

验证：

应用选择locale的方式：URL前缀、域名、账户设置、Cookie、浏览器语言或显式选择器。
重定向是否具有确定性且缓存安全。
规范URL、替代链接、元数据、Open Graph、站点地图、机器人规则和文档导航是否与区域设置策略匹配。
API、后台任务和邮件是否接收与可见应用相同的locale上下文。

不要混合区域设置协商与认证或计费策略，除非产品已将这些概念耦合。

5. Test And QA

5. 测试与QA

At minimum, recommend or add checks for:

Catalog completeness and unused key detection.
Missing interpolation variables.
Pseudo-locale rendering.
Snapshot or visual coverage for expanded strings and RTL layout where relevant.
Formatting tests for representative locales, including at least one non-US locale.
Accessibility checks for language attributes, direction, screen reader labels, and translated aria text.

For review tasks, report what the available tests prove and what still requires visual or translator QA.

至少建议或添加以下检查项：

目录完整性和未使用键检测。
缺失的插值变量。
伪区域设置渲染。
针对扩展字符串和相关RTL布局的快照或视觉覆盖测试。
针对代表性区域设置的格式化测试，至少包含一个非美国区域设置。
针对语言属性、方向、屏幕阅读器标签和翻译后的aria文本的可访问性检查。

对于审查任务，报告现有测试已验证的内容以及仍需视觉或译者QA的部分。

Progressive Disclosure

渐进式披露

Start with this
```
SKILL.md
```
for routing, hard rules, and output shape.
Read
```
references/localization-checklist.md
```
only when planning, reviewing, or releasing concrete localization work.
Do not preload unrelated frontend, SEO, copywriting, or JavaScript guidance.
Use the existing project i18n library and catalog format before introducing new tooling.

从本
```
SKILL.md
```
开始，了解路由、核心规则和输出格式。
仅在规划、审查或发布具体本地化工作时才阅读
```
references/localization-checklist.md
```
。
不要预先加载无关的前端、SEO、文案或JavaScript指导内容。
在引入新工具之前，优先使用项目现有的i18n库和目录格式。

Output Shape

输出格式

Return concise, implementation-oriented output:

Findings for audits and reviews, ordered by severity with file or route references.
Plan for implementation requests, ordered by dependency: routing/catalog foundation, extraction, formatting, QA, release.
Acceptance Criteria that include catalog completeness, pseudo-locale, formatting, fallback, and route/SEO checks when relevant.
Open Questions only for unresolved choices that cannot be grounded in the codebase or user request.

Do not rewrite marketing copy unless the user explicitly asks for copy editing. Do not perform general frontend redesign unless localization exposes a concrete layout or directionality defect.

返回简洁、面向实施的输出：

审计与审查结果：按严重性排序，并附带文件或路由引用。
实施计划：按依赖关系排序：路由/目录基础、提取、格式化、QA、发布。
验收标准：相关时需包含目录完整性、伪区域设置、格式化、回退以及路由/SEO检查。
待解决问题：仅针对无法基于代码库或用户请求确定的未解决选项。

除非用户明确要求文案编辑，否则不要重写营销文案。除非本地化暴露了具体的布局或方向性缺陷，否则不要进行一般性前端重新设计。

Validation Contract

验证契约

Run from this skill directory before declaring changes complete:

bash

python scripts/check.py

Completion criteria:

```
scripts/check.py
```
exits 0.
No portable-CLI violations remain under this skill directory.
A smoke review of the dispatch table covers empty, explicit, implicit, and negative-control prompts.

在声明变更完成前，从本技能目录运行以下命令：

bash

python scripts/check.py

完成标准：

```
scripts/check.py
```
执行后返回0。
本技能目录下无portable-CLI违规项。
对调度表进行快速审查，覆盖空值、显式、隐式和负控制提示。