为什么 GTweak 的 15 种语言从不失守？一次看懂新增语言的 3 步避坑流程

为什么 GTweak 的 15 种语言从不失守一次看懂新增语言的 3 步避坑流程【免费下载链接】GTweakPortable Tool for an Ideal Windows Setup项目地址: https://gitcode.com/GitHub_Trending/gt/GTweak新功能上线英文基准文件多了几十条文案其他 14 种语言却还停留在旧版本——直到巴西用户打开 GTweak发现界面半句葡萄牙语、半句英文。维护多语言桌面应用的人对这一幕不会陌生。GTweak 是一款免安装的 Windows 优化工具仓库里维护着 15 种语言每份语言文件恰好 522 条文案长期没有失守过。它靠的是一套统一约定加一个同步脚本下面按流程拆开看。新功能上线后14 种语言集体夹杂英文显示到底做错了什么这类问题九成出在同一处键值分离只译了值却没管键。GTweak 把所有界面文案集中在.Source/GTweak/Languages/目录每种语言一个文件夹里面放一份Localize.xaml。把 zh-CN/Localize.xaml 和 en/Localize.xaml 的前几行并排放一眼就能看懂英文里的v:String x:Keybtn_changeChange/v:String在中文文件里就是同一个x:Key配上值「更改」。键是程序与界面之间的契约改键等于撕毁契约界面会直接找不到那段文字。文件内部还有一条隐性规则每份文件用#region注释切成 16 个分区Load Window、Main Window、Confidentiality Page、Toolset Page 等。作者新增文案时先落到对应分区15 种语言共用同一套分区骨架这就是「条数能对上」的结构基础。那为什么缺了键不会报错而是显示英文看App.xaml.cs第 91~97 行的加载逻辑先按「语言-地区」精确匹配匹配不到退回「只有语言」再匹配不到加载 en。缺的条目自然落回英文原文——官方 README 里也明说了「未翻译的部分默认显示英文」。三步走通翻译贡献全流程建文件夹、翻键值、登记名字第一步建文件夹命名对齐 Windows 语言包。文件夹名用语言代码单一语言写fr、ko这类两字符代码区域变体写「语言-地区」如pt-BR巴西葡语、zh-CN简体中文。地区代码全大写、用连字符连接。运行时按地区精确匹配zh-CN和zh-TW繁体中文是两份完全独立的文件不能互相借用。第二步只翻值保留分区对齐条数。复制en文件夹后只改引号内的值x:Key一个字母都不动#region分区注释全部保留。提交前把键数与基准文件核对一遍——当前基准是 522 键15 种语言清一色 522 键条数一致是最基本的自检项。第三步在「户口本」上登记。LanguageCatalog.xaml 是所有语言的登记表文件顶部有一段 NOTE 注释第 5~11 行写清规则语言名写原生拼写括号内附英文缩写key 全小写、连字符换成下划线。两个区域变体在文件里的实际样子v:String x:Keypt_brPortuguês (BR)/v:String v:String x:Keyzh_cn简体中文 (CN)/v:String注意文件夹与 key 的对照文件夹是pt-BRkey 是pt_br。路径带横线、地区大写key 全小写、用下划线。这是新人最容易踩的坑。文件夹名与 key 为什么用两套大小写规则因为它们服务两套系统。文件夹名面向 Windows启动时程序读取系统区域设置拼出pt-BR这样的代码去定位文件夹所以文件夹名必须和语言包代码完全一致包括地区部分的大小写。key 面向 .NET 资源字典LanguageCatalog.xaml以 ResourceDictionary 方式加载key 本质是区域标识符区域化标识符的惯例就是小写加下划线的pt_br。程序运行时在GlobalOptions.cs第 22 行做一次Replace(_, -)还原成pt-BR设置面板里显示的才是完整区域代码。好消息是key 的大小写写错了也不会永远错着同步脚本里有专门的键名规范化环节会把带连字符或大写的 key 自动改写成小写下划线形式。顺带一提代码里还有个特例——系统语言是be白俄罗斯语时直接复用俄语资源。缺键了用 LocalizeSync 的 3 个开关一次对齐 15 份翻译15 份文件、每份 522 键纯手工维护迟早对不上号。仓库因此内置了 Tools/LocalizeSync.cmd——一个用 cmd 包起来的 PowerShell 脚本双击即可运行。它默认以en/Localize.xaml为基准自动向上定位.Source/GTweak/Languages目录不需要手填路径。脚本干三件事先审计目录文件的键名再逐语言把键和分区与基准比对、输出差异报告[] Keys added/[-] Keys deleted最后按基准文件的结构重排目标文件把已有译文填回原位。三个开关对应三个阶段开关加上它会发生什么典型使用时机-DryRun只报告差异不写任何文件翻译初稿完成后第一遍排查-Backup写入前先存一份.bak副本正式同步的第二遍出错可回退-Placeholder缺失的键填入空占位符让翻译者接手时一眼看到待译清单建议的顺序:: 第一遍只看报告 Tools\LocalizeSync.cmd -DryRun :: 第二遍正式同步并保留备份 Tools\LocalizeSync.cmd -Backup差异报告出现 No changes 就代表文件已与基准对齐此时再确认键数 522、分区 16 个#region与英文基准一致可以放心提交。常见问题提交翻译 PR 前先回答这 4 个能在翻译文件里自造键吗不能。en 基准里没有的键脚本会当作「被删除的键」清掉。认为缺文案时先给基准文件提改动。只翻简体中文繁体能共享吗不能。zh-CN与zh-TW是两个独立文件夹目录里也各有zh_cn和zh_tw两行。地区匹配失败时程序退回「只有语言」但仓库没有单独的zh文件夹最终一路回落到英文。翻译没翻完留几条英文行不行可以。缺失条目显示英文是设计内的降级行为README 也明确允许这种过渡状态。怎么验证条数没差数一数任意Localize.xaml里x:Key的出现行数15 份文件都应是 522。或者直接信任同步脚本的 DryRun 报告No changes 即代表条数与分区双通过。【免费下载链接】GTweakPortable Tool for an Ideal Windows Setup项目地址: https://gitcode.com/GitHub_Trending/gt/GTweak创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考