如何正确使用语言国家英文缩写进行国际化配置？

Question

在国际化（i18n）配置中，如何正确使用语言-国家英文缩写（如 en-US、zh-CN）是常见痛点。开发者常混淆 ISO 639-1 语言代码与 ISO 3166-1 国家代码的组合规则，导致资源文件加载失败或 locale 匹配错误。例如，误将“中文简体”写作 “zh-SG”（应为 zh-CN）或使用非标准格式如 “zh_cn”。此外，Java、Spring、React Intl 等框架对大小写敏感性处理不一，可能引发运行时异常。如何确保缩写规范统一，并在多平台环境中正确映射到对应语言包？这是实现精准本地化的关键问题。

Answer 1

1. 国际化（i18n）中的语言-国家代码基础概念

在国际化配置中，语言-国家代码（如 en-US、zh-CN）是定位资源文件的核心标识。这类代码遵循 BCP 47（Best Current Practice 47）标准，由语言子标签（ISO 639-1）和可选的地区子标签（ISO 3166-1 alpha-2）组成，中间以连字符“-”连接。

语言-国家代码	语言	国家/地区	常见误写
zh-CN	中文（简体）	中国	zh_cn, zh-sg, zh-Hans
zh-TW	中文（繁体）	台湾	zh-tw, zh_Hant, zh-HK
en-US	英语	美国	en_us, en, en-US
en-GB	英语	英国	en_UK, en-gb
fr-FR	法语	法国	fr_fr, fr
de-DE	德语	德国	de_de, DE
ja-JP	日语	日本	ja_jp, jp
ko-KR	韩语	韩国	ko_kr, kr
es-ES	西班牙语	西班牙	es_es, es-MX
pt-BR	葡萄牙语	巴西	pt_br, pt-PT

2. 常见错误与框架差异分析

开发者常因混淆标准导致资源加载失败。例如将新加坡中文写作 zh-SG，虽然存在该变体，但其通常应继承自 zh-CN 或使用独立的语言包。真正的规范简体中文为中国大陆，应为 zh-CN。而 zh-SG 虽合法，但需明确是否提供特定本地化内容。

不同技术栈对大小写敏感性处理不一致：

• Java / Spring Boot：Locale 类对格式较宽松，但推荐使用 new Locale("zh", "CN") 构造，内部转为 zh_CN 下划线格式；但在资源文件命名中建议使用 messages_zh_CN.properties。
• React Intl：依赖 Intl.Locale API，严格遵循 BCP 47，要求连字符且大小写不敏感（但推荐小写），如 zh-CN。
• Node.js i18next：支持多种格式，可通过插件规范化输入，但仍建议统一使用小写连字符格式。

3. 规范化策略与工程实践

为确保多平台一致性，应建立标准化流程：

1. 定义项目级语言代码白名单（如 JSON 配置）
2. 在 CI/CD 中加入校验脚本，检测资源文件名合法性
3. 封装 locale 解析工具类，自动归一化输入（如将 zh_cn → zh-CN）
4. 使用 TypeScript 接口或枚举限定支持的语言选项
5. 文档化团队内部 i18n 命名规范，并集成至代码模板

// 示例：TypeScript 枚举约束合法 locale
enum SupportedLocales {
  ZH_CN = 'zh-CN',
  EN_US = 'en-US',
  JA_JP = 'ja-JP',
  KO_KR = 'ko-KR'
}

function normalizeLocale(input: string): string | null {
  const normalized = input.replace('_', '-').toLowerCase();
  return Object.values(SupportedLocales).includes(normalized as any) 
    ? normalized 
    : null;
}

4. 多平台映射与自动化流程设计

在跨技术栈项目中，需实现语言代码的统一映射层。以下 Mermaid 流程图展示从用户请求到资源加载的标准化路径：

graph TD A[用户浏览器 Accept-Language] --> B{解析并归一化} B --> C[zh_cn → zh-CN] B --> D[en-us → en-US] C --> E[查询支持语言白名单] D --> E E --> F{匹配成功?} F -- 是 --> G[加载对应语言包] F -- 否 --> H[回退至默认 locale (如 en-US)] G --> I[返回本地化内容] H --> I