1. 为什么我要给 Codex 桌面端做汉化Codex 桌面端这东西刚上手的时候确实挺唬人——功能强、界面干净、响应快但满屏的英文菜单对不少国内开发者来说还是有点膈应。尤其是团队里刚入行的同学看到 “Settings” 里那一堆 “Advanced Configuration”、“Proxy Override”、“Model Provider” 之类的选项第一反应往往是“这都啥跟啥”。我最初也只是想给自己省点事后来发现身边问的人越来越多干脆把整个汉化流程整理出来顺便把踩过的坑一并记下。这篇文章要聊的就是Codex 桌面端从菜单到主界面的完整汉化思路。核心手段是围绕i18n 资源文件和ASAR 包解包重打包两条线展开前者负责把界面上的英文文案替换成中文后者负责把改好的资源塞回应用里。整个过程不需要重新编译源码也不需要动核心逻辑属于“外科手术式”的轻量改造。适合有一定动手能力、想自己定制桌面端界面的开发者也适合想了解 Electron 类应用汉化通用套路的同学。需要提前说明的是我做的汉化只针对界面文案层面不涉及任何功能修改、不绕过任何校验、不触碰账号体系。所有操作都在本地完成改坏了直接重装就行风险可控。2. 汉化前的整体思路与方案选型2.1 先搞清楚 Codex 桌面端的结构Codex 桌面端本质上是基于 Electron 打包的跨平台应用。Electron 应用的典型结构是这样的主进程代码、渲染进程代码、静态资源、以及一个叫app.asar的归档文件。app.asar相当于把整个app目录打成了一个包Electron 启动时会优先读取这个包里的内容。换句话说你想改的任何界面文案最终都要落到这个 asar 包里。那界面文案藏在哪一般有两个位置一是渲染进程的 JS bundle 里字符串直接硬编码在代码中二是独立的 i18n 资源文件比如en.json、en-US.json这类。Codex 桌面端属于后者做得比较规范的那一类它有一套自己的 locale 目录里面按语言分文件存放文案。这就给了我们一个很舒服的切入点——不用去啃压缩后的 JS直接改 JSON 就行。2.2 为什么选 ASAR 解包而不是直接改安装目录有人可能会问既然安装目录里能看到文件为什么不直接改原因很简单Electron 加载的是app.asar这个归档文件而不是散落的源文件。你改了解压出来的目录应用启动时根本不读。所以必须走“解包 → 修改 → 重打包”这条路。具体工具有两个选择asar命令行工具和electron/asar。前者是老牌工具安装简单后者是官方维护的新版本兼容性更好。我实测下来electron/asar在处理大文件时更稳尤其是 Codex 这种包体积不小的应用用新版能避免一些内存溢出的问题。2.3 汉化的边界在哪里这里必须划一条线只改文案不改逻辑。具体来说以下几类内容不要动任何看起来像 API 路径、配置键名的字符串比如model_provider、endpoint这些改了会导致功能异常。任何带占位符的模板字符串比如{count} items你只能改items对应的中文不能动{count}本身。任何错误码、状态码相关的英文比如ERR_TIMEOUT这些是程序内部判断用的改了会出问题。我一般会在改之前先把整个 locale 文件备份一份改完对比 diff确认只动了展示层文案。3. 核心细节解析与实操要点3.1 定位 i18n 资源文件第一步是找到 locale 文件在哪。解包app.asar之后通常在以下几个路径之一app/resources/locales/app/dist/locales/app/out/renderer/locales/Codex 桌面端我实测是在app/resources/locales/下面文件名类似en.json、en-US.json。打开之后你会看到结构很清晰大概是这样的{ menu: { file: File, edit: Edit, view: View }, settings: { title: Settings, general: General, advanced: Advanced } }这种扁平化的 key-value 结构对汉化非常友好你只需要把 value 换成中文key 保持不动即可。3.2 汉化菜单栏的关键点菜单栏是最先被注意到的部分也是最容易出问题的地方。Codex 桌面端的菜单分两层一层是应用级菜单File、Edit、View 这些另一层是右键上下文菜单。前者在 locale 文件里能找到对应条目后者有时候是硬编码在 JS 里的。我的做法是先在 locale 文件里把所有能匹配到的菜单项改掉然后启动应用看哪些还是英文。剩下的英文项再去 JS bundle 里搜。搜的时候有个技巧——用菜单项的英文原文作为关键词比如搜Open Folder一般能定位到硬编码位置。定位到之后把字符串替换成中文注意保留引号和逗号别把语法搞坏了。3.3 主界面文案的批量替换策略主界面文案量大手动一条条改效率太低。我的策略是分三步走导出所有 value用脚本把 locale 文件里所有 value 提取出来生成一个待翻译列表。批量翻译借助翻译工具或者自己逐条过生成中文对照表。回写 JSON用脚本把中文对照表按 key 回写到原 JSON 文件里。这样做的好处是翻译和替换解耦翻译错了可以单独修不用重新解包。我写了一个简单的 Python 脚本干这事核心逻辑就是json.load→ 遍历 →json.dump几十行代码搞定。注意回写 JSON 时一定要指定ensure_asciiFalse否则中文会变成\uXXXX转义序列虽然功能上没问题但可读性极差后续维护很痛苦。3.4 重打包时的参数选择改完文件之后重打包这一步有几个参数值得注意npx electron/asar pack app app.asar --unpack-dir **/{node_modules,.cache}--unpack-dir这个参数很关键。Codex 桌面端里有些原生模块比如.node文件是不能被打进 asar 的必须解压到外面。如果你不加这个参数打包出来的应用启动时会报 “Cannot find module” 之类的错误。具体哪些目录需要 unpack可以看原包里有没有.unpacked后缀的目录有的话就照着加。另外打包顺序也有讲究先备份原 asar再打包到临时文件确认无误后再替换。我见过有人直接覆盖原文件结果打包失败原包也没了只能重装。4. 实操过程与核心环节实现4.1 环境准备与工具安装先确认本地有 Node.js 环境版本建议 18 以上。然后安装 asar 工具npm install -g electron/asar如果你不想全局安装也可以用npx electron/asar直接调用。我习惯全局装省得每次敲一长串。接着找到 Codex 桌面端的安装目录。Windows 一般在C:\Users\你的用户名\AppData\Local\Programs\Codex\resources\macOS 在/Applications/Codex.app/Contents/Resources/。目录里能看到app.asar这个文件就是我们的目标。4.2 解包与文件定位在 resources 目录下执行asar extract app.asar app-extracted解包完成后进入app-extracted目录用文件管理器或者find命令找 locale 文件find . -name *.json | grep -i locale找到之后先复制一份备份cp en.json en.json.bak这一步千万别省后面改错了直接还原比重装应用快得多。4.3 文案替换的实操记录我拿菜单栏的 “File” 举例。在en.json里找到menu.file: File改成menu.file: 文件改的时候注意有些 key 是嵌套结构比如menu: { file: File }这种就要改成menu: { file: 文件 }别把嵌套层级搞乱了否则应用读取时会报 JSON 解析错误。主界面文案我大概改了 400 多条耗时一个多小时。其中有一批是重复出现的比如 “Cancel”、“Confirm”、“Save”这些在多个模块里都有我统一翻译成“取消”、“确认”、“保存”保持一致性。4.4 重打包与验证改完之后回到 resources 目录执行打包asar pack app-extracted app-new.asar --unpack-dir **/{node_modules,.cache}打包完成后先别急着替换用asar list app-new.asar看一下文件列表确认关键文件都在。然后备份原包mv app.asar app.asar.original mv app-new.asar app.asar启动 Codex 桌面端检查菜单栏和主界面。如果发现某些地方还是英文说明那部分文案不在 locale 文件里需要回到 JS bundle 里继续找。提示如果启动后白屏或者报错大概率是打包时漏了 unpack 目录或者 JSON 格式有问题。这时候把app.asar.original改回app.asar重新来一遍就行。5. 常见问题与排查技巧实录5.1 启动报错 “Cannot find module”这是最常见的问题九成是 unpack 目录没配对。解决办法是打开原版app.asar的.unpacked目录看看里面有哪些文件夹然后在打包命令里把这些目录都加到--unpack-dir参数里。Codex 桌面端一般需要 unpack 的是node_modules和.cache但不同版本可能不一样以实际为准。5.2 界面文案改了但没生效有两种可能一是改的文件不是应用实际加载的那个比如你改了en.json但应用读的是en-US.json二是应用有缓存需要清一下缓存目录再启动。排查方法是看应用启动日志里面会打印加载的 locale 文件路径。5.3 中文显示乱码这通常是编码问题。确保你的 JSON 文件保存为 UTF-8 无 BOM 格式。如果用记事本改的很容易带上 BOM导致应用解析失败。建议用 VS Code 或者 Sublime Text 改保存时选 UTF-8。5.4 部分菜单项找不到对应 key有些菜单项是动态生成的比如最近打开的文件列表这类文案通常不在 locale 文件里而是在 JS 代码里拼接的。遇到这种情况只能去 JS bundle 里搜英文原文找到后手动替换。替换时注意不要破坏模板字符串的结构。5.5 汉化后应用更新导致失效Codex 桌面端更新时会覆盖app.asar你的汉化就没了。解决办法有两个一是每次更新后重新走一遍流程二是把汉化脚本化更新后一键执行。我后来写了个 shell 脚本把解包、替换、打包、替换原包这几步串起来更新后跑一下就行省事很多。问题现象可能原因解决办法启动报错 Cannot find moduleunpack 目录缺失对照原包 .unpacked 目录补全参数文案改了没生效文件不对或缓存未清确认加载路径清理缓存中文乱码编码格式不对保存为 UTF-8 无 BOM菜单项找不到 key文案硬编码在 JS 里去 JS bundle 搜索替换更新后汉化失效asar 被覆盖脚本化流程更新后重跑5.6 一个容易被忽略的细节Codex 桌面端的某些界面文案是从服务端下发的比如模型名称、状态提示。这类文案不在本地 locale 文件里汉化不了也不建议汉化因为改了可能影响功能判断。我的原则是本地能改的改服务端下发的别碰。6. 汉化后的维护与扩展思路汉化做完不是终点后续维护才是真正花时间的地方。我的做法是建一个独立的 Git 仓库把 locale 文件、替换脚本、打包脚本都放进去。每次 Codex 更新后先拉取新版 asar解包用diff对比新旧 locale 文件看看新增了哪些 key只翻译新增部分然后重新打包。这样每次维护成本能控制在十分钟以内。另外如果你想让汉化更彻底可以考虑做一个“翻译映射表”把常见的英文术语和对应的中文固定下来比如 “Provider” 统一译成“提供方”“Endpoint” 统一译成“端点”。这样多人协作时不会出现同一个词多种译法的情况。最后再分享一个小技巧改完 locale 文件后可以用jq工具校验 JSON 格式是否正确jq empty en.json echo JSON 格式正确这一步能提前发现语法错误避免打包后启动失败。我踩过好几次坑都是因为少了个逗号或者多了个括号用jq一验就出来了。