Fix #1734: Could not translate the caption of toctree directive

1 files changed, 45 insertions, 1 deletions

diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py
index 284bc1c75..c5ce4e296 100644
--- a/sphinx/addnodes.py
+++ b/sphinx/addnodes.py
@@ -14,9 +14,53 @@ import warnings
 from docutils import nodes
 
 
-class toctree(nodes.General, nodes.Element):
+class translatable:
+    """Node which supports translation.
+
+    The translation goes forward with following steps:
+
+    1. Preserve original translatable messages
+    2. Apply translated messages from message catalog
+    3. Extract preserved messages (for gettext builder)
+
+    The translatable nodes MUST preserve original messages.
+    And these messages should not be overridden at applying step.
+    Because they are used at final step; extraction.
+    """
+
+    def preserve_original_messages(self):
+        """Preserve original translatable messages."""
+        raise NotImplementedError
+
+    def apply_translated_message(self, original_message, translated_message):
+        """Apply translated message."""
+        raise NotImplementedError
+
+    def extract_original_messages(self):
+        """Extract translation messages.
+
+        :returns: list of extracted messages or messages generator
+        """
+        raise NotImplementedError
+
+
+class toctree(nodes.General, nodes.Element, translatable):
     """Node for inserting a "TOC tree"."""
 
+    def preserve_original_messages(self):
+        if 'caption' in self:
+            self['rawcaption'] = self['caption']
+
+    def apply_translated_message(self, original_message, translated_message):
+        if self.get('rawcaption') == original_message:
+            self['caption'] = translated_message
+
+    def extract_original_messages(self):
+        if 'rawcaption' in self:
+            return [self['rawcaption']]
+        else:
+            return []
+
 
 # domain-specific object descriptions (class, function etc.)