Back to Details

localize

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Build and maintain internationalized interfaces that feel native in every supported locale, not merely translated.
Localization is more than swapping strings. It is adapting layout, formatting, content, and interaction patterns so that users in every market experience the product as intentional, not as an afterthought.
Consult the language and locale selection reference when designing language selectors, country pickers, currency choosers, or regional-preference controls. Consult the component accessibility reference when localizing custom components that must remain keyboard-navigable and screen-reader friendly across locales. Consult the error-recovery reference when localizing validation messages, error states, and recovery flows. Consult the date-input-ux and date-time-picker-ux references when adapting date, time, and calendar patterns to locale conventions.
构建并维护国际化界面，使其在每个受支持的 locale 中都显得原生，而不只是经过翻译。
本地化不只是替换字符串。它需要对布局、格式、内容和交互模式进行适配，让每个市场的用户都感受到产品是经过有意设计的，而不是事后附加的。
在设计语言选择器、国家选择器、货币选择器或区域偏好控件时，请参阅 语言与 locale 选择 参考文档。 在本地化必须保持键盘可导航且对屏幕阅读器友好的自定义组件时，请参阅 组件无障碍性 参考文档。 在本地化验证消息、错误状态和恢复流程时，请参阅 错误恢复 参考文档。 在根据 locale 约定调整日期、时间和日历模式时，请参阅 日期输入 UX 和 日期时间选择器 UX 参考文档。

MANDATORY PREPARATION

强制准备

Users start this workflow with 
/localize
. Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup first. Additionally gather: which markets and languages are targeted now and next, whether the product is content-heavy or UI-heavy, and whether translation will be done in-house, by agency, or through a TMS.
用户通过 
/localize
开始此工作流。此 skill 激活后，加载 $frontend-design——它包含设计原则、反模式以及 Context Gathering Protocol（上下文收集协议）。继续之前必须遵循该协议——如果尚不存在设计上下文，则必须先加载 $setup。此外还需收集：当前阶段和下一阶段分别要支持哪些市场与语言，产品是内容密集型还是 UI 密集型，以及翻译由内部团队、代理机构还是 TMS 完成。

Assess Localization Scope

评估本地化范围

Understand what must change and how deep the adaptation goes:
  1. Content surface area:
    • Static UI strings (labels, buttons, headings, empty states)
    • Dynamic user-generated content (names, descriptions, comments)
    • Marketing and legal copy (terms, privacy, compliance)
    • Error messages and validation feedback
    • Notifications, emails, and off-product messaging
  2. Formatting and conventions:
    • Date, time, and calendar formats (ISO vs localized display)
    • Number formats (decimal separators, grouping, currency)
    • Measurement units (metric vs imperial, currency symbols)
    • Address and phone number formats
    • Name ordering (given name first vs family name first)
    • Sorting and collation rules
  3. Layout and structural adaptation:
    • Text expansion and contraction (German +30%, Japanese -10%)
    • Right-to-left (RTL) script requirements
    • Vertical text or mixed-script layouts
    • Reading direction and scanning patterns
  4. Content and legal differences:
    • Region-specific features or catalog availability
    • Legal requirements (GDPR, CCPA, local tax, age gates)
    • Payment methods and currency support
    • Cultural imagery, colors, and symbolism
明确需要变更的内容以及适配深度：
  1. 内容覆盖面：
    • 静态 UI 字符串（标签、按钮、标题、空状态）
    • 动态用户生成内容（姓名、描述、评论）
    • 营销和法律文案（条款、隐私、合规）
    • 错误消息和验证反馈
    • 通知、邮件和产品外消息
  2. 格式与约定：
    • 日期、时间和日历格式（ISO 还是本地化显示）
    • 数字格式（小数分隔符、分组方式、货币）
    • 计量单位（公制与英制、货币符号）
    • 地址和电话号码格式
    • 姓名顺序（名在前与姓在前）
    • 排序与字序规则
  3. 布局与结构适配：
    • 文本扩展与收缩（德语 +30%，日语 -10%）
    • 从右到左（RTL）文字需求
    • 垂直文本或混合文字布局
    • 阅读方向和扫视模式
  4. 内容与法律差异：
    • 区域特定功能或商品目录可用性
    • 法律要求（GDPR、CCPA、当地税收、年龄门槛）
    • 支付方式和货币支持
    • 文化相关图像、颜色和象征

Localization Architecture

