From 35e16233386b31f999a6681afe84f45c6e0fdb39 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Wed, 15 Jul 2020 02:38:38 +0900
Subject: [PATCH] Fix #4888: i18n: Failed to add an explicit title to ``:ref:``
 role

To allow to give (or not to give) an explicit title to the
pending_xref nodes on translation, this skips to override the
attribute on merge original and translated documents.
---
 CHANGES                                           |  1 +
 sphinx/transforms/i18n.py                         | 14 +++++++++-----
 tests/roots/test-intl/role_xref.txt               |  2 +-
 tests/roots/test-intl/xx/LC_MESSAGES/role_xref.po |  4 ++--
 tests/test_intl.py                                |  6 +++---
 5 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/CHANGES b/CHANGES
index 36e5cc77b..e5125fd46 100644
--- a/CHANGES
+++ b/CHANGES
@@ -57,6 +57,7 @@ Bugs fixed
 * #7846: html theme: XML-invalid files were generated
 * #7894: gettext: Wrong source info is shown when using rst_epilog
 * #7691: linkcheck: HEAD requests are not used for checking
+* #4888: i18n: Failed to add an explicit title to ``:ref:`` role on translation
 * #7928: py domain: failed to resolve a type annotation for the attribute
 * #7968: i18n: The content of ``math`` directive is interpreted as reST on
   translation
diff --git a/sphinx/transforms/i18n.py b/sphinx/transforms/i18n.py
index 34d5b1368..c935ab195 100644
--- a/sphinx/transforms/i18n.py
+++ b/sphinx/transforms/i18n.py
@@ -37,6 +37,13 @@ if False:
 
 logger = logging.getLogger(__name__)
 
+# The attributes not copied to the translated node
+#
+# * refexplict: For allow to give (or not to give) an explicit title
+#               to the pending_xref on translation
+EXCLUDED_PENDING_XREF_ATTRIBUTES = ('refexplicit',)
+
+
 N = TypeVar('N', bound=nodes.Node)
 
 
@@ -426,11 +433,8 @@ class Locale(SphinxTransform):
                 # Copy attributes to keep original node behavior. Especially
                 # copying 'reftarget', 'py:module', 'py:class' are needed.
                 for k, v in xref_reftarget_map.get(key, {}).items():
-                    # Note: This implementation overwrite all attributes.
-                    # if some attributes `k` should not be overwritten,
-                    # you should provide exclude list as:
-                    # `if k not in EXCLUDE_LIST: new[k] = v`
-                    new[k] = v
+                    if k not in EXCLUDED_PENDING_XREF_ATTRIBUTES:
+                        new[k] = v
 
             # update leaves
             for child in patch.children:
diff --git a/tests/roots/test-intl/role_xref.txt b/tests/roots/test-intl/role_xref.txt
index 875af4667..2919b5c7f 100644
--- a/tests/roots/test-intl/role_xref.txt
+++ b/tests/roots/test-intl/role_xref.txt
@@ -14,7 +14,7 @@ same type links
 
 link to :term:`Some term` and :term:`Some other term`.
 
-link to :ref:`i18n-role-xref` and :ref:`same-type-links`.
+link to :ref:`i18n-role-xref`, :ref:`same-type-links` and :ref:`label <same-type-links>`.
 
 link to :doc:`index` and :doc:`glossary_terms`.
 
diff --git a/tests/roots/test-intl/xx/LC_MESSAGES/role_xref.po b/tests/roots/test-intl/xx/LC_MESSAGES/role_xref.po
index 81ee22c6e..96d821fdb 100644
--- a/tests/roots/test-intl/xx/LC_MESSAGES/role_xref.po
+++ b/tests/roots/test-intl/xx/LC_MESSAGES/role_xref.po
@@ -28,8 +28,8 @@ msgstr "SAME TYPE LINKS"
 msgid "link to :term:`Some term` and :term:`Some other term`."
 msgstr "LINK TO :term:`SOME OTHER NEW TERM` AND :term:`SOME NEW TERM`."
 
-msgid "link to :ref:`i18n-role-xref` and :ref:`same-type-links`."
-msgstr "LINK TO :ref:`same-type-links` AND :ref:`i18n-role-xref`."
+msgid "link to :ref:`i18n-role-xref`, :ref:`same-type-links` and :ref:`label <same-type-links>`."
+msgstr "LINK TO :ref:`LABEL <i18n-role-xref>` AND :ref:`same-type-links` AND :ref:`same-type-links`."
 
 msgid "link to :doc:`index` and :doc:`glossary_terms`."
 msgstr "LINK TO :doc:`glossary_terms` AND :doc:`index`."
diff --git a/tests/test_intl.py b/tests/test_intl.py
index d0c64b589..1d1282baa 100644
--- a/tests/test_intl.py
+++ b/tests/test_intl.py
@@ -956,9 +956,9 @@ def test_xml_role_xref(app):
          'glossary_terms#term-Some-term'])
     assert_elem(
         para2[1],
-        ['LINK TO', 'SAME TYPE LINKS', 'AND',
-         "I18N ROCK'N ROLE XREF", '.'],
-        ['same-type-links', 'i18n-role-xref'])
+        ['LINK TO', 'LABEL', 'AND',
+         'SAME TYPE LINKS', 'AND', 'SAME TYPE LINKS', '.'],
+        ['i18n-role-xref', 'same-type-links', 'same-type-links'])
     assert_elem(
         para2[2],
         ['LINK TO', 'I18N WITH GLOSSARY TERMS', 'AND', 'CONTENTS', '.'],