localization-i18n

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

当激活此技能时，你的第一条回复请以🧢表情开头。

Localization & Internationalization (i18n)

本地化与国际化（i18n）

Internationalization (i18n) is the process of designing software so it can be adapted to different languages and regions without engineering changes. Localization (l10n) is the actual adaptation - translating strings, formatting dates and currencies, supporting right-to-left scripts, and handling pluralization rules that vary wildly across languages. This skill gives an agent the knowledge to set up i18n infrastructure, write correct ICU MessageFormat patterns, handle RTL layouts, manage translation workflows, and avoid the common traps that cause garbled UIs in non-English locales.

国际化（i18n）是指在无需修改工程代码的前提下，设计可适配不同语言和地区的软件的过程。本地化（l10n）则是实际的适配操作——翻译字符串、格式化日期和货币、支持从右到左的文字排版，以及处理不同语言间差异极大的复数规则。此技能可为Agent提供搭建i18n基础设施、编写正确的ICU MessageFormat模板、处理RTL布局、管理翻译工作流的知识，并帮助避免导致非英语地区界面显示混乱的常见陷阱。

When to use this skill

何时使用此技能

Trigger this skill when the user:

Wants to add i18n/l10n support to a web or mobile application
Needs to write or debug ICU MessageFormat strings (plural, select, selectordinal)
Asks about handling right-to-left (RTL) languages like Arabic or Hebrew
Wants to set up a translation workflow or integrate a TMS (translation management system)
Needs to format dates, numbers, or currencies for specific locales
Asks about pluralization rules for different languages
Wants to configure i18n libraries like react-intl, i18next, FormatJS, or vue-i18n
Needs to extract translatable strings from source code

Do NOT trigger this skill for:

General string manipulation unrelated to translations
Timezone handling without a localization context (use a datetime skill instead)

当用户有以下需求时，触发此技能：

想要为网页或移动应用添加i18n/l10n支持
需要编写或调试ICU MessageFormat字符串（plural、select、selectordinal）
询问如何处理阿拉伯语、希伯来语等从右到左（RTL）的语言
想要搭建翻译工作流或集成TMS（翻译管理系统）
需要为特定地区格式化日期、数字或货币
询问不同语言的复数规则
想要配置react-intl、i18next、FormatJS或vue-i18n等i18n库
需要从源代码中提取可翻译字符串

请勿在以下场景触发此技能：

与翻译无关的通用字符串处理
无本地化上下文的时区处理（请使用日期时间相关技能）

Key principles

核心原则

Never concatenate translated strings - String concatenation breaks in languages with different word order. Use ICU MessageFormat placeholders instead:
```
"Hello, {name}"
```
not
```
"Hello, " + name
```
. This is the single most common i18n bug.
Externalize all user-facing strings from day one - Retrofitting i18n is 10x harder than building it in. Every user-visible string belongs in a message catalog, never hardcoded in source. Even if you only ship English today.
Design for text expansion - German text is 30-35% longer than English. Japanese can be shorter. UI layouts must accommodate expansion without clipping or overflow. Use flexible containers, never fixed widths on text elements.
Locale is not language -
```
en-US
```
and
```
en-GB
```
are the same language but format dates, currencies, and numbers differently. Always use full BCP 47 locale tags (language-region), not just language codes.
Pluralization is not just singular/plural - English has 2 plural forms. Arabic has 6. Polish has 4. Russian has 3. Always use CLDR plural rules through ICU MessageFormat rather than
```
count === 1 ? "item" : "items"
```
conditionals.

