-
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Description
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:
- Translators reorder references for natural flow in the target language
- 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
- The stricter checking was introduced in Fix: Implement smarter reference comparison for i18n #14001.