Guidedog / 文档 0.2.0

国际化¶

翻译解释，保留结构。Guidedog 提取消息清单、合并译文，并按选定语言构建。源文本始终是参照，缺失的译文回退到源文，不凭空编造。

工作流程¶

使用 gettext 构建器生成消息模板：
```
guidedog build gettext
```
它在 _build/gettext 中为每个文本域生成一个模板（.pot）。文档中的段落、标题、列表项、表格单元格、题注、提示框、术语和字段都会成为消息，并记录所在文件和行号。
像 sphinx-intl update 一样，为各语言创建或更新清单：
```
guidedog intl update -l de -l fr
```
目录文件位于 locales/de/LC_MESSAGES/*.po。再次运行时，命令会像 msgmerge 一样合并新模板：保留已有译文；源文改变时，将旧译文标为 fuzzy，供复核；已删除的消息作为废弃条目（#~）保留在末尾，以便日后恢复。
填写每个 msgstr。确认译文正确后，删除该消息的 #, fuzzy 行；构建时不会使用模糊译文。
```
msgid "Hello *world*, see the site_."
msgstr "Hallo *Welt*, siehe site_."
```
像 sphinx-intl stat 一样查看翻译进度：
```
guidedog intl stat -l de
```
按目标语言构建：
```
guidedog build html -D language=de
guidedog build pdf -D language=de
```
也可在 conf.toml 中设置 language = "de"。

每本书都有语言后缀：manual.pdf 会变为 manual-de.pdf。一次构建发布一个完整版本，因此保留多语言版本时应使用不同目标目录。例如，德文用 guidedog build -b pdf docs build/books/de -D language=de，英文用 guidedog build -b pdf docs build/books/en -D language=en。

与文档的其他输入相同，只有清单变化的文档才会重读；添加或删除清单时会重读所有文档。

guidedog intl 支持 sphinx-intl 的选项：-p DIR 指定模板目录（默认 _build/gettext）；-l LANG 指定语言，可重复使用（默认为项目语言）；-d DIR 指定目录文件位置（默认取 locale_dirs 的第一项）；-w N 指定行宽（默认 76）；还支持 --no-obsolete。

编写翻译¶

消息是段落、标题或其他元素的源文本，包含标记语法。.rst 文档使用 reStructuredText，.md 文档使用 Markdown。译文按同种语法读取，因此可保留原文的强调、链接和引用。

引用必须保持一致。译文保留消息中的每个引用及其写法，只改动周围文字和显示标题：

msgid "See :ref:`install` and the site_."
msgstr "Siehe :ref:`Installation <install>` und die site_."

译文缺少引用时，构建会像 Sphinx 一样发出警告（inconsistent references in translated message），但仍采用译文。若译文引用了原文没有的目标，该引用无法解析，构建会警告并保留原文。若读取器拒绝译文标记，也会保留原文，并在警告中列出该译文。

章节锚点不随语言变化。翻译后的标题保留原文锚点，因此站点内部和外部的链接仍然有效。

设置¶

标准设置沿用 Sphinx 的名称和默认值。Guidedog 还提供仅用于提取的排除项，可让参考附录保持原文。

设置项	含义
`language`	构建语言，例如 `"de"` 或 `"pt_BR"`。
`locale_dirs`	相对于源目录的目录文件位置。每处包含 `LANGUAGE/LC_MESSAGES/DOMAIN.po`（或编译后的 `.mo`）。默认是 `["locales"]`。指定多处时，采用第一个能翻译该消息的目录。
`gettext_compact`	决定文档消息所属的目录文件。`true`（默认）：顶层文档各用一个目录文件，同一文件夹内的文档共用一个（`guide/usage.rst` 使用 `guide.po`）。`false`：每个文档一个。指定名称：所有文档共用该名称的目录文件。
`gettext_location`	写入消息位置（`#: ../../index.rst:12`），默认为 `true`。
`gettext_uuid`	为消息的每次出现写入标识符。Guidedog 根据文档、消息及出现位置生成，因此每次构建结果相同。
`gettext_auto_build`	将每个 `.po` 编译为旁边的 `.mo`，供其他工具使用，默认为 `true`。Guidedog 自身读取 `.po`。
`gettext_additional_targets`	额外翻译内容：`index`（索引项）、`literal-block`、`doctest-block`、`raw` 和 `image`（替代文本）。
`gettext_allow_fuzzy_translations`	也使用模糊译文，默认为 `false`。
`gettext_exclude_patterns`	仅从 POT 提取中排除的文档路径模式，如 `["api/**"]`。默认为 `[]`。文档仍保留在 HTML 和 PDF 中。
`gettext_last_translator`, `gettext_language_team`	模板头部的 `Last-Translator` 和 `Language-Team`。
`figure_language_filename`	构建语言对应的图片文件。默认 `"{root}.{language}{ext}"`：若 `language = "de"`，且文件存在，`img/logo.png` 会改用 `img/logo.de.png`。可用字段为 `{root}`、`{path}`、`{basename}`、`{ext}`、`{docpath}` 和 `{language}`。
`translation_progress_classes`	给已翻译元素添加 `translated` 类，其他元素添加 `untranslated` 类（`true`）；也可只添加其中一种（`"translated"` 或 `"untranslated"`），以便用样式表显示翻译进度。

Guidedog 的界面用语¶

Guidedog 自身也生成文字：提示框标题、“Added in version 2.1”、“Fig. 1”、“Contents”，页面布局中的“Previous”、“Next”、“Navigation”和“Search”，搜索页和索引页，以及书籍中的“Version”。这些来自 guidedog 文本域，按以下顺序查找：

项目的 locales/LANGUAGE/LC_MESSAGES/guidedog.po。
项目的 locales/LANGUAGE/LC_MESSAGES/sphinx.po，与 Sphinx 一致。
Guidedog 内置的清单，支持德语、西班牙语、法语、日语、巴西葡萄牙语、俄语及简体中文。

消息标识符使用英文；Sphinx 有对应文字时，采用相同标识符，因此项目现有的 sphinx.po 仍可使用。项目自己的 guidedog.po 可以覆盖任意文字，或增加一种语言。

模板与 Sphinx 一样使用 _()、gettext() 和 ngettext() 翻译：

<small>{{ _('Previous') }}</small>
{{ _('Last updated on %s.')|format(last_updated) }}

除非在 conf.toml 中明确设置，numfig_format、html_title 和 html_short_title 会跟随语言。

日期¶

|today|、书籍日期和页面的 last_updated 采用 Sphinx 的格式规则：today_fmt 和 html_last_updated_fmt 使用 strftime 格式，月份和星期名称遵循 language。例如 %b %d, %Y 在英文中是“Sep 29, 2026”，在德文中是“Sept. 29, 2026”。空格式取 _('%b %d, %Y')，可由目录文件翻译。上述语言的名称来自 Unicode CLDR；其他语言使用英文，与 Sphinx 遇到 Babel 不支持的语言时相同。

日期取本地时区的本地日期。设置 SOURCE_DATE_EPOCH（自 1970 年起的 UTC 秒数），可实现可重复构建，使各机器使用相同日期。