永远不要拼接翻译后的字符串 - 字符串拼接在语序不同的语言中会失效。请使用ICU MessageFormat占位符替代：例如使用
```
"Hello, {name}"
```
而非
```
"Hello, " + name
```
。这是最常见的i18n错误。
从项目初期就抽离所有面向用户的字符串 - 后期再添加i18n支持的难度是初期集成的10倍。所有用户可见的字符串都应放在消息目录中，绝不要硬编码在源代码里。即使当前仅发布英文版本也应如此。
为文本长度变化预留空间 - 德语文本比英文长30-35%，日语文本则更短。UI布局必须能容纳文本长度变化，避免内容被截断或溢出。请使用弹性容器，绝不要为文本元素设置固定宽度。
地区不等于语言 -
```
en-US
```
和
```
en-GB
```
是同一种语言，但日期、货币和数字的格式不同。请始终使用完整的BCP 47地区标签（语言-地区），而非仅使用语言代码。
复数规则不只是单复数之分 - 英语有2种复数形式，阿拉伯语有6种，波兰语有4种，俄语有3种。请通过ICU MessageFormat使用CLDR复数规则，而非
```
count === 1 ? "item" : "items"
```
这类条件判断。

Core concepts

核心概念

ICU MessageFormat is the industry standard for parameterized, translatable strings. It handles interpolation, pluralization, gender selection, and number/date formatting in a single syntax. The key constructs are

{variable}

for simple interpolation,

{count, plural, ...}

for plurals,

{gender, select, ...}

for gender/category selection, and

{count, selectordinal, ...}

for ordinal numbers ("1st", "2nd", "3rd"). See

references/icu-message-format.md

for the full syntax guide.

CLDR Plural Rules define how languages categorize numbers into plural forms. The Unicode CLDR defines six categories:

zero

one

two

few

many

other

. English uses only

one

and

other

. Arabic uses all six. Every plural ICU message must include the

other

category as a fallback. See

references/pluralization.md

RTL (Right-to-Left) layout affects Arabic, Hebrew, Persian, and Urdu scripts. RTL is not just mirroring text - it requires flipping the entire layout direction, swapping padding/margins, mirroring icons with directional meaning, and using CSS logical properties (

inline-start

inline-end

instead of

left

right

). See

references/rtl-layout.md

Translation workflows connect developers to translators. The typical pipeline is: extract strings from source code into message catalogs (JSON/XLIFF/PO files), send catalogs to translators (via TMS or manual handoff), receive translations, compile them into the app's locale bundles, and validate completeness. Missing translations should fall back to the default locale, never show raw message keys.

ICU MessageFormat是参数化可翻译字符串的行业标准。它能在单一语法中处理插值、复数、性别选择以及数字/日期格式化。核心结构包括：用于简单插值的

{variable}

、用于复数的

{count, plural, ...}

、用于性别/类别选择的

{gender, select, ...}

，以及用于序数词（"1st"、"2nd"、"3rd"）的

{count, selectordinal, ...}

。完整语法指南请参考

references/icu-message-format.md

。

CLDR复数规则定义了不同语言对数字的复数分类方式。Unicode CLDR定义了六个类别：

zero

、

one

、

two

、

few

、

many

、

other

。英语仅使用

one

和

other

，阿拉伯语则使用全部六个类别。所有ICU复数消息必须包含

other

类别作为回退。详情请参考

references/pluralization.md

。

RTL（从右到左）布局适用于阿拉伯语、希伯来语、波斯语和乌尔都语等文字。RTL不只是镜像文本——它需要翻转整个布局方向、交换内边距/外边距、镜像具有方向含义的图标，并使用CSS逻辑属性（

inline-start

inline-end

替代

left

right

）。详情请参考

references/rtl-layout.md

。

翻译工作流连接开发者与翻译人员。典型流程为：从源代码中提取字符串到消息目录（JSON/XLIFF/PO文件），将目录发送给翻译人员（通过TMS或手动交接），接收翻译内容，将其编译到应用的地区包中，并验证完整性。缺失的翻译应回退到默认地区，绝不要显示原始消息键。

Common tasks

常见任务

Set up react-intl (FormatJS) in a React app

在React应用中搭建react-intl（FormatJS）

Install the library and wrap the app with

IntlProvider

bash

npm install react-intl

jsx

import { IntlProvider, FormattedMessage } from 'react-intl';

const messages = {
  en: { greeting: 'Hello, {name}!' },
  fr: { greeting: 'Bonjour, {name} !' },
};

