GTweak 本地化架构拆解：15 种语言 × 522 个键，新语种接入零额外成本
【免费下载链接】GTweakPortable Tool for an Ideal Windows Setup项目地址: https://gitcode.com/GitHub_Trending/gt/GTweak
GTweak 是一个 Windows 优化工具，内置 15 种语言的完整界面本地化。GTweak 本地化的多语言架构没有魔法，全部是结构约束：固定目录、注册文件、同步脚本三件套。读完你能拿走三样东西：一套可直接套用的多语言目录结构，区域变体命名的正确写法，一条「先干跑再写盘」的翻译同步工作流。
本地化资产全景：多语言目录结构与文件职责
GTweak 的多语言目录结构极简：全部本地化资产集中在.Source/GTweak/Languages/一个目录，其余代码只引用、不拥有它。
.Source/GTweak/Languages/ ├── LanguageCatalog.xaml # 语言注册表，15 条 ├── en/Localize.xaml # 英文基准，522 键、16 个分区 ├── pt-BR/Localize.xaml # 巴西葡萄牙语 └── zh-CN/Localize.xaml # 简体中文（共 15 个语言文件夹）| 文件 | 职责 |
|---|---|
| en/Localize.xaml | 英文基准，所有翻译的参照系，键的增删只发生在这里 |
| LanguageCatalog.xaml | 语言注册表，决定语言选择器里出现哪些语言、显示什么名字 |
| {lang}/Localize.xaml | 每种语言一份，只允许改值 |
| App.xaml.cs、GlobalOptions.cs | 运行时装配：按语言代码拼 URI 加载对应 Localize.xaml |
装配逻辑在 App.xaml.cs 的 Language setter：先拿系统 locale（形如 zh-CN）在 AvailableLangs 里精确匹配，匹配不到就剥掉地区段只按语言代码匹配，再不行落到英文，另有一条特殊映射 be → ru（白俄罗斯语借用俄语包）。AvailableLangs 本身也是生成的：GlobalOptions.cs 第 22 行把注册表 key 的下划线换成连字符后排序。语言选择器的条目完全由 LanguageCatalog.xaml 驱动，没有第二份硬编码名单。
区域变体命名规范：文件夹名与注册 key 是两套规则
区域变体（BCP-47 风格，就是「语言-地区」两段式写法）最容易踩的坑在大小写和分隔符：文件夹名和注册 key 各有一套规则，混着用就是 bug。
规则 1：文件夹用「语言小写 + 连字符 + 地区大写」。 正确：pt-BR/、zh-CN/。 错误：pt-BR 写成 pt_BR/（下划线是 key 的分隔符，不是路径的），或 ptbr/、pt-br/ 这种丢掉地区大小写区分的写法。
规则 2：注册 key 全小写、连字符变下划线。LanguageCatalog.xaml 文件头第 5–11 行的 NOTE 注释把这条写死了，实际条目：
<v:String x:Key="pt_br">Português (BR)</v:String> <v:String x:Key="zh_cn">简体中文 (CN)</v:String>错误示例：x:Key="pt-BR"。运行时 MainWinViewModel 按code.Replace("-", "_")查表，带连字符的 key 永远查不到，界面直接回退显示语言代码本身。
规则 3：语言名用原生写法，括号内附英文缩写——Português (BR)、简体中文 (CN)，而不是 English Name (PT-BR) 这种机翻感命名。
口诀：路径带连字符、地区大写；key 全小写、下划线连。
翻译纪律：Localize.xaml 的不可破规则
522 个键的翻译文件只有四条规则，破任何一条整个语言包都不可用。以 en/Localize.xaml（522 键、16 个 #region 分区）为样本：
规则 1（红线）：只改尖括号里的值，x:Key 一个字符都不许动。键是程序与界面之间的查找契约，XAML 绑定按 key 取值，改键等于断链，界面要么空白要么回落英文。
规则 2：16 个 #region 分区注释原样保留。文件按窗口切分（Load Window、Main Window、Confidentiality Page、Packages Page 等），分区让译者对着窗口逐段对照原文，也让同步脚本能按 region 名做差异比对——删掉分区注释，差异报告直接失效。
规则 3：键数与基准对齐 522。这是提交前最低成本的自检项，同步脚本的 [+/−] 报告也是以这个数为基准生成的。
规则 4：保留 XML 转义。基准里的 & 之类是 XAML 合法性的前提，翻译时顺手「修正」成 & 会让整个资源字典加载失败，522 个键全部作废。
zh-CN 里的条目长这样，键位与基准逐行对齐：
<!--#region Message Window --> <v:String x:Key="title_message">出错了...</v:String>同步工具：翻译同步脚本 LocalizeSync.cmd 的用法
防止 15 种语言掉队的翻译同步脚本是 Tools/LocalizeSync.cmd。它是个多形态脚本：前 8 行是 cmd 引导负责拉起 PowerShell，第 9 行开始才是真正的 PowerShell 逻辑，所以双击 .cmd 即可运行。
脚本以 en/Localize.xaml 为基准（-RefFile 可改），-BasePath 缺省时向上遍历目录自动定位 Languages 文件夹。它做三件事：审计 LanguageCatalog.xaml，自动把不合规 key 规范化为小写下划线；逐语言输出差异报告（[+] Keys added / [-] Keys deleted，外加 region 增删）；正式写盘时以基准文件为结构模板，把目标语言已有的值填回去，缺失键在 -Placeholder 下补成空占位条目。
参数一共 6 个，真正该记住的是三个开关：-DryRun（只报告不写盘）、-Backup（写前复制 .bak）、-Placeholder（缺失键补空占位）。推荐调用顺序：
LocalizeSync.cmd -DryRun # 第一步：只看差异，不动文件 LocalizeSync.cmd -Backup # 第二步：正式同步，先备份 LocalizeSync.cmd -DryRun # 第三步：复查，期望全部 No changes把「两次 DryRun 之间夹一次 Backup 写盘」固化成提交前流程，误操作时 .bak 就是一键回滚。
项目外围本地化：README 的多语言文档组织
多语言文档不该是本地化的边角料：文档层是程序层的镜像。根目录放了 15 份同规格 README-*.md（README-pt-br.md、README-zh-cn.md 等），命名沿用同一套区域变体规则；主 README.md 顶部一排语言徽章链接到各份文档，「Localization & Translation」章节给出提交 PR 或提 Issue 两条贡献路径，i18n 最佳实践里最容易被漏掉的文档层在这里补上了。
迁移清单：三步复刻这套 GTweak 本地化模式
复刻这套 GTweak 本地化模式只需要三步，顺序不能换。
- 先定目录结构：所有界面文案收敛进一个 Languages/ 目录，英文文件是唯一基准，UI 代码只按 key 引用、禁止硬编码文案。
- 把命名规则写成注释：文件夹大小写、key 的下划线规则、语言名格式，集中写在注册文件头部的 NOTE 里（GTweak 放在 LanguageCatalog.xaml 第 5–11 行），让贡献者先读注释再动手。
- 写一个以基准 diff 的同步脚本：至少支持干跑报告、写前备份、缺失键补占位三个开关，并把「先 DryRun 再写盘」写进贡献文档。
做到这三步，新增一种语言的成本就只剩「复制一个文件夹 + 翻译 522 个键 + 注册一行」——这正是 GTweak 本地化这套架构的全部收益。
【免费下载链接】GTweakPortable Tool for an Ideal Windows Setup项目地址: https://gitcode.com/GitHub_Trending/gt/GTweak
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
