internationalization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Internationalization

国际化

Add languages and regions in a way that works for users, search engines, and the team maintaining the content. Stack-agnostic.

以兼顾用户、搜索引擎和内容维护团队的方式添加语言和区域设置。与技术栈无关。

When to use

适用场景

Adding the first non-English (or non-default) language
Adding additional locales to an existing internationalized site
Choosing URL structure for languages
Implementing hreflang tags
Designing translation workflow
Handling currency, date, time, and number formats
Designing or fixing layout for RTL languages
Auditing an internationalization rollout that's underperforming

添加第一种非英语（或非默认）语言
为已实现国际化的网站添加更多区域设置（locale）
选择语言对应的URL结构
实现hreflang标签
设计翻译工作流
处理货币、日期、时间和数字格式
设计或修复RTL语言的页面布局
审核表现不佳的国际化部署

When NOT to use

不适用场景

Single-language site (use other skills)
Domain strategy that's not language-driven (use
```
domain-strategy
```
)
Content strategy independent of locale (use
```
content-strategy
```
)
Marketing copy production (use
```
content-and-copy
```
)

单语言网站（使用其他技能）
非语言驱动的域名策略（使用
```
domain-strategy
```
）
独立于区域设置的内容策略（使用
```
content-strategy
```
）
营销文案创作（使用
```
content-and-copy
```
）

Required inputs

必要输入

The locales in scope (language + region, e.g.,
```
en-US
```
,
```
de-DE
```
,
```
fr-CA
```
)
Business reason per locale (priority, audience size)
Existing site architecture
Translation resources (in-house, agency, AI-assisted, community)
Content volume and update frequency

涉及的区域设置（语言+区域，例如
```
en-US
```
、
```
de-DE
```
、
```
fr-CA
```
）
每个区域设置的业务原因（优先级、受众规模）
现有网站架构
翻译资源（内部团队、代理机构、AI辅助、社区贡献）
内容体量和更新频率

The framework: 5 layers

框架：5个层级

Internationalization touches everything. Five layers, each with their own decisions.

国际化涉及方方面面。以下5个层级，每个层级都有对应的决策要点。

Layer 1: URL structure

层级1：URL结构

How locales are reflected in URLs.

Pattern	Example	When
ccTLD	example.de, example.fr	Strong country focus, distinct legal entities, willing to maintain separate domains
Subdomain	de.example.com, fr.example.com	Logical separation, willing to host separately, common for large sites
Subfolder	example.com/de/, example.com/fr/	SEO equity unified, simplest to manage, default for most
URL parameter	example.com?lang=de	Avoid; weak SEO signal

For most sites: subfolder is the default. Subdomain or ccTLD only when there's a specific reason (legal, infrastructure, or brand).

Within the chosen pattern, decide:

Language only (
```
/de/
```
) or language plus region (
```
/de-de/
```
,
```
/de-at/
```
,
```
/de-ch/
```
)?
Default locale: at the apex (
```
example.com
```
) or in a folder (
```
example.com/en/
```
)?

The default-locale-at-apex pattern is common but causes hreflang complexity (the apex needs an

x-default

and the canonical for the default language).

区域设置在URL中的呈现方式。

模式	示例	适用场景
ccTLD	example.de, example.fr	有强烈的国家聚焦、独立法律实体、愿意维护独立域名
子域名	de.example.com, fr.example.com	需要逻辑分离、愿意独立托管，大型网站常用
子文件夹	example.com/de/, example.com/fr/	SEO权益统一、管理最简单，大多数网站的默认选择
URL参数	example.com?lang=de	避免使用；SEO信号较弱

对于大多数网站：子文件夹是默认选择。仅当存在特定原因（法律、基础设施或品牌需求）时，才选择子域名或ccTLD。

在选定模式后，需确定：

仅使用语言（
```
/de/
```
）还是语言+区域（
```
/de-de/
```
、
```
/de-at/
```
、
```
/de-ch/
```
）？
默认区域设置：放在根域名（
```
example.com
```
）还是子文件夹（
```
example.com/en/
```
）？