function App({ locale }) {
  return (
    <IntlProvider locale={locale} messages={messages[locale]}>
      <FormattedMessage id="greeting" values={{ name: 'World' }} />
    </IntlProvider>
  );
}

Always load only the messages for the active locale to minimize bundle size.

安装库并使用

IntlProvider

包裹应用。

bash

npm install react-intl

jsx

import { IntlProvider, FormattedMessage } from 'react-intl';

const messages = {
  en: { greeting: 'Hello, {name}!' },
  fr: { greeting: 'Bonjour, {name} !' },
};

function App({ locale }) {
  return (
    <IntlProvider locale={locale} messages={messages[locale]}>
      <FormattedMessage id="greeting" values={{ name: 'World' }} />
    </IntlProvider>
  );
}

请始终仅加载当前活跃地区的消息，以最小化包体积。

Set up i18next in a Node.js or React app

在Node.js或React应用中搭建i18next

bash

npm install i18next react-i18next i18next-browser-languagedetector

javascript

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources: {
      en: { translation: { welcome: 'Welcome, {{name}}!' } },
      ja: { translation: { welcome: 'ようこそ、{{name}}さん！' } },
    },
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

i18next uses
{{double braces}}
for interpolation by default, not ICU
{single braces}
. Enable ICU MessageFormat with the
i18next-icu
plugin if you want standard ICU syntax.

bash

npm install i18next react-i18next i18next-browser-languagedetector

javascript

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources: {
      en: { translation: { welcome: 'Welcome, {{name}}!' } },
      ja: { translation: { welcome: 'ようこそ、{{name}}さん！' } },
    },
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

i18next默认使用
{{双大括号}}
进行插值，而非ICU的
{单大括号}
。如果需要标准ICU语法，请启用
i18next-icu
插件。

Write ICU plural messages

编写ICU复数消息

