Skip to content

Fix false positive i18n warnings for translated glossary term references#14357

Open
m-aciek wants to merge 7 commits intosphinx-doc:masterfrom
m-aciek:copilot/fix-last-four-cases-issue-14162
Open

Fix false positive i18n warnings for translated glossary term references#14357
m-aciek wants to merge 7 commits intosphinx-doc:masterfrom
m-aciek:copilot/fix-last-four-cases-issue-14162

Conversation

@m-aciek
Copy link
Copy Markdown
Contributor

@m-aciek m-aciek commented Mar 27, 2026

Purpose

  • Translators were incorrectly warned about "inconsistent references" when legitimately translating hyperlink display text while preserving targets.
  • Term references (:term:) were generating "inconsistent term references" warnings when translators legitimately translated glossary term names or when PO files wrapped lines mid-reference.

Cases from #14162:

  • Case 2: Add translated display text for hyperlink
  • Case 3: Translated display text for hyperlink
  • Case 4: Use translated hyperlink tag
  • Case 5: Translated glossary term (with explicit target syntax)
  • Additional: Term references with translated glossary term names
  • Additional: Term references with newlines from PO file wrapping
# Examples that incorrectly warned:
msgid ":term:`virtual <abstract base\nclass>`"  # newline from PO wrapping
msgstr ":term:`wirtualną <abstrakcyjna klasa bazowa>`"

msgid ":term:`text encoding`"  # translated glossary term name
msgstr ":term:`kodowanie tekstu`"

Changes

  • Modified update_pending_xrefs() to validate cross-reference count only, not content

    • Removed compare_references() call comparing by reftarget
    • Allows translators to translate both display text and term names when glossary is translated
    • Preserves warnings for actual inconsistencies (count mismatches)
  • Modified update_refnamed_references() - same pattern applied to term references

  • Test coverage for newline handling and translated term names

This unblocks Python documentation translations where glossaries are translated alongside the content.

Note that changes were coded with use of Copilot, I performed a review and tests.

Python docs warnings before and after those changes (build warnings column).

References

Copilot AI and others added 5 commits March 26, 2026 19:32
- Modified update_refnamed_references() to only check reference count, not display text
- This allows translators to change display text while keeping the same target
- Added comprehensive test case covering cases 2-4 from issue sphinx-doc#14162
- Case 5 (glossary terms) already works correctly with explicit target syntax

Co-authored-by: m-aciek <9288014+m-aciek@users.noreply.github.com>
- Clarified comment about display text affecting rawsource comparison
- Simplified case 4 test to better demonstrate the fixup mechanism

Co-authored-by: m-aciek <9288014+m-aciek@users.noreply.github.com>
…ary terms

- Modified update_pending_xrefs() to only check count, not reftarget content
- This allows translators to translate glossary term names when glossary is also translated
- Handles newlines from PO file wrapping without false warnings
- Added comprehensive test cases covering all scenarios from the issue
- All 43 intl tests passing

Agent-Logs-Url: https://github.com/m-aciek/sphinx/sessions/5401f5a5-02a7-43cc-9525-a8039f9fa3f7

Co-authored-by: m-aciek <9288014+m-aciek@users.noreply.github.com>
@m-aciek m-aciek marked this pull request as draft March 27, 2026 10:23
@m-aciek
Copy link
Copy Markdown
Contributor Author

m-aciek commented Mar 27, 2026

ty failures should be addressed by #14296.

@m-aciek m-aciek marked this pull request as ready for review March 27, 2026 10:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

i18n: False positive build warnings of hyperlinks and term roles

2 participants