Description

mattwang44

opened on Dec 1, 2025

Issue body actions

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

• The stricter checking was introduced in Fix: Implement smarter reference comparison for i18n #14001.

Reacted by Maciej Olko and Rafael Fontenelle

Activity

1. mattwang44

   added

   type:bug

   on Dec 1, 2025
2. AA-Turner

   added this to the 9.0.x milestone on Dec 1, 2025
3. AA-Turner

   marked 9.0.1 caused a lot of warnings in sphinx-doc-translations' zh_CN part #14147 as a duplicate of this issue on Dec 3, 2025
4. AA-Turner

   unmarked 9.0.1 caused a lot of warnings in sphinx-doc-translations' zh_CN part #14147 as a duplicate of this issue on Dec 4, 2025
5. AA-Turner

   closed this as completedin #14144on Dec 4, 2025
6. AA-Turner commented on Dec 4, 2025

   

   AA-Turner

   on Dec 4, 2025

   Member

   More actions

   Sphinx 9.0.4 has been released.

   A

   Reacted by W. H. Wang
7. rffontenelle commented on Dec 4, 2025

   

   rffontenelle

   on Dec 4, 2025

   Contributor

   More actions

   I expected it be fixed with 9.0.4, but I'm still seeing the same errors when building translation documentation of Sphinx docs (See pt_BR build in sphinx-doc-translations repo)

   Example:

   development/tutorials/adding_domain.rst:30: WARNING: inconsistent term references in translated message. original: [':term:`domain`'], translated: [':term:`domínio`']
8. AA-Turner commented on Dec 4, 2025

   

   AA-Turner

   on Dec 4, 2025

   Member

   More actions

   @rffontenelle if you find a fix happy to merge.
9. mattwang44 commented on Dec 4, 2025

   

   mattwang44

   on Dec 4, 2025

   ContributorAuthor

   More actions

   Number of build warnings in pydoc-zh-tw has reduced from 1.6k to 31 after this PR is released and after I fixed dozens of true positives.

   Indeed this PR does not cover the case of the tag in the term role being translated. We use custom link text (:term:`domínio <domain>`) in translation so I didn't spot this issue.

   ---

   I also found that hyperlink syntax is not covered. These cases are legit and should not raise warnings too.

   # reorder
   about.rst:6: WARNING: inconsistent references in translated message. original: ['`reStructuredText`_', '`Sphinx`_'], translated: ['`Sphinx`_', '`reStructuredText`_'] [i18n.inconsistent_references]
   
   # translated display text
   bugs.rst:24: WARNING: inconsistent references in translated message. original: ['`translation’s repository <TRANSLATION_REPO_>`_'], translated: ['`翻譯存儲庫 <TRANSLATION_REPO_>`_'] [i18n.inconsistent_references]
   
   # translated tag
   bugs.rst:37: WARNING: inconsistent references in translated message. original: ['`Documentation bugs`_'], translated: ['`說明文件錯誤`_'] [i18n.inconsistent_references]
   
   # custom link text
   library/enum.rst:77: WARNING: inconsistent references in translated message. original: ['`Notes`_'], translated: ['`備註 <Notes_>`_'] [i18n.inconsistent_references]
   

   ---

   I'll open new issues mentioned above in recent days (if no one has opened then)
10. mattwang44

    changed the title [-]False positive warnings for reordered refs and translated display text[/-] [+]i18n: False positive warnings for reordered refs and translated display text[/+] on Dec 8, 2025
11. github-actions

    locked as resolved and limited conversation to collaborators on Jan 6, 2026

Issue actions