本地化架构

String Management Strategy

字符串管理策略

Key-based extraction:
  • Use descriptive, hierarchical keys: 
    checkout.shipping.title
    , 
    errors.email.required
  • Avoid English sentences as keys; they break when source copy changes
  • Include context comments for translators: 
    // Used as button label on shipping form
  • Namespace by feature or route to keep files manageable
Message format:
  • Use ICU MessageFormat for interpolation, pluralization, and gender
  • Avoid concatenating strings in code; translators need full sentences
icu
// 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')
Source language discipline:
  • Treat the source language (usually English) as the development contract
  • Write source strings for translation: complete sentences, clear pronoun references, no idioms
  • Review source copy for translatability before sending to translators
按键提取：
  • 使用描述性、分层级的键：
    checkout.shipping.title
    、
    errors.email.required
  • 避免使用英文句子作为键；源文案变化时会导致失效
  • 为翻译者添加上下文注释：
    // Used as button label on shipping form
  • 按功能或路由划分命名空间，以保持文件易于管理
消息格式：
  • 使用 ICU MessageFormat 进行插值、复数和性别处理
  • 避免在代码中拼接字符串；翻译者需要完整句子
icu
// 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')
源语言规范：
  • 将源语言（通常是英语）视为开发契约
  • 为翻译而编写源字符串：句子完整、代词指代清晰、不使用习语
  • 发送给翻译者之前，审查源文案的可译性

Locale Negotiation and Routing

locale 协商与路由

URL strategy (choose one and commit):
  • Subdirectories: 
    /en/products
    , 
    /de/products
    — SEO-friendly, shareable, clear
  • Subdomains: 
    en.example.com
    , 
    de.example.com
    — clean separation, harder to maintain
  • Query parameters: 
    ?lang=de
    — simplest to implement, worst for SEO and sharing
Locale detection order:
  1. Explicit user preference (stored in account or cookie)
  2. URL path or subdomain
  3. Browser 
    Accept-Language
    header
  4. Geolocation (use as soft default only, never hard redirect)
Locale persistence:
  • Store explicit choices in user profiles when authenticated
  • Use cookies for anonymous visitors; respect them on return
  • Never override an explicit choice with auto-detection
URL 策略（选定一种并始终采用）：
  • 子目录：
    /en/products
    、
    /de/products
    ——对 SEO 友好，可分享且清晰
  • 子域名：
    en.example.com
    、
    de.example.com
    ——分离清晰，但维护更难
  • 查询参数：
    ?lang=de
    ——实现最简单，但对 SEO 和分享最不利
locale 检测顺序：
  1. 用户明确偏好（存储在账户或 cookie 中）
  2. URL 路径或子域名
  3. 浏览器 
    Accept-Language
    请求头
  4. 地理位置（仅用作软默认值，绝不强制重定向）
locale 持久化：
  • 用户已登录时，将明确选择存储在用户资料中
  • 匿名访问者使用 cookie；再次访问时遵循这些 cookie
  • 绝不以自动检测结果覆盖明确选择

Library and Tool Selection

库和工具选择

NeedStrong optionsWhen to use
React / modern frameworksreact-i18next, Lingui, FormatJS (react-intl)Component-level translations with hooks/context
Vuevue-i18nVue 2/3 with composition or options API
Sveltesvelte-i18n, typesafe-i18nLightweight, store-based reactivity
Vanilla JS / framework-agnostici18next, FormatJS IntlMessageFormatShared across stacks, extensive plugin ecosystem
Build-time extractionLingui, typesafe-i18nSmaller bundles, no runtime parsing
Runtime extractioni18next, react-i18nextDynamic loading, CMS-driven content
Translation managementPhrase, Lokalise, Crowdin, SmartlingTeam collaboration, TMS workflows, in-context editing
Pragmatic rules:
  • Prefer one i18n library per project. Multiple libraries fragment key conventions and loading behavior.
  • If the project is small and static, build-time extraction with JSON/PO files is enough.
  • If translations change frequently or non-developers edit them, integrate a TMS early.
