GitHub #28303 分析：zh-CN/zh-TW 重命名为 zh-Hans/zh-Hant（附修改方案）

by

GitHub Issue #28303 是一个小而美的 i18n 改进任务，本文分析其价值和具体修改方案，供开发者参考。

问题背景

OpenClaw 当前使用 zh-CN 和 zh-TW 作为中文本地化的 locale 标识符。这两个是基于 region（地区）的代码，实际区分的是”简体中文”和”繁体中文”，但代码本身并没有表达这个语义。

技术分析

BCP 47 标准推荐使用 script-based codes：

  • zh-CN → zh-Hans（简体中文）
  • zh-TW → zh-Hant（繁体中文）

原因： Simplified Chinese 不只在中国用，新加坡、马来西亚也用； Traditional Chinese 也不只台湾用，香港、澳门也用。地区代码错误地暗示了语言变体和一个国家的绑定。

影响范围

  • types.ts 中的 locale 类型定义
  • translate.ts 中的 SUPPORTED_LOCALES 数组
  • locale 文件名：zh-CN.ts → zh-Hans.ts
  • 动态 import 路径
  • navigator.language 检测逻辑
  • localStorage 用户数据迁移
  • 语言选择器的显示名称

修改示例

// translate.ts
// 修改前
const SUPPORTED_LOCALES = ['en', 'zh-CN', 'zh-TW', 'ja'];

// 修改后
const SUPPORTED_LOCALES = ['en', 'zh-Hans', 'zh-Hant', 'ja'];
// locale 文件重命名
zh-CN.ts → zh-Hans.ts
zh-TW.ts → zh-Hant.ts
// localStorage 迁移（需要向后兼容）
const LEGACY_MAP = { 'zh-CN': 'zh-Hans', 'zh-TW': 'zh-Hant' };
const saved = localStorage.getItem('locale');
if (LEGACY_MAP[saved]) localStorage.setItem('locale', LEGACY_MAP[saved]);

注意事项

  • Severity: Low（无功能变更，仅标识符调整）
  • 需要 localStorage 迁移逻辑，否则已有用户会丢失语言偏好
  • 影响范围仅限 i18n 系统

这是一个适合新人入手的 good-first-issue，scope 清晰，规则明确。

Leave a Comment