默认区域设置放在根域名的模式很常见，但会增加hreflang的复杂度（根域名需要设置

x-default

，同时作为默认语言的规范链接）。

Layer 2: Content structure

层级2：内容结构

How content is organized across locales.

Pattern A: Mirror. Every page in every locale. The translation IS the page. Suitable for marketing sites with controlled content.

Pattern B: Subset. Some content in all locales, some only in select locales. Common for product pages (only available products), blog (some posts translated), or regulatory differences.

Pattern C: Local. Each locale has its own content largely independent of other locales. Common for media or community sites.

Most marketing sites are A. Most large sites end up at B by necessity. C is for sites with strong regional editorial.

The pattern affects:

How content models are designed (does each piece have parent/translation relationships?)
How translation is managed (workflow assumes the structure)
How the team coordinates

内容在不同区域设置间的组织方式。

模式A：镜像式。每个区域设置下都有所有页面。翻译内容即为对应页面。适用于内容可控的营销网站。

模式B：子集式。部分内容覆盖所有区域设置，部分内容仅在特定区域设置中存在。常见于产品页面（仅展示可用产品）、博客（部分文章翻译）或因法规差异导致的内容区分。

模式C：本地化。每个区域设置拥有独立于其他区域的内容。常见于媒体或社区类网站。

大多数营销网站采用模式A。大多数大型网站因实际需求最终会转向模式B。模式C适用于具有强大区域编辑能力的网站。

所选模式会影响：

内容模型的设计方式（每条内容是否需要设置父内容/翻译关联？）
翻译的管理方式（工作流需适配内容结构）
团队的协作方式

Layer 3: hreflang and canonicals

层级3：hreflang与规范链接

Telling search engines what's translated vs distinct.

hreflang specifies the language and optional region for each version.

html

<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page">
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page">
<link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/page">
<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page">

Rules:

Every page lists every translated equivalent (including itself)
Pages must reciprocate (page A says page B is its German version; page B says page A is its English version)
```
x-default
```
is the fallback for users in unspecified regions
Each page has its own canonical pointing to itself (not to the default language)

hreflang can be in the HTML head, in HTTP headers, or in the XML sitemap. Sitemap is best for large sites; HTML head is fine for small.

Canonicals:

Self-referential per page
Don't canonical the German page to the English page (search engines won't index the German page)

告知搜索引擎哪些内容是翻译版本，哪些是独立内容。

hreflang 指定每个版本对应的语言及可选区域。

html

<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page">
<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page">
<link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/page">
<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page">

规则：

每个页面需列出所有翻译版本（包括自身）
页面间需相互关联（页面A标注页面B为其德语版本；页面B需标注页面A为其英语版本）
```
x-default
```
是针对未指定区域用户的回退版本
每个页面的规范链接需指向自身（而非默认语言版本）

hreflang可放在HTML头部、HTTP头部或XML站点地图中。站点地图适合大型网站；HTML头部适合小型网站。

规范链接：

每个页面的规范链接指向自身
不要将德语页面的规范链接指向英语页面（否则搜索引擎不会索引德语页面）

Layer 4: Translation workflow

层级4：翻译工作流

How content gets translated, kept fresh, and quality-controlled.

Sources of translation:

In-house translators (full-time staff)
Translation agency (paid per word, professional)
Community contributors (volunteer, variable quality, free)
AI-assisted plus human review (cheap, fast, growing in quality)
AI only (acceptable for some content, not for brand-critical)

Workflow stages:

Source content authored in the source language
Translation requested through a TMS (translation management system) or spreadsheet
Translation produced with translation memory (avoids retranslating reused phrases)
Review by a second translator or in-region staff
Localization beyond translation (currency, units, examples, cultural references)
Publishing in the destination locale
Update propagation when source content changes

The TMS pays off above ~10K words of total content. Below that, spreadsheets and disciplined naming are fine.

Update propagation is the hardest part. Source content changes. Translations go stale. Without a process, you end up with locales drifting from the source.

内容如何完成翻译、保持更新并确保质量。

