Skip to content

False positive warnings for reordered refs and translated display text #14143

@mattwang44

Description

@mattwang44

Describe the bug

After Sphinx v9 was released, a significant increase in build warnings across multiple Python docs translation projects can be observed from the dashboard. I looked into those warnings from the zh-tw repo, and found out that most of the i18n.inconsistent_references warnings are false positives for legitimate translations when:

  1. Translators reorder references for natural flow in the target language
  2. Translators translate the display text while keeping the same reftarget

How to Reproduce

Reordered reference

Consider this PO content:

#: ../../glossary.rst:306
msgid ""
"The :meth:`~object.__enter__` and :meth:`~object.__exit__` methods called by "
"the :keyword:`with` statement.  See :pep:`343`."
msgstr ""
"由 :keyword:`with` 陳述式所呼叫的 :meth:`~object.__enter__` 和 :meth:"
"`~object.__exit__` 方法。另請參閱 :pep:`343`。"

It just reorders the references for natural Chinese sentence flow, but it produces the warning:

glossary.rst:306: WARNING: inconsistent term references in translated message. original: [':meth:`~object.__enter__`', ':meth:`~object.__exit__`', ':keyword:`with`'], translated: [':keyword:`with`', ':meth:`~object.__enter__`', ':meth:`~object.__exit__`'] [i18n.inconsistent_references]

Translated display text

Consider this PO content:

msgid ":ref:`code objects <code-objects>`"
msgstr ":ref:`程式碼物件 <code-objects>`"

The reftarget (code-objects) is the same, and only the display text is translated, which should be legitimate but induces the warning:

whatsnew/3.13.rst:800: WARNING: inconsistent term references in translated message.
original: [':ref:`code objects <code-objects>`'],
translated: [':ref:`程式碼物件 <code-objects>`']
[i18n.inconsistent_references]

Environment Information

sphinx>=9.0.0

Sphinx extensions

Additional context

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions