fix: don't let translated snippets clobber a page's sphinx metadata

myst_parser/mdit_to_docutils/base.py

@@ -270,9 +270,14 @@ def _render_initialise(self) -> None:
     def _render_finalise(self) -> None:
         """Finalise the render of the document."""
 
+        # when sphinx parses a translation snippet (``_publish_msgstr``),
+        # the document source ends with ":<translated>";
+        # such a snippet must not overwrite the page's own metadata
+        is_translated = str(self.document["source"]).endswith(":<translated>")
+
         # save for later reference resolution
         self.document.myst_slugs = self._heading_slugs
-        if self._heading_slugs and self.sphinx_env:
+        if self._heading_slugs and self.sphinx_env and not is_translated:
             self.sphinx_env.metadata[self.sphinx_env.docname]["myst_slugs"] = (
                 self._heading_slugs
             )
@@ -302,7 +307,7 @@ def _render_finalise(self) -> None:
         wordcount_metadata = self.md_env.get("wordcount", {})
         if wordcount_metadata:
             # save the wordcount to the sphinx BuildEnvironment metadata
-            if self.sphinx_env is not None:
+            if self.sphinx_env is not None and not is_translated:
                 meta = self.sphinx_env.metadata.setdefault(self.sphinx_env.docname, {})
                 meta["wordcount"] = wordcount_metadata
 

tests/test_sphinx/sourcedirs/translated_slugs/conf.py

@@ -0,0 +1,3 @@
+extensions = ["myst_parser"]
+exclude_patterns = ["_build"]
+myst_heading_anchors = 2

tests/test_sphinx/sourcedirs/translated_slugs/fr/LC_MESSAGES/other.po

@@ -0,0 +1,6 @@
+msgid ""
+msgstr ""
+"Content-Type: text/plain; charset=UTF-8\n"
+
+msgid "Gamma"
+msgstr "Gama"

tests/test_sphinx/sourcedirs/translated_slugs/index.md

@@ -0,0 +1,7 @@
+# Home
+
+```{toctree}
+other
+```
+
+See [beta](other.md#beta).

tests/test_sphinx/sourcedirs/translated_slugs/other.md

@@ -0,0 +1,9 @@
+# Other
+
+## Alpha
+
+## Beta
+
+```{admonition} Gamma
+Text.
+```

tests/test_sphinx/test_sphinx_builds.py

@@ -647,6 +647,34 @@ def test_gettext_html(
     )
 
 
+@pytest.mark.sphinx(
+    buildername="html",
+    srcdir=os.path.join(SOURCE_DIR, "translated_slugs"),
+    freshenv=True,
+    confoverrides={"language": "fr", "gettext_compact": False, "locale_dirs": ["."]},
+)
+def test_translated_local_id(
+    app,
+    status,
+    warning,
+    get_sphinx_app_output,
+):
+    """A translated snippet must not clobber the page's heading-slug metadata.
+
+    Sphinx's ``Locale`` transform parses each translated message with a new
+    document whose source ends in ``:<translated>``; when the snippet is a
+    heading (Sphinx appends an ``===`` underline to translated titles), the
+    snippet's own slugs must not replace ``env.metadata[docname]["myst_slugs"]``,
+    or local anchors in other documents stop resolving (#844).
+    """
+    app.build()
+    assert "build succeeded" in status.getvalue()  # Build succeeded
+    assert warning.getvalue().strip() == ""
+    # and the local id still resolves to the right anchor
+    output = get_sphinx_app_output(app, filename="index.html", buildername="html")
+    assert "other.html#beta" in output
+
+
 @pytest.mark.sphinx(
     buildername="gettext",
     srcdir=os.path.join(SOURCE_DIR, "gettext"),