翻译来源：

内部翻译人员（全职员工）
翻译代理机构（按字数付费，专业级）
社区贡献者（志愿参与，质量参差不齐，免费）
AI辅助+人工审核（成本低、速度快，质量持续提升）
纯AI翻译（适用于部分内容，不适用于品牌核心内容）

工作流阶段：

源内容创作：使用源语言创作内容
翻译请求：通过TMS（翻译管理系统）或电子表格发起请求
翻译生成：使用翻译记忆库（避免重复翻译常用短语）
审核：由第二名翻译人员或区域内工作人员审核
本地化处理：除翻译外的适配（货币、单位、示例、文化参考）
发布：在目标区域设置中发布内容
更新同步：源内容变更时同步更新翻译内容

当总内容量超过约10000词时，TMS的价值会凸显。低于此规模时，使用电子表格并保持规范命名即可。

更新同步是最困难的环节。源内容变更后，翻译内容会过时。若无流程管控，各区域设置的内容会与源内容逐渐脱节。

Layer 5: Locale-aware UX

层级5：区域设置适配型UX

Beyond translation, the experience must adapt.

Currency: display in the local currency where applicable. EUR for European locales, JPY for Japanese, etc. Don't show USD to French users for a French-locale page.

Numbers: thousand separators and decimals differ.

1,000.50

in en-US is

1.000,50

in de-DE.

Dates and times: format and order vary.

MM/DD/YYYY

in en-US,

DD/MM/YYYY

in en-GB,

YYYY-MM-DD

(ISO) is universal but unfamiliar to many.

Names and addresses: field order and required components differ. Country-aware address forms.

Phone numbers: E.164 international format universally; display formatting per locale.

Units: metric vs imperial. Most of the world is metric; the US is imperial. Some products serve both.

Right-to-left (RTL) languages: Arabic, Hebrew, Persian, Urdu. Layout flips: navigation moves right, text aligns right, icons that imply direction may flip too. CSS logical properties (

margin-inline-start

instead of

margin-left

) make this manageable.

Language switcher: prominent but not intrusive. Show locale names in their own language ("Deutsch" not "German"). Persist the choice. Don't auto-redirect based on browser language without offering a way back.

Cultural sensitivity: colors, imagery, examples, references that don't translate. Avoid hand gestures in product imagery. Avoid country-specific references unless localized.

除翻译外，用户体验也需适配区域特性。

货币： 适用时显示当地货币。欧洲区域设置显示EUR，日本区域设置显示JPY等。不要向法语区域设置的用户显示美元。

数字： 千位分隔符和小数表示方式不同。en-US中的

1,000.50

在de-DE中是

1.000,50

。

日期和时间： 格式和顺序各异。en-US为

MM/DD/YYYY

，en-GB为

DD/MM/YYYY

，ISO格式

YYYY-MM-DD

通用但对许多用户来说不熟悉。

姓名和地址： 字段顺序和必填项不同。需使用适配国家的地址表单。

电话号码： 通用采用E.164国际格式；显示格式需适配区域设置。

单位： 公制 vs 英制。世界大部分地区使用公制；美国使用英制。部分产品需同时支持两种单位。

从右到左（RTL）语言： 阿拉伯语、希伯来语、波斯语、乌尔都语。布局需翻转：导航栏移至右侧，文本右对齐，带有方向指向的图标也需翻转。使用CSS逻辑属性（如

margin-inline-start

替代

margin-left

）可简化此操作。

语言切换器： 显眼但不突兀。用区域自身的语言显示区域名称（显示"Deutsch"而非"German"）。保留用户选择。不要仅根据浏览器语言自动跳转，需提供返回途径。

文化敏感性： 颜色、图片、示例、参考内容需避免文化冲突。产品图片中避免使用手势。除非经过本地化，否则避免使用特定国家的参考内容。

Workflow

工作流

Step 1: Decide which locales

步骤1：确定区域设置

Don't add languages just because you can. Each locale has ongoing maintenance cost.

