Skip to content

i18n: False positive build warnings of hyperlinks and term roles #14162

@mattwang44

Description

@mattwang44

Describe the bug

This is the successive issue of #14143, which has been addressed by #14144, but not all the false positive warnings are covered. We can still observe many correct translation are flagged on the python docs translation dashboard. Some python docs translation repos do not allow any build warning in their build workflows and hence being blocked by this issue.

How to Reproduce

The followings are all valid translation across different language version of the python docs but now induce build warnings:

Reordered hyperlink

Example from python-docs-zh-cn:

#: ../../about.rst:6
msgid ""
"Python's documentation is generated from `reStructuredText`_ sources using "
"`Sphinx`_, a documentation generator originally created for Python and now "
"maintained as an independent project."
msgstr ""
"Python 的文档是用 `Sphinx`_ 从 `reStructuredText`_ 源生成的,`Sphinx` 是一个专为处理 Python "
"文档而编写的文档生成器。"

# about.rst:6: WARNING: inconsistent references in translated message. original: ['`reStructuredText`_', '`Sphinx`_'], translated: ['`Sphinx`_', '`reStructuredText`_'] 

I suggest that we can ignore all sequence checking (make ignore_order=True the default behavior of compare_references(), see the previous discussion)

Add translated display text for hyperlink

Example from python-docs-ko:

#: ../../c-api/call.rst:353
msgid ""
"Call a callable Python object *callable*. The arguments are the same as "
"for :c:type:`vectorcallfunc`. If *callable* supports vectorcall_, this "
"directly calls the vectorcall function stored in *callable*."
msgstr ""
"콜러블 파이썬 객체 *callable*\\을 호출합니다. 인자는 :c:type:`vectorcallfunc` 와 같습니다. "
"*callable*\\이 `벡터콜 <vectorcall_>`_\\을 지원하면, *callable*\\에 저장된 벡터콜 함수를 직접 "
"호출합니다."

# c-api/call.rst:353: WARNING: inconsistent references in translated message. original: ['vectorcall_'], translated: ['`벡터콜 <vectorcall_>`_'] [i18n.inconsistent_references]

Translated the display text for hyperlink

Example from python-docs-it:

#: whatsnew/3.12.rst:103
msgid ""
"`Improved 'Did you mean ...' suggestions <improved error messages_>`_ for "
":exc:`NameError`, :exc:`ImportError`, and :exc:`SyntaxError` exceptions"
msgstr ""
"`Suggerimenti migliorati 'Intendevi dire ...' <improved error messages_>`_ "
"per eccezioni :exc:`NameError`, :exc:`ImportError`, e :exc:`SyntaxError`"

# whatsnew/3.12.rst:103: WARNING: inconsistent references in translated message. original: ["`Improved 'Did you mean ...' suggestions <improved error messages_>`_"], translated: ["`Suggerimenti migliorati 'Intendevi dire ...' <improved error messages_>`_"] [i18n.inconsistent_references]

Use translated hyperlink tag

Example from python-docs-ja:

#: ../../bugs.rst:37
msgid "`Documentation bugs`_"
msgstr "`ドキュメントのバグ`_"

# bugs.rst:37: WARNING: inconsistent references in translated message. original: ['`Documentation bugs`_'], translated: ['`ドキュメントのバグ`_'] [i18n.inconsistent_references]

Translated glossary tags in term role

Example from python-docs-pt-br:

#: ../../c-api/init_config.rst:991
msgid "Configure the LC_CTYPE locale (:term:`locale encoding`)"
msgstr "Configura a localidade LC_CTYPE (:term:`codificação da localidade`)"

# c-api/init_config.rst:991: WARNING: inconsistent term references in translated message. original: [':term:`locale encoding`'], translated: [':term:`codificação da localidade`'] [i18n.inconsistent_references]

Note that we can avoid warning by using :term:`codificação da localidade <locale encoding>` in the translation, so not all translation repos is affected by this issue.

Environment Information

sphinx >= 9.0.0

Sphinx extensions

Additional context

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions