Add :notranslate: metadata feature

Fixes sphinx-doc#11787

doc/usage/advanced/intl.rst

@@ -85,6 +85,10 @@ because code blocks do not contain references anyway.)
 .. versionadded:: 4.5
    The ``#noqa`` mechanism.
 
+If certain parts of the documentation should not be translated, e.g., you want
+to translate tutorials but not technical reference material, you can use the
+``:notranslate:`` metadata field. See :ref:`special-metadata-fields`.
+
 
 Translating with sphinx-intl
 ----------------------------

doc/usage/restructuredtext/field-lists.rst

@@ -34,6 +34,8 @@ document metadata, and is not displayed in the output.
    *docinfo* as normal and will be displayed in the output.
 
 
+.. _special-metadata-fields:
+
 Special metadata fields
 -----------------------
 
@@ -76,3 +78,12 @@ At the moment, these metadata fields are recognized:
    .. note:: object search is still available even if `nosearch` option is set.
 
    .. versionadded:: 3.0
+
+``notranslate``
+   If set, no paragraphs from this document will be added to Gettext message
+   catalogs. This may be useful to save work to the translators, e.g., if you
+   want to internationalize tutorials but not technical reference material. When
+   found in a document ``.../index``, this recursively applies to all
+   documents in the directory ``.../``.
+
+   .. versionadded:: 7.3.0

sphinx/builders/gettext.py

@@ -20,7 +20,11 @@
 from sphinx.util.display import status_iterator
 from sphinx.util.i18n import CatalogInfo, docname_to_domain
 from sphinx.util.index_entries import split_index_msg
-from sphinx.util.nodes import extract_messages, traverse_translatable_index
+from sphinx.util.nodes import (
+    extract_messages,
+    is_translatable_document,
+    traverse_translatable_index,
+)
 from sphinx.util.osutil import canon_path, ensuredir, relpath
 from sphinx.util.tags import Tags
 from sphinx.util.template import SphinxRenderer
@@ -150,6 +154,9 @@ def compile_catalogs(self, catalogs: set[CatalogInfo], message: str) -> None:
         return
 
     def write_doc(self, docname: str, doctree: nodes.document) -> None:
+        if not is_translatable_document(docname, self.env):
+            return
+
         catalog = self.catalogs[docname_to_domain(docname, self.config.gettext_compact)]
 
         for toctree in self.env.tocs[docname].findall(addnodes.toctree):

sphinx/transforms/i18n.py

@@ -342,6 +342,14 @@ class Locale(SphinxTransform):
     default_priority = 20
 
     def apply(self, **kwargs: Any) -> None:
+        # TODO/FIXME: If this document is marked :notranslate:, it might
+        # be better to skip translation here. Some paragraphs might
+        # still get translated in rare cases, e.g., if gettext_compact=True
+        # and there is an identical paragraph in a document that is not
+        # marked :notranslate:. This might be tricky, since self.env.metadata
+        # is only populated in the doctree-read event, which runs after
+        # this transform.
+
         settings, source = self.document.settings, self.document['source']
         msgstr = ''
 

sphinx/util/nodes.py

@@ -232,6 +232,19 @@ def is_translatable(node: Node) -> bool:
     return False
 
 
+def is_translatable_document(docname: str, env: BuildEnvironment) -> bool:
+    docname_parts = docname.split('/')
+    for i in range(len(docname_parts) + 1):
+        bare_prefix = '/'.join(docname_parts[:i])
+        for prefix_docname in (bare_prefix, bare_prefix + '/index'):
+            if (
+                prefix_docname in env.metadata
+                and 'notranslate' in env.metadata[prefix_docname]
+            ):
+                return False
+    return True
+
+
 LITERAL_TYPE_NODES = (
     nodes.literal_block,
     nodes.doctest_block,

tests/roots/test-notranslate/conf.py

@@ -0,0 +1 @@
+gettext_compact = False

tests/roots/test-notranslate/dir/index.rst

@@ -0,0 +1,14 @@
+:notranslate:
+
+A directory
+===========
+
+``dir/index.rst`` is not translated.
+
+The ``:notranslate:`` metadata on this document will apply
+to the whole directory.
+
+.. toctree::
+
+   non-translated
+   subdir/index

tests/roots/test-notranslate/dir/non-translated.rst

@@ -0,0 +1,4 @@
+Non-translated document
+=======================
+
+``dir/non-translated.rst`` is not translated.

tests/roots/test-notranslate/dir/subdir/index.rst

@@ -0,0 +1,4 @@
+Non-translated document
+=======================
+
+``dir/subdir/non-translated.rst`` is not translated.

tests/roots/test-notranslate/index.rst

@@ -0,0 +1,7 @@
+``index.rst`` is translated.
+
+.. toctree::
+
+   non-translated
+   translated
+   dir/index

tests/roots/test-notranslate/non-translated.rst

@@ -0,0 +1,6 @@
+:notranslate:
+
+Non-translated document
+=======================
+
+``non-translated.rst`` is not translated.

tests/roots/test-notranslate/translated.rst

@@ -0,0 +1,4 @@
+Translated document
+===================
+
+``translated.rst`` is translated.

tests/test_notranslate.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+
+import pytest
+
+
+@pytest.mark.sphinx("gettext", testroot="notranslate")
+def test_notranslate_extraction(app):
+    app.build()
+    out = Path(app.outdir)
+    pot_files = {path.relative_to(out) for path in out.glob("*.pot")}
+    assert pot_files == {Path("index.pot"), Path("translated.pot")}