Audience research: where are visitors and prospects?
Business priority: which markets are growth targets?
Content readiness: do you have the resources to maintain it?
Legal: do regulations require localization (GDPR, accessibility laws)?

不要为了添加而添加语言。每个区域设置都有持续的维护成本。

受众调研：访客和潜在客户来自哪些地区？
业务优先级：哪些市场是增长目标？
内容准备情况：是否有资源维护该区域的内容？
法律要求：法规是否要求本地化（GDPR、无障碍法规）？

Step 2: Pick URL structure

步骤2：选择URL结构

Subfolder for most. Document the choice and rationale.

大多数情况选择子文件夹。记录选择及理由。

Step 3: Pick content structure

步骤3：选择内容结构

Mirror, subset, or local. Be honest about what's sustainable.

镜像式、子集式或本地化。如实评估可持续性。

Step 4: Set up hreflang and canonicals

步骤4：配置hreflang与规范链接

Implement before launching the second locale, even if it's just one extra page.

在推出第二个区域设置前完成配置，即使仅新增一个页面。

Step 5: Set up translation workflow

步骤5：搭建翻译工作流

Pick a TMS or spreadsheet system. Document the workflow. Designate translators and reviewers.

选择TMS或电子表格系统。记录工作流。指定翻译人员和审核人员。

Step 6: Localize beyond translation

步骤6：翻译之外的本地化处理

For each locale:

Currency, numbers, dates, units
Locale-specific images if needed
Address forms
Customer service hours and contact

针对每个区域设置：

货币、数字、日期、单位
必要时使用区域特定图片
地址表单
客服时间和联系方式

Step 7: Implement language switcher

步骤7：实现语言切换器

Prominent in the header or footer
Shows the current locale clearly
Lists all available locales in their own language
Persists the choice (cookie or local storage)
Doesn't auto-redirect based on browser; suggests instead

放置在页眉或页脚的显眼位置
清晰显示当前区域设置
用区域自身语言列出所有可用区域设置
保留用户选择（通过Cookie或本地存储）
不要仅根据浏览器语言自动跳转，而是提供建议

Step 8: Test

步骤8：测试

Each locale renders correctly
hreflang links are valid (use a checker)
Canonicals are self-referential per page
Currency and dates are correct
RTL layout is correct (for RTL locales)
Language switcher works and persists
Search-engine perspective: each locale is crawlable and indexable

每个区域设置的页面渲染正常
hreflang链接有效（使用检查工具）
每个页面的规范链接指向自身
货币和日期显示正确
RTL布局正常（针对RTL区域设置）
语言切换器功能正常且保留用户选择
搜索引擎视角：每个区域设置的内容可抓取且可索引

Step 9: Launch and monitor

步骤9：上线与监控

Per locale:

Indexing rate
Traffic from intended geographies
Engagement metrics in the locale
Translation freshness (when did source content change without translation update?)

针对每个区域设置：

索引率
目标地区的流量
该区域的用户参与度指标
翻译内容的新鲜度（源内容变更后翻译内容是否未更新？）

Step 10: Maintain

步骤10：维护

Translation update cadence (when source changes, when translations follow)
Quarterly review of locale performance
Sunset locales that aren't viable (better than maintaining a dead locale poorly)

翻译更新节奏（源内容变更后，翻译内容何时跟进）
每季度审核区域设置的表现
停止维护无价值的区域设置（比糟糕地维护废弃区域设置更好）

Failure patterns

失败案例

Auto-redirect based on browser language. User is in Germany, prefers English. Site forces German. Frustrating. Suggest, don't redirect.

Single canonical to default language. Search engines can't index the translations. Self-canonical per page.

Reciprocal hreflang missing. German page lists English as its translation, English page doesn't list German. Search engines treat the relationship as unconfirmed.

hreflang language without region when region matters.

hreflang="es"

is fine if there's one Spanish version. If you have es-ES (Spain) and es-MX (Mexico), use both with regions.

Auto-translated content treated as final. Machine translation is an acceptable starting point. Human review is necessary for any user-facing content.

