Always ignore order in `_NodeUpdater.compare_references()` (#14172)

sphinx/transforms/i18n.py

@@ -133,24 +133,21 @@ class _NodeUpdater:
         warning_msg: str,
         *,
         key_func: Callable[[nodes.Element], Any] = attrgetter('rawsource'),
-        ignore_order: bool = False,
     ) -> None:
         """Warn about mismatches between references in original and translated content.
+        Ignores the order of references when comparing. This allows translators to
+        reorder references while still catching missing or extra references.
 
         :param key_func: A function to extract the comparison key from each reference.
             Defaults to extracting the ``rawsource`` attribute.
-        :param ignore_order: If True, ignore the order of references when comparing.
-            This allows translators to reorder references while still catching
-            missing or extra references.
         """
         old_ref_keys = list(map(key_func, old_refs))
         new_ref_keys = list(map(key_func, new_refs))
 
-        if ignore_order:
-            # The ref_keys lists may contain ``None``, so compare hashes.
-            # Recall objects which compare equal have the same hash value.
-            old_ref_keys.sort(key=hash)
-            new_ref_keys.sort(key=hash)
+        # The ref_keys lists may contain ``None``, so compare hashes.
+        # Recall objects which compare equal have the same hash value.
+        old_ref_keys.sort(key=hash)
+        new_ref_keys.sort(key=hash)
 
         if not self.noqa and old_ref_keys != new_ref_keys:
             old_ref_rawsources = [ref.rawsource for ref in old_refs]
@@ -365,9 +362,7 @@ class _NodeUpdater:
                 ' original: {0}, translated: {1}'
             ),
             # Compare by reftarget only, allowing translated display text.
-            # Ignore order since translators may legitimately reorder references.
             key_func=lambda ref: ref.get('reftarget'),
-            ignore_order=True,
         )
 
         xref_reftarget_map: dict[tuple[str, str, str] | None, dict[str, Any]] = {}

tests/roots/test-intl/refs_inconsistency.txt

@@ -6,8 +6,12 @@ i18n with refs inconsistency
 * [100]_ for [#]_ citation [ref2]_.
 * for reference_.
 * normal text.
+* we ignore the [order]_ of the [refs]_ in [translations]_.
 
 .. [#] This is a auto numbered footnote.
 .. [ref2] This is a citation.
 .. [100] This is a numbered footnote.
 .. _reference: https://www.example.com
+.. [order] order
+.. [refs] references
+.. [translations] translations

tests/roots/test-intl/xx/LC_MESSAGES/refs_inconsistency.po

@@ -28,6 +28,9 @@ msgstr "reference_ FOR reference_."
 msgid "normal text."
 msgstr "ORPHAN REFERENCE: `I18N WITH REFS INCONSISTENCY`_."
 
+msgid "we ignore the [order]_ of the [refs]_ in [translations]_."
+msgstr "the [refs]_ [translations]_ [order]_ is ignored."
+
 msgid "This is a auto numbered footnote."
 msgstr "THIS IS A AUTO NUMBERED FOOTNOTE."
 
@@ -36,4 +39,3 @@ msgstr "THIS IS A CITATION."
 
 msgid "This is a numbered footnote."
 msgstr "THIS IS A NUMBERED FOOTNOTE."
-

tests/test_intl/test_intl.py

@@ -166,9 +166,13 @@ def test_text_inconsistency_warnings(app):
         '\n* FOR CITATION [ref3].\n'
         '\n* reference FOR reference.\n'
         '\n* ORPHAN REFERENCE: I18N WITH REFS INCONSISTENCY.\n'
+        '\n* the [refs] [translations] [order] is ignored.\n'
         '\n[1] THIS IS A AUTO NUMBERED FOOTNOTE.\n'
         '\n[ref2] THIS IS A CITATION.\n'
         '\n[100] THIS IS A NUMBERED FOOTNOTE.\n'
+        '\n[order] order\n'
+        '\n[refs] references\n'
+        '\n[translations] translations\n'
     )
     assert result == expect