需求成熟选项使用场景
React / 现代框架react-i18next, Lingui, FormatJS (react-intl)使用 hooks/context 进行组件级翻译
Vuevue-i18n支持 Vue 2/3，并兼容 composition API 或 options API
Sveltesvelte-i18n, typesafe-i18n轻量级、基于 store 的响应机制
Vanilla JS / 与框架无关i18next, FormatJS IntlMessageFormat跨技术栈共享，具有广泛的插件生态
构建时提取Lingui, typesafe-i18n更小的包体积，无需运行时解析
运行时提取i18next, react-i18next动态加载、由 CMS 驱动的内容
翻译管理Phrase, Lokalise, Crowdin, Smartling团队协作、TMS 工作流、上下文内编辑
务实规则：
  • 每个项目优先只使用一个 i18n 库。多个库会导致键约定和加载行为碎片化。
  • 如果项目较小且内容静态，使用构建时提取和 JSON/PO 文件即可。
  • 如果翻译经常变化或由非开发人员编辑，应尽早集成 TMS。

Implementation Dimensions

实现维度

Text Expansion and Layout Resilience

文本扩展与布局韧性

Space budget:
  • Add 30-40% horizontal space for German, Finnish, and other expansion-heavy languages
  • Test shortest languages (Chinese, Japanese) for excessive whitespace or broken visual rhythm
  • Use min/max widths, not fixed widths, on buttons, labels, and navigation items
Container behavior:
  • Favor flexbox and grid that adapt to content length
  • Allow text wrapping; do not force single-line layouts on labels
  • Test truncation behavior when expansion exceeds available space
空间预算：
  • 为德语、芬兰语和其他扩展较多的语言增加 30-40% 的水平空间
  • 测试最短的语言（中文、日语），检查是否出现过多空白或视觉节奏被破坏
  • 在按钮、标签和导航项上使用最小/最大宽度，而不是固定宽度
容器行为：
  • 优先使用能够适应内容长度的 flexbox 和 grid
  • 允许文本换行；不要在标签上强制单行布局
  • 测试文本扩展超过可用空间时的截断行为

RTL and Bidirectional Text

RTL 与双向文本

CSS logical properties:
css
/* Use logical properties for margins, padding, borders */
margin-inline-start: 1rem;
padding-inline: 1rem;
border-inline-end: 1px solid;
Direction-aware transforms:
css
[dir="rtl"] .arrow { transform: scaleX(-1); }
[dir="rtl"] .timeline { flex-direction: row-reverse; }
Mirroring considerations:
  • Mirror navigation, breadcrumbs, and back buttons
  • Do not mirror icons that represent physical objects (clocks, text cursors)
  • Do mirror directional icons (arrows, chevrons, progress indicators)
  • Test with native RTL speakers; mechanical mirroring often misses cultural patterns
CSS 逻辑属性：
css
/* Use logical properties for margins, padding, borders */
margin-inline-start: 1rem;
padding-inline: 1rem;
border-inline-end: 1px solid;
方向感知变换：
css
[dir="rtl"] .arrow { transform: scaleX(-1); }
[dir="rtl"] .timeline { flex-direction: row-reverse; }
镜像 considerations：
  • 对导航、面包屑和返回按钮进行镜像
  • 不要镜像代表物理对象的图标（时钟、文本光标）
  • 应镜像方向性图标（箭头、尖角图标、进度指示器）
  • 请让母语 RTL 使用者参与测试；机械式镜像往往会忽略文化模式

Formatting and Data Display

格式与数据显示

Dates and times:
  • Use 
    Intl.DateTimeFormat
    or library equivalents; never hardcode format strings
  • Respect 12-hour vs 24-hour conventions per locale
  • Consider calendar systems (Gregorian, Buddhist, Islamic) where relevant
Numbers and currency:
  • Use 
    Intl.NumberFormat
    for grouping, decimals, and currency symbols
  • Currency symbols can prefix or suffix depending on locale (
    $1,234.56
    vs 
    1.234,56 €
    )
  • Display currency codes (USD, EUR) alongside symbols for clarity in multi-currency contexts
Pluralization, ordinals, and grammar:
  • Use ICU MessageFormat plural rules; do not assume English 
    one/other
  • Arabic has six plural forms; Polish has four; Welsh has six
  • Handle gendered grammar and ordinals (1st, 2nd, 3rd) through message format, not code logic
日期和时间：
  • 使用 
    Intl.DateTimeFormat
    或等效库；绝不硬编码格式字符串
  • 遵循各 locale 的 12 小时制或 24 小时制约定
  • 在相关场景中考虑日历系统（公历、佛历、伊斯兰历）