Currency baked into copy. "$99/month" in body text breaks for European users. Use templated currency that adapts.

Hardcoded date formats. "January 5, 2024" in code. Doesn't adapt. Use a date formatting library that respects locale.

Field labels left in source language. Translated body, untranslated form labels. Inconsistent. Translate UI strings as part of localization.

Untranslated error messages. User submits a form, gets an error in English on a French page. Frustrating. Translate UI states.

Untranslated emails. Site is in French; transactional emails are English. Translate emails to match.

Forgotten locales in CMS. Editors forget to update one locale. Drift. Use a TMS or workflow that surfaces drift.

Locale switcher that doesn't work mid-flow. User is on the German checkout, switches to French, lands on French homepage. Try to land on the same page in the new locale.

RTL layouts that don't actually flip. Margin and padding hardcoded for LTR. Use CSS logical properties.

Sunset language without redirect. Discontinuing French; old French URLs 404. Redirect to the closest equivalent in another supported language.

根据浏览器语言自动跳转。用户在德国但偏好英语，网站强制跳转至德语版本。体验糟糕。应提供建议而非强制跳转。

统一规范链接指向默认语言。搜索引擎无法索引翻译版本。每个页面的规范链接需指向自身。

缺失双向hreflang关联。德语页面标注英语页面为其翻译版本，但英语页面未标注德语页面为其翻译版本。搜索引擎会认为该关联未确认。

当区域重要时仅使用语言的hreflang。如果只有一个西班牙语版本，

hreflang="es"

没问题。但如果有es-ES（西班牙）和es-MX（墨西哥）版本，则需同时使用带区域的标签。

将自动翻译内容视为最终版本。机器翻译可作为起点，但任何面向用户的内容都需要人工审核。

货币硬编码到文案中。正文中的"$99/month"对欧洲用户不适用。使用可适配的模板化货币显示方式。

硬编码日期格式。代码中的"January 5, 2024"无法适配区域设置。使用支持区域设置的日期格式化库。

字段标签保留源语言。正文已翻译，但表单标签未翻译。体验不一致。本地化需包含UI字符串的翻译。

错误消息未翻译。用户提交表单后，法语页面显示英语错误信息。体验糟糕。需翻译所有UI状态信息。

邮件未翻译。网站是法语版本，但事务性邮件是英语。邮件翻译需与网站语言匹配。

CMS中遗漏区域设置更新。编辑人员忘记更新某个区域的内容。内容逐渐脱节。使用TMS或可识别内容脱节的工作流。

流程中途语言切换器失效。用户在德语结账页面切换至法语，却跳转到法语首页。应尝试跳转到新区域设置下的同一页面。

RTL布局未真正翻转。边距和内边距为LTR硬编码。使用CSS逻辑属性。

停用语言时未设置跳转。停止支持法语；旧法语URL返回404错误。需重定向至其他支持语言的最接近等效页面。

Output format

输出格式

An internationalization plan includes:

Locale list: with priority and audience rationale
URL structure: chosen pattern and reason
Content structure: mirror, subset, or local
hreflang plan: how it's implemented
Translation workflow: sources, stages, tools
Localization checklist: beyond translation (currency, dates, etc.)
Language switcher design: position, behavior, persistence
Test plan: what's verified per locale
Maintenance plan: update cadence, drift detection

国际化计划应包含：

区域设置列表：含优先级和受众理由
URL结构：选定模式及理由
内容结构：镜像式、子集式或本地化
hreflang方案：实现方式
翻译工作流：来源、阶段、工具
本地化检查清单：翻译之外的适配项（货币、日期等）
语言切换器设计：位置、行为、用户选择保留方式
测试方案：每个区域设置需验证的内容
维护方案：更新节奏、内容脱节检测机制

Reference files

参考文件

```
references/locale-checklist.md
```
: Per-locale checklist of everything that needs to adapt beyond translation, organized by category (URL, content, UX, format, legal).

```
references/locale-checklist.md
```
：每个区域设置需适配的所有非翻译项检查清单，按类别（URL、内容、UX、格式、法律）整理。