Ghostty 本地化i18n指南基于 gettext 的贡献者翻译体系详解【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty导读本文是 Ghostty 开源终端模拟器面向本地化i18n贡献者的完整技术指南。文章将围绕 po/README_CONTRIBUTORS.md 展开说明 Ghostty 为何选择gettext作为统一本地化框架并深入讲解如何编写可翻译字符串、维护翻译模板与各语言.po文件、理解构建期编译为二进制.mo的全链路同时结合仓库源码src/os/i18n.zig、src/build/GhosttyI18n.zig 等解释底层实现原理。读完后你将具备为 Ghostty GTK/Linux 版新增或修正翻译、以及在源码与 Blueprint 界面中正确标记可翻译字符串的完整能力。一、为什么 Ghostty 选择 gettextGhostty 的本地化体系以gettext库/框架为核心原因是它具备一个独特优势可以被 Ghostty 两个主要的应用运行时macOS 与 GTK/Linux直接消费。gettext是 Linux/Unix 生态中的事实标准GTK 运行时可以无缝使用macOS 上亦可通过libintl编译产物接入同一套.mo消息文件。与此同时Ghostty 的架构刻意保持“核心core与本地化无关”并非所有libghostty的消费方都对本地化感兴趣例如把 libghostty 作为 VT 引擎嵌入自有产品的第三方因此本地化职责被下放到各个 apprt应用运行时实现者身上由他们决定是否以及如何接入本地化。从源码看这一职责边界非常清晰src/os/i18n.zig 中所有初始化逻辑都以if (comptime !build_config.i18n) return;作为编译期开关且注释明确指出initGlobalDomain“只应当被完整拥有 Ghostty 应用的 apprt 调用不应被 libghostty 的用户调用”——即只有当 apprt 完全拥有整个应用时才允许设置全局 text domain。需要澄清的一点是文档所称的“核心core”在本仓库中即指可嵌入的libghosttyVT/终端核心库本地化开关由构建配置i18n控制见 build.zig 中的if (config.i18n) try buildpkg.GhosttyI18n.init(...) else null。二、GTK 运行时可翻译字符串从哪来在 GTK apprt 中可翻译字符串主要有两个来源Blueprint.blp界面文件——主要来源Zig 源码文件——用于动态选择或需要格式化字符串的场景。2.1 Blueprint 原生语法Blueprint 界面文件集中存放于 src/apprt/gtk/ui 目录按 GTK/Adwaita 主版本号分目录如1.0、1.2、1.5。Blueprint 自带可翻译字符串的原生语法形式如下// Translators: This is the name of the button that opens the about dialog. title: _(About Ghostty);_是 gettext 世界的“标记该字符串待翻译”约定。在 Blueprint 中// Translators:注释用于给翻译者提供额外上下文——当字符串本身对“用途/出现位置”表述不清时这条注释会随字符串一并被提取到.po文件里参考 src/build/GhosttyI18n.zig 的--add-commentsTranslators参数。仓库中真实样例例如 src/apprt/gtk/ui/1.2/close-confirmation-dialog.blpresponses [ cancel: _(Cancel), close: _(Close) destructive, ]2.2 上下文与字符串合并规则gettext默认会把完全相同的字符串合并为同一条待翻译条目即同一个msgid对应一个msgstr。例如界面不同位置都出现_(Copy)它们会被合并成同一条。如果某条字符串在含义上需要区分比如菜单动作里的 “Copy” 与某对话框按钮上的 “Copy” 在不同语言中可能有不同译法就需要给字符串指定一个上下文context使用C_语法label: C_(menu action, Copy);C_的第一个参数是上下文标签第二个参数才是消息本身。加了上下文的字符串会在.pot/.po中生成带msgctxt的独立条目从而避免合并歧义。在提取阶段xgettext通过--keywordC_:1c,2识别这种两参数调用见 src/build/GhosttyI18n.zig含义是“第一个参数为上下文、第二个参数为待翻译消息”。2.3 从 Zig 源码标记字符串i18n._当字符串需要在运行时动态选择或需要额外格式化时就不能写在 Blueprint 里而要写在 Zig 源码中。注意在 Zig 中_不能作为裸标识符使用因此必须通过i18n命名空间前缀调用const i18n import(i18n.zig); const text if (awesome) i18n._(My awesome label :D) else i18n._(My not-so-awesome label :(); const label gtk.Label.new(text);这里的i18n._对应源码 src/os/i18n.zig 的实现pub fn _(msgid: [*:0]const u8) [*:0]const u8 { if (comptime !build_config.i18n) return msgid; if (inComptime()) return msgid; return dgettext(build_config.bundle_id, msgid); }即正常运行时调用dgettext(build_config.bundle_id, msgid)以 Ghostty 的 bundle idcom.mitchellh.ghostty作为 gettext domain 去查翻译表。提取范围的细节构建系统扫描的 Zig 范围是整个src/apprt/gtk目录下的.zig文件按文件名字典序排序以保证输出确定性外加专门用于命令面板本地化的 src/input/command.zig以及 nautilus 文件管理器集成脚本dist/linux/ghostty_nautilus.py以 Python 语言调用xgettext单独提取后再合并。详见 src/build/GhosttyI18n.zig。2.4 延迟翻译N_有些字符串必须先原样存储、等到展示给用户时才翻译。典型场景是编译期或静态元数据例如命令定义结构体里的标题。这时应使用i18n.N_N 代表 “No-op”只做标记、不做翻译const i18n import(i18n.zig); const Command struct { title: [:0]const u8, }; const cmd Command{ .title i18n.N_(Reset Terminal), }; const label gtk.Label.new(i18n._(cmd.title));N_仅把字符串标记进提取模板返回的仍是原始 msgid等到真正上屏时再调用一次_完成翻译。源码实现非常直观src/os/i18n.zigpub fn N_(msgid: [:0]const u8) [:0]const u8 { return msgid; }2.5 comptime 调用 _ 的特殊语义如果i18n._在comptime编译期被调用它同样返回原始 msgid 不做翻译但同时仍会把字符串标记为待翻译条目。这一点有专门的单元测试兜底src/os/i18n.zigtest _ returns msgid at comptime { const testing std.testing; const msgid comptime _(Ghostty); try testing.expectEqualStrings(Ghostty, std.mem.span(msgid)); }设计原因翻译查表依赖运行时 locale编译期不可能完成真实翻译但字符串出现在源码中就必须被xgettext提取否则翻译者看不到它。因此字符串在编译期需要被“读取”的场合如确定数组长度、构造静态结构用_字符串被“存储待用、稍后翻译”的场合更推荐语义清晰的N_。三、翻译模板.pot与 .po 文件的同步机制3.1 pot 模板同步的基石所有可翻译字符串都会被提取进翻译模板文件po/com.mitchellh.ghostty.pot。Ghostty 团队对这一文件有严格要求该文件必须始终与源码或 Blueprint 中的可翻译字符串列表保持同步。为此每个 PR 都会触发一条CI 检查验证翻译模板是否需要更新若源码里新增/删除了带_、N_、C_的字符串而模板未同步CI 即会失败。3.2 更新命令zig build update-translations贡献者本地可用一条命令完成同步zig build update-translations该命令会用xgettext重新提取所有字符串Blueprint GTK Zig 源码 命令面板command.zig nautilus Python 脚本生成中间.pot合并两个中间 potPython 产物优先因xgettext对字符集处理有依赖见 src/build/GhosttyI18n.zig并更新根模板 po/com.mitchellh.ghostty.pot对每个 locale用msgmerge --quiet --no-fuzzy-matching同步对应 po/*.po把新条目并入、标记过时条目使所有语言文件与模板保持一致。构建系统侧的定义见 build.zig 与 build.zigupdate-translationsstep 依赖GhosttyI18n.update_step当i18n构建配置被禁用时该命令会直接报错 “cannot update translations when i18n is disabled”。维护者手册 HACKING.md 也收录了这条命令的用途说明。实用提示为了让每次 PR 的模板 diff 尽量小Ghostty 对 Blueprint 文件名、GTK Zig 文件都做了确定性排序后再交给xgettext见 src/build/GhosttyI18n.zig并且传给xgettext的一律是相对构建根的路径而非绝对路径避免因开发者检出路径不同造成海量 diff 噪音。3.3 语言文件与多语言现状各语言的翻译存放于 po 目录命名格式为locale.po例如zh_CN.po、ja.po、de.po、fr.po、zh_TW.po等。文件头部是标准 gettext 元信息如 po/zh_CN.po# Chinese translations for com.mitchellh.ghostty package # com.mitchellh.ghostty 软件包的简体中文翻译. # Copyright (C) 2025 Mitchell Hashimoto, Ghostty contributors ... Project-Id-Version: com.mitchellh.ghostty\n Language: zh_CN\n Plural-Forms: nplurals1; plural0;\n条目中还保留了每个字符串的来源引用例如#: src/apprt/gtk/ui/1.0/clipboard-confirmation-dialog.blp:12方便翻译者对照上下文。Ghostty 所支持 locale 的完整清单由 src/os/i18n_locales.zig 维护构建期与运行时 libghostty API 共用。该清单注释还说明了两个细节顺序即优先级当系统只有语言码、缺少更细粒度信息时按顺序取首个匹配如用户只请求zh且无脚本码时取列表中最靠前的zh_CN排序偏好最常用 locale 在前减少线性查找的迭代次数同档则按字母序。因此新增一种语言翻译时需要同时更新po/locale.po与i18n_locales.zig中的清单。四、构建期从 .po 编译到 .mo在构建过程中每个 locale 的.po文件都会被编译为二进制.mo消息文件安装路径为share/locale/LOCALE/LC_MESSAGES/com.mitchellh.ghostty.mo这一过程由 src/build/GhosttyI18n.zig 实现构建系统对清单中的每个 locale 执行系统命令msgfmt -o - po/locale.po并把msgfmt的 stdout 安装为share/locale/locale/LC_MESSAGES/com.mitchellh.ghostty.mo。这里同样有平台细节在 FreeBSD 上LC_MESSAGES 路径不含编码后缀因此会先把 locale 字符串末尾的.UTF-8去掉再作为目标目录名src/build/GhosttyI18n.zig。编译出的.mo文件可被libintl直接读取。libintl提供了各种gettext的 C 函数这些函数有两种调用途径由 Zig 代码直接调用经 src/os/i18n.zig 封装的extern fn dgettext/bindtextdomain/textdomain由 GTK builder 调用推荐方式——即让 GTK 界面在运行时根据 locale 自动替换 Blueprint 中以_()标注的字符串。4.1 运行时的 domain 绑定编译期编译.mo只是“备好弹药”运行时还需要把 gettext domain 指向正确的翻译目录。这部分逻辑集中在 src/os/i18n.zig 的init由资源目录推导出share目录资源目录恒位于 share 之下拼接出share/locale路径调用bindtextdomain(com.mitchellh.ghostty, locale_path)完成绑定。代码注释特意强调只调用bindtextdomain、不调用textdomain因为全局 text domain 会影响同样链接了 libghostty 的宿主应用只有完全拥有应用的 apprt如 GTK 主程序才应通过initGlobalDomain设置全局 domainsrc/os/i18n.zig。初始化会被global.zig的全局状态初始化自动触发。4.2 libintl 依赖说明对绝大多数用户而言无需额外安装任何库即可获得本地化能力——libintl是 GNU C 标准库glibc的组成部分。例外情况是使用替代 C 标准库如musl的用户。由于 musl 不含 GNU libintl这些用户必须使用提供翻译函数 no-op 符号的桩实现例如gettext-tiny或使用一套能正常工作的libintl构建。这一限制对发行版打包者尤其重要。[!NOTE] 从构建源码看Ghostty 在 musl 场景的兼容性设计不止于文档说明Zig 侧通过手写extern fn声明bindtextdomain/textdomain/dgettext的方式规避了libintl.h头文件在 musl 等环境下不易获取的问题src/os/i18n.zig 的注释明确写道 “libintl.h isnt always easily available (e.g. in musl)”。五、locale 名称规范化不同平台上报的 locale 命名风格差异很大macOS 使用形如zh-Hans-CN的 BCP-47 风格POSIX 生态则期望zh_CN。为统一查询src/os/i18n.zig 提供canonicalizeLocale内部调用 gnulib 的_libintl_locale_name_canonicalize完成规范化并做了额外的边界保护与错误处理原 gnulib 函数原地修改缓冲区且无边界检查。源码中还单独实现了fixZhLocalesrc/os/i18n.zig因为内部 canonicalize 函数无法正确处理中文 locale 的映射例如输入输出zh-Hanszh_CNzh-Hans-SGzh_SGzh-Hantzh_TWzh-Hant-HKzh_HKzh-Hant-MOzh_MOsrc/os/i18n.zig 中的canonicalizeLocale darwin测试覆盖了上述映射并提示了一个边界情况该函数不处理字符编码后缀en_US.UTF-8会被转成en_US.UTF_8调用方应先剥离编码信息。另外当存在编译期已知的 locale 且想校验其受支持时可用staticLocale——若 locale 不在支持清单中会直接在编译期抛compileError(unsupported locale)src/os/i18n.zig。六、macOS 现状与整体边界需要特别说明的是macOS 上的本地化系统目前尚未实现即本文上述 GTK 管线现阶段仅适用于 Linux/GTK apprt。文档原文对此的表述是[!NOTE] The localization system is not yet implemented for macOS.若希望推进 macOS 本地化从仓库结构看可关注两块基础储备pkg/libintl相关构建产物_libintl_locale_name_canonicalize仅当从源码构建 libintl 时才可用注释表明目前主要在 macOS 需要src/os/i18n.zig以及canonicalizeLocale中针对 macOS locale 命名的转换逻辑。但请注意这些只是基础设施不代表 macOS 端本地化已经可用。七、给贡献者的快速上手清单综合 po/README_CONTRIBUTORS.md 与源码实现为 Ghostty 做本地化工作的标准流程可归纳为定位字符串来源需要改写的界面字符串可能在 Blueprint 文件src/apprt/gtk/ui 下的.blp或 GTK 相关 Zig 源码含 src/input/command.zig 命令面板中标记字符串静态界面字符串在 Blueprint 中用_(...)需要歧义区分时加C_(context, ...)并配// Translators:注释Zig 源码中用i18n._需延迟翻译用i18n.N_同步模板与语言文件运行zig build update-translations刷新 po/com.mitchellh.ghostty.pot 并合并到各 po/*.po提交 PR 时确保该命令产物干净以免触发 CI 的模板同步检查翻译 .po 文件在对应的po/locale.po中填写/修订msgstr本地验证构建产物会经msgfmt生成share/locale/LOCALE/LC_MESSAGES/com.mitchellh.ghostty.mo以对应 locale 启动 GhosttyGTK即可检查界面效果留意平台差异若涉及 locale 名称处理尤其 macOS/BSD 风格命名注意 src/os/i18n_locales.zig 的支持清单与canonicalizeLocale的行为边界。参考资料索引翻译贡献者官方指南po/README_CONTRIBUTORS.md翻译模板po/com.mitchellh.ghostty.pot简体中文翻译po/zh_CN.po运行时实现domain 绑定、_/N_、locale 规范化src/os/i18n.zig支持的 locale 清单src/os/i18n_locales.zig构建/提取/合并/安装实现src/build/GhosttyI18n.zig构建步骤注册build.zig、build.zig开发者命令手册HACKING.mdBlueprint 界面源目录src/apprt/gtk/ui可翻译字符串主要来源含真实_()用法示例维护者手册中对本指南的交叉引用po/README_CONTRIBUTORS.md见 HACKING.md【免费下载链接】ghostty Ghostty is a fast, feature-rich, and cross-platform terminal emulator that uses platform-native UI and GPU acceleration.项目地址: https://gitcode.com/GitHub_Trending/gh/ghostty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