数字和货币：
  • 使用 
    Intl.NumberFormat
    处理分组、小数和货币符号
  • 货币符号的位置取决于 locale，可能位于前缀或后缀（
    $1,234.56
    与 
    1.234,56 €
    ）
  • 在多货币场景中，同时显示货币代码（USD、EUR），以提高清晰度
复数、序数和语法：
  • 使用 ICU MessageFormat 复数规则；不要假定英语只有 
    one/other
  • 阿拉伯语有六种复数形式；波兰语有四种；威尔士语有六种
  • 通过消息格式处理性别语法和序数（1st、2nd、3rd），而不是代码逻辑

Content Beyond Strings

字符串之外的内容

Images and media:
  • Replace text-in-images with live text whenever possible
  • Maintain locale-specific image sets when visuals contain culturally specific content
  • Use SVG for icons and diagrams; they scale and mirror more cleanly
URLs and SEO:
  • Use 
    hreflang
    annotations to indicate language/region variants
  • Include locale in canonical URLs
  • Localize meta titles and descriptions, not just page content
  • Avoid locale-inappropriate keywords in URL slugs
Legal and compliance content:
  • Maintain region-specific legal copy (terms, privacy, cookie notices)
  • Do not auto-translate legal text; use certified legal translators
  • Keep compliance content versioned per jurisdiction
图像和媒体：
  • 尽可能将图片中的文字替换为实时文本
  • 当视觉内容包含文化特定元素时，维护特定 locale 的图片集
  • 图标和图表使用 SVG；这样更易缩放和镜像
URL 和 SEO：
  • 使用 
    hreflang
    标注语言/地区变体
  • 在 canonical URL 中包含 locale
  • 不仅本地化页面内容，也本地化 meta 标题和描述
  • 避免在 URL slug 中使用不适合相应 locale 的关键词
法律和合规内容：
  • 维护特定地区的法律文案（条款、隐私、Cookie 通知）
  • 不要自动翻译法律文本；应使用经认证的法律翻译人员
  • 按司法辖区对合规内容进行版本管理

Translation Workflow

翻译工作流

Developer handoff:
  1. Extract strings from code into translation files (JSON, PO, YAML)
  2. Add context comments and screenshot references for ambiguous strings
  3. Freeze source strings before sending to translation to prevent mid-translation churn
  4. Version translation files alongside code releases
Quality assurance:
  • Review translations for truncation, overflow, and broken layout
  • Verify that placeholders and HTML tags are preserved
  • Check that gendered translations match the intended context
  • Run pseudo-localization (accented expansion) before real translation to catch layout bugs early
Continuous localization:
  • Integrate TMS with version control (GitHub/GitLab webhooks)
  • Automate extraction on pull requests
  • Set up translation memory to reduce cost and improve consistency
  • Notify translators of new or changed keys promptly
开发者移交：
  1. 将字符串从代码中提取到翻译文件（JSON、PO、YAML）
  2. 为含义不明确的字符串添加上下文注释和截图引用
  3. 发送翻译前冻结源字符串，防止翻译过程中频繁变更
  4. 将翻译文件与代码发布一起进行版本管理
质量保证：
  • 审查翻译中的截断、溢出和布局破坏
  • 验证占位符和 HTML 标签均已保留
  • 检查带性别的翻译是否符合预期语境
  • 在正式翻译前运行伪本地化（重音扩展），尽早发现布局缺陷
持续本地化：
  • 将 TMS 与版本控制集成（GitHub/GitLab webhooks）
  • 在拉取请求上自动执行提取
  • 设置翻译记忆库（translation memory），以降低成本并提高一致性
  • 及时通知翻译者新增或变更的键

Testing Localized UI

测试本地化 UI

Layout testing:
  • Test with longest and shortest supported languages
  • Verify RTL layouts with native browser direction switching
  • Check truncation, wrapping, and overflow at minimum and maximum viewport widths
Functional testing:
  • Validate that interpolation variables populate correctly in all locales
  • Confirm pluralization rules render correctly (0, 1, 2, 5, 11, 21 items)
  • Test locale switching without full page reload where applicable
  • Verify that persisted locale preferences survive logout and re-login
Content testing:
  • Spot-check translations for accuracy and tone consistency
  • Verify that legal and compliance copy matches the certified version
  • Ensure that localized URLs and SEO metadata are present
布局测试：
  • 使用最长和最短的受支持语言进行测试
  • 通过浏览器原生方向切换验证 RTL 布局
  • 在最小和最大视口宽度下检查截断、换行和溢出
