翻译

Luna Flow 以 Blender 手册的方式翻译文档：英文页面是唯一的源，其他每种语言都是一个由已翻译消息组成的 gettext 翻译目录。构建站点时，中文或日文页面由英文页面和翻译目录生成。

这带来了三个结果：

任何语言的结构都不会与英文脱节。页面、标题、代码和链接都来自同一个源。
未翻译或过时的段落会以英文显示，而不会消失或出错。页面会说明其中已翻译的比例。
站点掌握每个页面和每个仓库的翻译覆盖率，并在文档库中显示。

消息

lunadoc 将每个页面拆分为消息：标题、段落、列表项、表格单元格，以及 front matter 中的 title 和 description 键。代码块、行间公式和原始 HTML 永远不是消息；它们在每种语言中都与英文原文完全相同。

跨越多行的段落是一条消息。重新折行英文文本不会改变其消息，因此不会使译文失效。

工作流程

在 doc/manual 中编辑英文页面。
运行 lunadoc update。它会重新生成 doc/locale/manual.pot，并将其合并到每个 manual.po 中。
将页面和翻译目录一起提交。

update 的行为与 GNU msgmerge 相同：

英文文本未改变的消息保留其译文。
英文文本发生变化的消息会采用最相似旧消息的译文，并被标记为 fuzzy。之前的英文文本保存在 #| msgid 注释中，以便译者查看改动。
消息已消失的译文会作为废弃条目（#~）保留在翻译目录末尾，update 之后可以从那里恢复它。

fuzzy 译文不会在站点上显示。在译者审阅并移除 fuzzy 标记之前，它们都算作未翻译。

进行翻译

在文本编辑器或 Poedit 等 gettext 编辑器中打开 doc/locale/<locale>/LC_MESSAGES/manual.po，为每个 msgid 填写 msgstr：

#: manual/core/api.md:12
msgid "The `Ring` trait models rings with $0$ and $1$."
msgstr "`Ring` trait 刻画带有 $0$ 与 $1$ 的环。"

翻译时：

行内代码、数学公式和链接目标必须与英文完全一致。链接文字需要翻译。
保留 Markdown 标记：强调、行内代码和链接必须保持配对完整。
将 GitHub 提示标记（例如 [!NOTE]）保留在消息开头。
不要翻译标识符，即使它们出现在正文中。
与其猜测，不如将 msgstr 留空。空消息会回退到英文。

使用 lunadoc status --pages 检查结果，并通过站点预览。

语言环境

语言环境名称遵循 gettext：zh_CN 表示简体中文，ja_JP 表示日语。它们出现在 conf.json、翻译目录路径以及站点的 config/locales.json 中，后者还为每个语言环境指定 URL 路径段和显示名称。为站点添加一种语言，就是在那里添加它；为仓库添加一种语言，就是在 conf.json 中列出它并运行 update。