You have {count, plural,
  =0 {no messages}
  one {# message}
  other {# messages}
}.

The

symbol is replaced with the formatted number. Always include

other

as the fallback category. For languages with more plural forms (Arabic, Polish, Russian), translators add the additional categories (

zero

two

few

many

See

references/icu-message-format.md

for select, selectordinal, and nested patterns.

You have {count, plural,
  =0 {no messages}
  one {# message}
  other {# messages}
}.

符号会被替换为格式化后的数字。请始终包含

other

作为回退类别。对于复数形式更多的语言（阿拉伯语、波兰语、俄语），翻译人员可添加额外的类别（

zero

、

two

、

few

、

many

）。

select、selectordinal和嵌套模板的详情请参考

references/icu-message-format.md

。

Write ICU select messages (gender/category)

编写ICU select消息（性别/类别）

{gender, select,
  male {He liked your post}
  female {She liked your post}
  other {They liked your post}
}

The

other

branch is required and acts as the default. Select works for any categorical variable, not just gender.

{gender, select,
  male {He liked your post}
  female {She liked your post}
  other {They liked your post}
}

other

分支是必填项，作为默认选项。select适用于任何分类变量，不只是性别。

Format dates, numbers, and currencies per locale

按地区格式化日期、数字和货币

javascript

// Numbers
new Intl.NumberFormat('de-DE').format(1234567.89);
// -> "1.234.567,89"

// Currency
new Intl.NumberFormat('ja-JP', {
  style: 'currency',
  currency: 'JPY',
}).format(5000);
// -> "￥5,000"

// Dates
new Intl.DateTimeFormat('fr-FR', {
  dateStyle: 'long',
}).format(new Date('2025-03-14'));
// -> "14 mars 2025"

Always use
Intl.NumberFormat
and
Intl.DateTimeFormat
(or library equivalents). Never manually format numbers with string operations - decimal separators, grouping separators, and currency symbol positions vary by locale.

javascript

// 数字
new Intl.NumberFormat('de-DE').format(1234567.89);
// -> "1.234.567,89"

// 货币
new Intl.NumberFormat('ja-JP', {
  style: 'currency',
  currency: 'JPY',
}).format(5000);
// -> "￥5,000"

// 日期
new Intl.DateTimeFormat('fr-FR', {
  dateStyle: 'long',
}).format(new Date('2025-03-14'));
// -> "14 mars 2025"

请始终使用
Intl.NumberFormat
和
Intl.DateTimeFormat
（或对应库的等效方法）。绝不要通过字符串操作手动格式化数字——小数分隔符、千位分隔符和货币符号的位置因地区而异。

Configure RTL layout with CSS logical properties

使用CSS逻辑属性配置RTL布局

css

/* Instead of physical directions: */
.card {
  margin-left: 16px;    /* DON'T */
  padding-right: 8px;   /* DON'T */
  text-align: left;     /* DON'T */
}

/* Use logical properties: */
.card {
  margin-inline-start: 16px;   /* DO */
  padding-inline-end: 8px;     /* DO */
  text-align: start;           /* DO */
}

Set the document direction with

<html dir="rtl" lang="ar">

. For bidirectional content, use the

dir="auto"

attribute on user-generated content containers.

See

references/rtl-layout.md

for the full migration guide.

css

/* 避免使用物理方向： */
.card {
  margin-left: 16px;    /* 不要这么做 */
  padding-right: 8px;   /* 不要这么做 */
  text-align: left;     /* 不要这么做 */
}

/* 请使用逻辑属性： */
.card {
  margin-inline-start: 16px;   /* 推荐做法 */
  padding-inline-end: 8px;     /* 推荐做法 */
  text-align: start;           /* 推荐做法 */
}

通过

<html dir="rtl" lang="ar">

设置文档方向。对于双向内容，请在用户生成内容的容器上使用

dir="auto"

属性。

完整迁移指南请参考

references/rtl-layout.md

。

Extract translatable strings from source code

从源代码中提取可翻译字符串

For react-intl / FormatJS projects:

bash

npx formatjs extract 'src/**/*.{ts,tsx}' --out-file lang/en.json --id-interpolation-pattern '[sha512:contenthash:base64:6]'

For i18next projects, use

i18next-parser

bash

npx i18next-parser 'src/**/*.{js,jsx,ts,tsx}'

Run extraction in CI to catch untranslated strings before they reach production.

对于react-intl / FormatJS项目：

bash

npx formatjs extract 'src/**/*.{ts,tsx}' --out-file lang/en.json --id-interpolation-pattern '[sha512:contenthash:base64:6]'

对于i18next项目，请使用

i18next-parser

：

bash

npx i18next-parser 'src/**/*.{js,jsx,ts,tsx}'

在CI流程中运行提取操作，在未翻译的字符串进入生产环境前及时发现。

Handle missing translations with fallback chains

通过回退链处理缺失的翻译

javascript

// i18next fallback chain
i18n.init({
  fallbackLng: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant': ['zh-Hans', 'en'],
    default: ['en'],
  },
});

The fallback order should go: specific locale -> language family -> default language. Never show raw message keys (

app.greeting.title

) to users - always ensure the fallback chain terminates at a fully-translated locale.

javascript

// i18next回退链
i18n.init({
  fallbackLng: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant': ['zh-Hans', 'en'],
    default: ['en'],
  },
});

回退顺序应为：特定地区 -> 语系 -> 默认语言。绝不要向用户显示原始消息键（如

app.greeting.title

）——请确保回退链最终指向完全翻译的地区。

Anti-patterns / common mistakes

反模式/常见错误

Mistake	Why it's wrong	What to do instead
String concatenation for translations	Word order differs across languages; `"Welcome to " + city` fails in Japanese	Use ICU placeholders: `"Welcome to {city}"`
Hardcoded plural logic ( `n === 1` )	Only works for English; breaks for Arabic (6 forms), Polish (4 forms), Russian (3 forms)	Use ICU `{count, plural, ...}` with CLDR rules
Using `left` / `right` CSS properties	Breaks RTL layouts for Arabic, Hebrew, Persian	Use CSS logical properties: `inline-start` / `inline-end`
Translating string fragments	`"Click " + <Link>here</Link> + " to continue"` is untranslatable as a whole	Use rich text formatting: `"Click <link>here</link> to continue"` with component interpolation
Embedding numbers in strings	`"Page 1 of 5"` via concatenation skips locale-aware number formatting	Use `"Page {current} of {total}"` with `Intl.NumberFormat`
Storing translations in code	Translations scattered across components make extraction and updates impossible	Centralize in JSON/XLIFF message catalogs, one file per locale
Assuming text length is constant	German is ~35% longer than English; UI clips or overflows	Design flexible layouts, test with pseudolocalization

错误做法	问题所在	正确做法
拼接翻译后的字符串	不同语言语序不同； `"Welcome to " + city` 在日语中会失效	使用ICU占位符： `"Welcome to {city}"`
硬编码复数逻辑（ `n === 1` ）	仅适用于英语；在阿拉伯语（6种复数形式）、波兰语（4种）、俄语（3种）中会失效	使用带有CLDR规则的ICU `{count, plural, ...}`
使用 `left` / `right` CSS属性	在阿拉伯语、希伯来语、波斯语等RTL布局中会失效	使用CSS逻辑属性： `inline-start` / `inline-end`
翻译字符串片段	`"Click " + <Link>here</Link> + " to continue"` 无法作为整体翻译	使用富文本格式： `"Click <link>here</link> to continue"` 并结合组件插值
在字符串中嵌入数字	通过拼接生成的 `"Page 1 of 5"` 无法按地区格式化数字	使用 `"Page {current} of {total}"` 并结合 `Intl.NumberFormat`
在代码中存储翻译内容	分散在组件中的翻译内容难以提取和更新	集中存储在JSON/XLIFF消息目录中，每个地区对应一个文件
假设文本长度固定	德语比英语长约35%；UI会出现内容截断或溢出	设计弹性布局，使用伪本地化进行测试

References

参考资料

For detailed content on specific topics, read the relevant file from

references/

```
references/icu-message-format.md
```
- Full ICU syntax: plural, select, selectordinal, nested patterns, number/date skeletons
```
references/pluralization.md
```
- CLDR plural rules by language, plural categories, and common pitfalls
```
references/rtl-layout.md
```
- Complete RTL migration guide: CSS logical properties, bidirectional text, icon mirroring
```
references/translation-workflows.md
```
- TMS integration, XLIFF/JSON/PO formats, CI extraction, pseudolocalization

Only load a references file if the current task requires deep detail on that topic.

如需特定主题的详细内容，请阅读

references/

下的对应文件：

```
references/icu-message-format.md
```
- 完整ICU语法：复数、select、selectordinal、嵌套模板、数字/日期骨架
```
references/pluralization.md
```
- 各语言的CLDR复数规则、复数类别及常见陷阱
```
references/rtl-layout.md
```
- 完整RTL迁移指南：CSS逻辑属性、双向文本、图标镜像
```
references/translation-workflows.md
```
- TMS集成、XLIFF/JSON/PO格式、CI提取、伪本地化

仅当当前任务需要深入了解某一主题时，才加载对应的参考文件。

localization-i18n

Original

Translation

Localization & Internationalization (i18n)

本地化与国际化（i18n）

When to use this skill

何时使用此技能

Key principles

核心原则

Core concepts

核心概念

Common tasks

常见任务

Set up react-intl (FormatJS) in a React app

在React应用中搭建react-intl（FormatJS）

Set up i18next in a Node.js or React app

在Node.js或React应用中搭建i18next

Write ICU plural messages

编写ICU复数消息

Write ICU select messages (gender/category)

编写ICU select消息（性别/类别）

Format dates, numbers, and currencies per locale

按地区格式化日期、数字和货币

Configure RTL layout with CSS logical properties

使用CSS逻辑属性配置RTL布局

Extract translatable strings from source code

从源代码中提取可翻译字符串

Handle missing translations with fallback chains

通过回退链处理缺失的翻译

Anti-patterns / common mistakes

反模式/常见错误

References

参考资料

Related skills

相关技能