Keep "translated" attribute on translated nodes

[humitos]

Feature or Bugfix

Feature

Purpose

sphinx.transforms.Locale iterates over all the nodes to replace its content with the translated version of the text if found. Since the process works in two phases, it adds an "internal" translated: True attribute to the docutils node when the translated text is found in phase 1, allowing phase 2 to skip this nodes and avoid re-processing them. Finally, this "internal" translated attribute is removed from all the nodes.

This particular commit deletes the code that removes the translated attribute from the nodes so developers can use it to improve the experience on translations. This attribute can be useful to calculate the translated percentage of a particular document, to visually mark paragraphs as not translated and many other applications.

Example

I created a minimal example of how developers can use this translated attribute to develop Sphinx extensions: https://github.com/humitos/sphinx-translated-node-example

Detail

• Keep 'translated' node attribute #11157

Relates

• i18n: Highlight untranslated paragraphs #1246

[AA-Turner]

The tests need fixing -- likely the problem is shared_result.

A

[humitos]

That makes sense. Thanks! 👍🏼 . I pushed a new commit. I think it should pass all the tests now.

[AA-Turner]

Does #3588 still apply? That was the reason translated attributes were originally removed from nodes.

A

[humitos]

Good point. It seems that it only affects HTML4 writer since the method should_be_compact_paragraph() does not exist in the other writers. I suppose this will break when using html4_writer=True in Sphinx, tho.

If we want to keep supporting HTML4, we could remove those attributes in another SphinxTransform that's executed with default_priority = 999 for example. This way, developers can still use these attributes in transforms between 20 (sphinx.transforms.i18n.Locale) and 999 (our new transform). However, I just tried this and I found this error message when building:

HTML 4 is no longer supported by Sphinx. ("html4_writer=True" detected in configuration options)

So, I suppose we are safe keeping this translated attribute in the nodes. Let me know your thoughts on this.

[humitos]

I created the HTML file using the latest Sphinx 7.0.1 and another using the development version from this PR (with the translated.py extension from my example repository):

▶ diff -u sphinx-latest.html sphinx-pr-development.html
--- sphinx-latest.html	2023-07-23 20:32:16.329349599 +0200
+++ sphinx-pr-development.html	2023-07-23 20:32:28.145932780 +0200
@@ -6,13 +6,13 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
 
     <title>Hola mundo traducido &#8212; documentación de Python - </title>
-    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
-    <link rel="stylesheet" type="text/css" href="_static/translated.css" />
-    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
-    <script src="_static/doctools.js"></script>
-    <script src="_static/sphinx_highlight.js"></script>
-    <script src="_static/translations.js"></script>
+    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b3523f8e" />
+    <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=039e1c02" />
+    <link rel="stylesheet" type="text/css" href="_static/translated.css?v=dbb70219" />
+    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=0828dd0a"></script>
+    <script src="_static/doctools.js?v=888ff710"></script>
+    <script src="_static/sphinx_highlight.js?v=4825356b"></script>
+    <script src="_static/translations.js?v=b95a766b"></script>
     <link rel="index" title="Índice" href="genindex.html" />
     <link rel="search" title="Búsqueda" href="search.html" />
    
@@ -32,15 +32,15 @@
           <div class="body" role="main">
             
   <section id="hello-translated-world">
-<h1>Hola mundo traducido<a class="headerlink" href="#hello-translated-world" title="Enlace permanente a este encabezado">¶</a></h1>
+<h1 class="translated">Hola mundo traducido<a class="headerlink" href="#hello-translated-world" title="Enlace permanente a este encabezado">¶</a></h1>
 <p>This is a minimal example of how developers can use the <code class="docutils literal notranslate"><span class="pre">translated</span></code> node attribute to build different Sphinx extensions.
 It highlights (in green) via CSS the translated paragraphs and shows the translated percetange of each document.</p>
 <div class="admonition note">
 <p class="admonition-title">Nota</p>
 <p>The source language is English and the target language is Spanish.</p>
 </div>
-<p>This file is translated at 0.0 %</p>
-<p>Este archivo está escrito en inglés y será traducido al español.</p>
+<p>This file is translated at 18.181818181818183 %</p>
+<p class="translated">Este archivo está escrito en inglés y será traducido al español.</p>
 <p>This paragraph should be missing the Spanish translation and it is shown in it’s original language.</p>
 <p>List definition:</p>
 <ul class="simple">
@@ -101,7 +101,7 @@
       &copy;.
       
       |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 7.0.1</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 7.1.0+/2c8909cdc</a>
       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.13</a>
       
       |

Note the only differences are:

• the css and js because it seems the development version adds ?v= to all the files (not my change)
• the class="translated" on tags (added by the translated.py Sphinx extension as example)

This means there is no HTML structure modification when keeping the translated attribute on nodes. At least on HTML5 writer.

[AA-Turner]

Thanks for the detailed explanation @humitos!

A