功能测试：
  • 验证插值变量在所有 locale 中均能正确填充
  • 确认复数规则能正确呈现（0、1、2、5、11、21 个项目）
  • 在适用情况下，测试无需整页重新加载即可切换 locale
  • 验证持久化的 locale 偏好在退出并重新登录后仍然保留
内容测试：
  • 抽查翻译的准确性和语气一致性
  • 验证法律和合规文案与认证版本一致
  • 确保本地化 URL 和 SEO 元数据完整存在

Anti-Patterns

反模式

  • Concatenate translated fragments: Translators need complete sentences. 
    t('you_have') + count + t('messages')
    breaks in most languages.
  • Hardcode locale assumptions: Do not assume left-to-right, 12-hour time, MM/DD/YYYY, or English plural rules.
  • Auto-translate UI without review: Machine translation for UI strings produces inconsistent terminology and broken grammar.
  • Ignore text expansion: Fixed-width buttons and labels break in German and other expansion-heavy languages.
  • Use flags for languages: A flag represents a country, not a language. Spanish has 20+ countries; English has dozens. Use language names or neutral icons.
  • Redirect based on IP alone: Travelers, VPN users, and expats get trapped in wrong locales. Suggest, do not force.
  • Skip pseudo-localization: Running pseudo-locale tests before real translation catches layout and truncation bugs when they are still cheap to fix.
  • Store translations in version control without versioning: Translation files should be tagged and released alongside code so rollback is possible.
  • Forget to localize error messages: Untranslated validation errors are a frequent source of user confusion and abandonment.
  • Treat localization as a one-time project: Languages evolve, products add features, and markets change. Localization is continuous maintenance.
  • 拼接翻译片段：翻译者需要完整句子。
    t('you_have') + count + t('messages')
    在大多数语言中都会失效。
  • 硬编码 locale 假设：不要假定从左到右、12 小时制、MM/DD/YYYY 或英语复数规则。
  • 未经审核就自动翻译 UI：机器翻译 UI 字符串会造成术语不一致和语法错误。
  • 忽视文本扩展：固定宽度的按钮和标签在德语及其他扩展较多的语言中会失效。
  • 使用旗帜表示语言：旗帜代表国家，而不是语言。西班牙语覆盖 20 多个国家，英语覆盖数十个国家。使用语言名称或中性图标。
  • 仅根据 IP 重定向：旅行者、VPN 用户和侨居者会被困在不正确的 locale。建议而不是强制。
  • 跳过伪本地化：在正式翻译前运行伪 locale 测试，可以在修复成本尚低时发现布局和截断缺陷。
  • 将翻译存储在版本控制中却不进行版本管理：翻译文件应打标签，并与代码一同发布，以便回滚。
  • 忘记本地化错误消息：未翻译的验证错误是用户困惑和放弃使用的主要来源之一。
  • 将本地化视为一次性项目：语言会演变，产品会增加功能，市场也会变化。本地化需要持续维护。

Verify Localization Readiness

验证本地化就绪状态

Before shipping a localized product:
  • All user-facing strings are extracted and keyed, not hardcoded
  • Source copy is reviewed for translatability (complete sentences, no idioms)
  • Layouts are tested with longest and shortest target languages
  • RTL scripts are supported with logical properties and directional testing
  • Date, number, and currency formatting use locale-aware APIs
  • Pluralization handles all target language plural forms correctly
  • Locale switching preserves user context and state
  • URLs include locale and use 
    hreflang
    annotations
  • Legal and compliance copy is region-specific and certified
  • Translation workflow is documented and integrated with release cadence
  • Pseudo-localization passes layout and truncation checks before real translation begins
在发布本地化产品之前：
  • 所有面向用户的字符串都已提取并设置键值，而不是硬编码
  • 源文案已完成可译性审查（句子完整、无习语）
  • 已使用最长和最短的目标语言测试布局
  • RTL 文字通过逻辑属性和方向测试得到支持
  • 日期、数字和货币格式使用 locale 感知 API
  • 复数处理正确涵盖所有目标语言的复数形式
  • 切换 locale 时会保留用户上下文和状态
  • URL 包含 locale，并使用 
    hreflang
    标注
  • 法律和合规文案针对不同地区，且经过认证
  • 翻译工作流已记录并与发布节奏集成
  • 在正式翻译开始前，伪本地化已通过布局和截断检查