当 gettext_compact=False 时，sphinx gettext 与子目录中的文本域不匹配
我目前正在使用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中的规则在makefile中创建HTML输出
html:
sphinx-build -M html "source" "build" -Dlanguage="de" -v
规则，以创建 *.pot文件：
gettext:
sphinx-build -b gettext "source" "build\gettext"
in makefile以更新本地化：
update_po:
sphinx-intl update -p "build\gettext" -Dlanguage="en" -Dlanguage="de"
您可能已经可以从目录结构和路径定界符中分辨出来：我使用的是Windows 10
。本地化输出
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输出时，仅处理topLevel文档文本域，然后在结果文档中替换本地化字符串。 同样，在翻译加载过程中也没有抛出任何错误（如上上面的切口所示）。文件数也与文档数量匹配 - 我假设在这里一切正常。
我想知道这是否与使用与Unix不同的路径分离器有关的Windows有关系吗？也许getText找不到正确的文本域，因为“ articles/connect”！=“ articles \ connect”。 还是我只是错过了什么？我假设make update_po命令在getText可以处理的lc_messages下产生有效的文件/目录结构。这个假设正确吗？我还没有找到有关此主题的任何信息。
任何帮助和/或想法都感谢！
I'm currently working on a complex documentation project with python sphinx.
My next step is to enable internationalization.
Project overview (simplified):
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
Localization options in conf.py:
locale_dirs = [
'../locales/'
]
gettext_compact = False
Rule in Makefile to create html output
html:
sphinx-build -M html "source" "build" -Dlanguage="de" -v
Rule in Makefile to create *.pot files:
gettext:
sphinx-build -b gettext "source" "build\gettext"
Rule in Makefile to update localizations:
update_po:
sphinx-intl update -p "build\gettext" -Dlanguage="en" -Dlanguage="de"
As you may already can tell from the directory structure and path delimiter: I am using Windows 10.
Cutout from build output for make html containing localization output
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
My problem is the following:
Sphinx does not match localized strings in textdomains that are contained in a subdirectory of LC_MESSAGES.
I've configured sphinx gettext with gettext_compact=False because I want to have separate translation files for each document.
This makes it easier for our team's workflow to manage translations and progress.
When generating *.pot files using command make gettext I'm using the same configuration.
Now when I generate html/pdf output only the toplevel documents textdomains are processed correctly and localized strings are substituted in the resulting document.
Also no errors are thrown during loading of the translations (as you can see in the cutout above). The number of files also matches the number of documents - I assume until here everything works fine.
I am wondering if this has something to do with windows using a different path seperator than unix? Maybe gettext doesn't find the correct textdomain because "articles/connect" != "articles\connect".
Or am I just missing something? I assumed that the make update_po command produces a valid file/directory structure under LC_MESSAGES that gettext is able to process. Is this assumption correct? I haven't found any information on this topic, yet.
Any help and/or ideas appreciated!
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
我找到了解决方案/原因。
我的第一个假设是它可能与
conf.py中的locale_dirs条目有关。我将包含 sphinx-build 本地化字符串的
*.po文件的目录移动到sphinx-intl文档。一切都没有改变。
当再次检查生成的 *.po 文件时，我注意到一些奇怪的东西（我猜）。
一些 msgid 包含在多个
*.po文件中。事实证明，sphinx 为目录结构中的每个
*.rst文档或至少为文档层次结构中的每个文档生成一个*.po文件。当一个文档通过
include指令导入另一个文档时，所包含文档的文本也被视为包含文档的一部分。当生成特定语言的文档时，文本域也会以这种方式匹配。
这有点有意义，因为
include指令只是将包含文档的内容插入到当前文档中...要解决此问题，必须在
*.po 包含文档的文件。实际文档的*.po文件中翻译的文本将被忽略。我认为这种行为适用于包括其他文档在内的整个递归文档堆栈，但尚未测试。
希望其他人发现这很有用。
我将接受这个答案作为正确答案。
I have found the solution/cause.
My first assumption was that it might have to do with the
locale_dirsentry inconf.py.I moved the directory with
*.pofiles containing sphinx-build localized strings to the location recommended insphinx-intldocs.Nothing changed.
When again inspecting the generated
*.pofiles I noticed something weird (I guess).Some msgid's were contained in multiple
*.pofiles.It turned out that sphinx generates a
*.pofile for each*.rstdocument in the directory structure or at least for each document that is part of the document hierarchy.When one document imports another via the
includedirective the texts of the included document are also treated as part of the including document.And also the textdomain is matched that way when generating the documentation for a specific language.
This kinda makes sense because the
includedirective just inserts the contents of the included document in the current document...To work around this, texts have to be translated in the
*.pofile of the including document. Texts translated in the*.pofile of the actual document are ignored.I think this behavior applies to the whole recursive stack of documents inluding other documents, but havent tested yet.
Hope someone else finds this useful.
I'm going to accept this answer as the correct answer.