我目前正在使用python-sphinx进行一个复杂的文档项目。我的下一步是实现国际化。
项目概述(简化(：
doc
build # contains sphinx build output
images # contains image resources
locales # gnu gettext structure (simplified)
enLC_MESSAGESindex.po+mo
enLC_MESSAGESarticlesconnect.po+mo
deLC_MESSAGESindex.po+mo
deLC_MESSAGESarticlesconnect.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" "buildgettext"
Makefile中更新本地化的规则：
update_po:
sphinx-intl update -p "buildgettext" -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，因为我想为每个文档提供单独的翻译文件。这使我们团队的工作流程更容易管理翻译和进度。
当使用命令make gettext生成*.pot文件时，我使用相同的配置。
现在，当我生成html/pdf输出时，只有顶层文档的文本域得到了正确处理，并且本地化字符串在生成的文档中被替换。此外，在加载翻译过程中也不会出现任何错误(正如您在上面的剪切中看到的那样(。文件的数量也与文档的数量相匹配——我认为在这里之前一切都很好。
我想知道这是否与windows使用与unix不同的路径分隔符有关？也许gettext找不到正确的文本域，因为"articles/connect" != "articlesconnect"。还是我只是错过了什么？我假设make update_po命令在LC_MESSAGES下生成gettext能够处理的有效文件/目录结构。这个假设正确吗？我还没有找到关于这个话题的任何信息。
感谢任何帮助和/或想法！
我找到了解决方案/原因。
我的第一个假设是，它可能与conf.py中的locale_dirs条目有关。我将包含sphinx构建本地化字符串的*.po文件的目录移动到sphinx-intl文档中推荐的位置。一切都没有改变。
当再次检查生成的*.po文件时，我注意到了一些奇怪的事情(我想(。一些消息ID包含在多个*.po文件中。事实证明，sphinx为目录结构中的每个*.rst文档或至少为文档层次结构中的每一个文档生成一个*.po文件。当一个文档通过include指令导入另一个文档时，包含文档的文本也被视为包含文档的一部分。而且，在为特定语言生成文档时，文本域也是以这种方式匹配的。这有点道理，因为include指令只是在当前文档中插入所包含文档的内容。。。
为了解决这个问题，必须在包含文档的*.po文件中翻译文本。实际文档的*.po文件中翻译的文本将被忽略。我认为这种行为适用于包括其他文档在内的整个递归文档堆栈，但尚未进行测试。
希望其他人觉得这个有用
我将接受这个答案作为正确答案。