feat: Setup infrastructure for I18N, add translations for simplified …

…chinese and japanese PR #77: #77
mkdocstrings · Jul 13, 2023 · b053b29 · b053b29
1 parent ae42356
commit b053b29
Show file tree

Hide file tree

Showing 31 changed files with 281 additions and 74 deletions.
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
@@ -187,6 +187,7 @@ def __init__(
         *args: Any,
         config_file_path: str | None = None,
         paths: list[str] | None = None,
+        locale: str = "en",
         **kwargs: Any,
     ) -> None:
         """Initialize the handler.
@@ -195,6 +196,7 @@ def __init__(
             *args: Handler name, theme and custom templates.
             config_file_path: The MkDocs configuration file path.
             paths: A list of paths to use as Griffe search paths.
+            locale: The locale to use when rendering content.
             **kwargs: Same thing, but with keyword arguments.
         """
         super().__init__(*args, **kwargs)
@@ -215,6 +217,7 @@ def __init__(
         self._paths = search_paths
         self._modules_collection: ModulesCollection = ModulesCollection()
         self._lines_collection: LinesCollection = LinesCollection()
+        self._locale = locale
 
     @classmethod
     def load_inventory(
@@ -328,7 +331,13 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa
         final_config["signature_crossrefs"] = False
 
         return template.render(
-            **{"config": final_config, data.kind.value: data, "heading_level": heading_level, "root": True},
+            **{
+                "config": final_config,
+                data.kind.value: data,
+                "heading_level": heading_level,
+                "root": True,
+                "locale": self._locale,
+            },
         )
 
     def update_env(self, md: Markdown, config: dict) -> None:  # noqa: D102 (ignore missing docstring)
@@ -344,6 +353,7 @@ def update_env(self, md: Markdown, config: dict) -> None:  # noqa: D102 (ignore
         self.env.filters["filter_objects"] = rendering.do_filter_objects
         self.env.filters["stash_crossref"] = lambda ref, length: ref
         self.env.filters["get_template"] = rendering.do_get_template
+        self.env.tests["existing_template"] = lambda template_name: template_name in self.env.list_templates()
 
     def get_anchors(self, data: CollectorItem) -> set[str]:  # noqa: D102 (ignore missing docstring)
         try:
@@ -357,6 +367,7 @@ def get_handler(
     custom_templates: str | None = None,
     config_file_path: str | None = None,
     paths: list[str] | None = None,
+    locale: str = "en",
     **config: Any,  # noqa: ARG001
 ) -> PythonHandler:
     """Simply return an instance of `PythonHandler`.
@@ -366,6 +377,7 @@ def get_handler(
         custom_templates: Directory containing custom templates.
         config_file_path: The MkDocs configuration file path.
         paths: A list of paths to use as Griffe search paths.
+        locale: The locale to use when rendering content.
         **config: Configuration passed to the handler.
 
     Returns:
@@ -377,4 +389,5 @@ def get_handler(
         custom_templates=custom_templates,
         config_file_path=config_file_path,
         paths=paths,
+        locale=locale,
     )
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html
@@ -1,13 +1,16 @@
 {{ log.debug("Rendering attributes section") }}
+
+{% import "language.html" as lang with context %}
+
 {% if config.docstring_section_style == "table" %}
   {% block table_style %}
-  <p><strong>{{ section.title or "Attributes:" }}</strong></p>
+  <p><strong>{{ section.title or lang.t("Attributes:") }}</strong></p>
   <table>
     <thead>
       <tr>
-        <th>Name</th>
-        <th>Type</th>
-        <th>Description</th>
+        <th>{{ lang.t("Name") }}</th>
+        <th>{{ lang.t("Type") }}</th>
+        <th>{{ lang.t("Description") }}</th>
       </tr>
     </thead>
     <tbody>
@@ -33,7 +36,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style %}
-  <p>{{ section.title or "Attributes:" }}</p>
+  <p>{{ section.title or lang.t("Attributes:") }}</p>
   <ul>
     {% for attribute in section.value %}
       <li class="field-body">
@@ -56,8 +59,8 @@
   <table>
     <thead>
       <tr>
-        <th><b>{{ (section.title or "ATTRIBUTE").rstrip(":").upper() }}</b></th>
-        <th><b>DESCRIPTION</b></th>
+        <th><b>{{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }}</b></th>
+        <th><b>{{ lang.t("DESCRIPTION") }}</b></th>
       </tr>
     </thead>
     <tbody>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html
@@ -1,5 +1,8 @@
 {{ log.debug("Rendering examples section") }}
-<p><strong>{{ section.title or "Examples:" }}</strong></p>
+
+{% import "language.html" as lang with context %}
+
+<p><strong>{{ section.title or lang.t("Examples:") }}</strong></p>
 {% for section_type, sub_section in section.value %}
   {% if section_type.value == "text" %}
     {{ sub_section|convert_markdown(heading_level, html_id) }}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html
@@ -1,13 +1,16 @@
 {{ log.debug("Rendering other parameters section") }}
+
+{% import "language.html" as lang with context %}
+
 {% if config.docstring_section_style == "table" %}
   {% block table_style %}
-  <p><strong>{{ section.title or "Other Parameters:" }}</strong></p>
+  <p><strong>{{ section.title or lang.t("Other Parameters:") }}</strong></p>
   <table>
     <thead>
       <tr>
-        <th>Name</th>
-        <th>Type</th>
-        <th>Description</th>
+        <th>{{ lang.t("Name") }}</th>
+        <th>{{ lang.t("Type") }}</th>
+        <th>{{ lang.t("Description") }}</th>
       </tr>
     </thead>
     <tbody>
@@ -33,7 +36,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style %}
-  <p>{{ section.title or "Other Parameters:" }}</p>
+  <p>{{ section.title or lang.t("Other Parameters:") }}</p>
   <ul>
     {% for parameter in section.value %}
       <li class="field-body">
@@ -56,8 +59,8 @@
   <table>
     <thead>
       <tr>
-        <th><b>{{ (section.title or "PARAMETER").rstrip(":").upper() }}</b></th>
-        <th><b>DESCRIPTION</b></th>
+        <th><b>{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }}</b></th>
+        <th><b>{{ lang.t("DESCRIPTION") }}</b></th>
       </tr>
     </thead>
     <tbody>
@@ -71,7 +74,7 @@
             <p>
               {% if parameter.annotation %}
                 <span class="doc-param-annotation">
-                  <b>TYPE:</b>
+                  <b>{{ lang.t("TYPE:") }}</b>
                   {% with expression = parameter.annotation %}
                     <code>{% include "expression.html" with context %}</code>
                   {% endwith %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html
@@ -1,14 +1,17 @@
 {{ log.debug("Rendering parameters section") }}
+
+{% import "language.html" as lang with context %}
+
 {% if config.docstring_section_style == "table" %}
   {% block table_style %}
-  <p><strong>{{ section.title or "Parameters:" }}</strong></p>
+  <p><strong>{{ section.title or lang.t("Parameters:") }}</strong></p>
   <table>
     <thead>
       <tr>
-        <th>Name</th>
-        <th>Type</th>
-        <th>Description</th>
-        <th>Default</th>
+        <th>{{ lang.t("Name") }}</th>
+        <th>{{ lang.t("Type") }}</th>
+        <th>{{ lang.t("Description") }}</th>
+        <th>{{ lang.t("Default") }}</th>
       </tr>
     </thead>
     <tbody>
@@ -33,7 +36,7 @@
                 <code>{% include "expression.html" with context %}</code>
               {% endwith %}
             {% else %}
-              <em>required</em>
+              <em>{{ lang.t("required") }}</em>
             {% endif %}
           </td>
         </tr>
@@ -43,7 +46,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style %}
-  <p>{{ section.title or "Parameters:" }}</p>
+  <p>{{ section.title or lang.t("Parameters:") }}</p>
   <ul>
     {% for parameter in section.value %}
       <li class="field-body">
@@ -66,8 +69,8 @@
   <table>
     <thead>
       <tr>
-        <th><b>{{ (section.title or "PARAMETER").rstrip(":").upper() }}</b></th>
-        <th><b>DESCRIPTION</b></th>
+        <th><b>{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }}</b></th>
+        <th><b> {{ lang.t("DESCRIPTION") }}</b></th>
       </tr>
     </thead>
     <tbody>
@@ -81,15 +84,15 @@
             <p>
               {% if parameter.annotation %}
                 <span class="doc-param-annotation">
-                  <b>TYPE:</b>
+                  <b>{{ lang.t("TYPE:") }}</b>
                   {% with expression = parameter.annotation %}
                     <code>{% include "expression.html" with context %}</code>
                   {% endwith %}
                 </span>
               {% endif %}
               {% if parameter.default %}
                 <span class="doc-param-default">
-                  <b>DEFAULT:</b> 
+                  <b>{{ lang.t("DEFAULT:") }}</b> 
                   {% with expression = parameter.default %}
                     <code>{% include "expression.html" with context %}</code>
                   {% endwith %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html
@@ -1,12 +1,15 @@
 {{ log.debug("Rendering raises section") }}
+
+{% import "language.html" as lang with context %}
+
 {% if config.docstring_section_style == "table" %}
   {% block table_style %}
-  <p><strong>{{ section.title or "Raises:" }}</strong></p>
+  <p><strong>{{ section.title or lang.t("Raises:") }}</strong></p>
   <table>
     <thead>
       <tr>
-        <th>Type</th>
-        <th>Description</th>
+        <th>{{ lang.t("Type") }}</th>
+        <th>{{ lang.t("Description") }}</th>
       </tr>
     </thead>
     <tbody>
@@ -31,7 +34,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style %}
-  <p>{{ section.title or "Raises:" }}</p>
+  <p>{{ lang.t(section.title) or lang.t("Raises:") }}</p>
   <ul>
     {% for raises in section.value %}
       <li class="field-body">
@@ -53,8 +56,8 @@
   <table>
     <thead>
       <tr>
-        <th><b>{{ (section.title or "RAISES").rstrip(":").upper() }}</b></th>
-        <th><b>DESCRIPTION</b></th>
+        <th><b>{{ (section.title or lang.t("RAISES")).rstrip(":").upper() }}</b></th>
+        <th><b>{{ lang.t("DESCRIPTION") }}</b></th>
       </tr>
     </thead>
     <tbody>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html
@@ -1,14 +1,17 @@
 {{ log.debug("Rendering receives section") }}
+
+{% import "language.html" as lang with context %}
+
 {% if config.docstring_section_style == "table" %}
   {% block table_style %}
   {% set name_column = section.value|selectattr("name")|any %}
-  <p><strong>{{ section.title or "Receives:" }}</strong></p>
+  <p><strong>{{ section.title or lang.t("Receives:") }}</strong></p>
   <table>
     <thead>
       <tr>
-        {% if name_column %}<th>Name</th>{% endif %}
-        <th>Type</th>
-        <th>Description</th>
+        {% if name_column %}<th>{{ lang.t("Name") }}</th>{% endif %}
+        <th>{{ lang.t("Type") }}</th>
+        <th>{{ lang.t("Description") }}</th>
       </tr>
     </thead>
     <tbody>
@@ -34,7 +37,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style %}
-  <p>{{ section.title or "Receives:" }}</p>
+  <p>{{ section.title or lang.t("Receives:") }}</p>
   <ul>
     {% for receives in section.value %}
       <li class="field-body">
@@ -59,8 +62,8 @@
   <table>
     <thead>
       <tr>
-        <th><b>{{ (section.title or "RECEIVES").rstrip(":").upper() }}</b></th>
-        <th><b>DESCRIPTION</b></th>
+        <th><b>{{ (section.title or lang.t("RECEIVES")).rstrip(":").upper()) }}</b></th>
+        <th><b>{{ lang.t("DESCRIPTION") }}</b></th>
       </tr>
     </thead>
     <tbody>
@@ -84,7 +87,7 @@
             {% if receives.name and receives.annotation %}
               <p>
                 <span class="doc-receives-annotation">
-                  <b>TYPE:</b>
+                  <b>{{ lang.t("TYPE:") }}</b>
                   {% with expression = receives.annotation %}
                     <code>{% include "expression.html" with context %}</code>
                   {% endwith %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html
@@ -1,14 +1,17 @@
 {{ log.debug("Rendering returns section") }}
+
+{% import "language.html" as lang with context %}
+
 {% if config.docstring_section_style == "table" %}
   {% block table_style %}
   {% set name_column = section.value|selectattr("name")|any %}
-  <p><strong>{{ section.title or "Returns:" }}</strong></p>
+  <p><strong>{{ section.title or lang.t("Returns:") }}</strong></p>
   <table>
     <thead>
       <tr>
-        {% if name_column %}<th>Name</th>{% endif %}
-        <th>Type</th>
-        <th>Description</th>
+        {% if name_column %}<th>{{ lang.t("Name") }}</th>{% endif %}
+        <th>{{ lang.t("Type") }}</th>
+        <th>{{ lang.t("Description") }}</th>
       </tr>
     </thead>
     <tbody>
@@ -34,7 +37,7 @@
   {% endblock table_style %}
 {% elif config.docstring_section_style == "list" %}
   {% block list_style %}
-  <p>{{ section.title or "Returns:" }}</p>
+  <p>{{ section.title or lang.t("Returns:") }}</p>
   <ul>
     {% for returns in section.value %}
       <li class="field-body">
@@ -59,8 +62,8 @@
   <table>
     <thead>
       <tr>
-        <th><b>{{ (section.title or "RETURNS").rstrip(":").upper() }}</b></th>
-        <th><b>DESCRIPTION</b></th>
+        <th><b>{{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }}</b></th>
+        <th><b>{{ lang.t("DESCRIPTION").upper() }}</b></th>
       </tr>
     </thead>
     <tbody>
@@ -84,7 +87,7 @@
             {% if returns.name and returns.annotation %}
               <p>
                 <span class="doc-returns-annotation">
-                  <b>TYPE:</b>
+                  <b>{{ lang.t("TYPE:") }}</b>
                   {% with expression = returns.annotation %}
                     <code>{% include "expression.html" with context %}</code>
                   {% endwith %}