gettext_compact=False 时，sphinx gettext 与子目录中的文本域不匹配

Question

我目前正在使用 python sphinx 进行一个复杂的文档项目。我的下一步是启用国际化。

项目概览（简体）：

doc\
  build\     # contains sphinx build output
  images\    # contains image resources
  locales\   # gnu gettext structure (simplified)
    en\LC_MESSAGES\index.po+mo
    en\LC_MESSAGES\articles\connect.po+mo
    de\LC_MESSAGES\index.po+mo
    de\LC_MESSAGES\articles\connect.po+mo
  source\
    _static\
    articles\
      connect.rst
      commission.rst
    troubleshoot\
      bugs.rst
    reference\
      generated.rst
    about.rst
    conf.py  # contains sphinx configuration
    index.rst
    terminology.rst
  Makefile
Workbench\  # contains work contained in generated reference

conf.py 中的本地化选项：

locale_dirs = [
    '../locales/'
]
gettext_compact = False

Makefile 中的规则以创建 html 输出

html:
    sphinx-build -M html "source" "build" -Dlanguage="de" -v

Makefile 中的规则创建 *.pot 文件：

gettext:
    sphinx-build -b gettext "source" "build\gettext"

Makefile 中的规则更新本地化：

update_po:
    sphinx-intl update -p "build\gettext" -Dlanguage="en" -Dlanguage="de"

您可能已经从目录结构和路径定界符中看出：我正在使用 Windows 10.

从包含本地化输出

的 make html 的构建输出中截取

Running Sphinx v4.2.0
loading translations [de]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 15 changed, 0 removed

我的问题如下：

Sphinx 不匹配 LC_MESSAGES.

的子目录中包含的文本域中的本地化字符串

我用 gettext_compact=False 配置了 sphinx gettext，因为我想为每个文档准备单独的翻译文件。这使我们团队的工作流程更容易管理翻译和进度。

使用命令生成 *.pot 文件时 make gettext 我使用相同的配置。

现在，当我生成 html/pdf 输出时，只有顶层文档文本域会得到正确处理，本地化字符串会在生成的文档中被替换。在翻译的加载过程中也不会抛出任何错误（如您在上面的截图中所见）。文件的数量也与文档的数量相匹配 - 我假设直到这里一切正常。

我想知道这是否与 windows 使用不同于 unix 的路径分隔符有关？也许 gettext 找不到正确的文本域，因为 "articles/connect" != "articles\connect"。或者我只是错过了什么？我假设 make update_po 命令在 LC_MESSAGES 下生成一个 gettext 能够处理的有效 file/directory 结构。这个假设是否正确？我还没有找到关于这个主题的任何信息。

任何帮助 and/or 想法表示赞赏！

Answer 1

我找到了solution/cause。

我的第一个假设是它可能与 conf.py 中的 locale_dirs 条目有关。我将包含 sphinx-build 个本地化字符串的 *.po 个文件的目录移动到 sphinx-intl docs 中推荐的位置。没有任何变化。

再次检查生成的 *.po 文件时，我发现有些奇怪（我猜）。一些 msgid 包含在多个 *.po 文件中。事实证明，sphinx 为目录结构中的每个 *.rst 文档或至少为文档层次结构中的每个文档生成一个 *.po 文件。当一个文档通过 include 指令导入另一个文档时，包含文档的文本也被视为包含文档的一部分。在为特定语言生成文档时，文本域也会以这种方式匹配。这有点道理，因为 include 指令只是将包含文档的内容插入到当前文档中...

要解决此问题，必须在包含文档的 *.po 文件中翻译文本。在实际文档的 *.po 文件中翻译的文本将被忽略。我认为这种行为适用于包括其他文档在内的整个文档递归堆栈，但尚未测试。

希望其他人觉得这有用。
我将接受此答案作为正确答案。

gettext_compact=False 时，sphinx gettext 与子目录中的文本域不匹配

sphinx gettext does not match textdomains in subdirectories when gettext_compact=False

python

windows

gettext

internationalization

python-sphinx