From 6d102bf082220ba04b85f1449b3eb9c858820353 Mon Sep 17 00:00:00 2001 From: BlueGlassBlock Date: Wed, 14 Jun 2023 22:14:15 +0800 Subject: [PATCH 1/6] feat(i18n): infra + simplified chinese --- src/mkdocstrings_handlers/python/handler.py | 14 +++++++++- .../material/_base/docstring/attributes.html | 17 ++++++----- .../material/_base/docstring/examples.html | 5 +++- .../_base/docstring/other_parameters.html | 19 +++++++------ .../material/_base/docstring/parameters.html | 25 +++++++++-------- .../material/_base/docstring/raises.html | 15 ++++++---- .../material/_base/docstring/receives.html | 19 +++++++------ .../material/_base/docstring/returns.html | 19 +++++++------ .../material/_base/docstring/warns.html | 15 ++++++---- .../material/_base/docstring/yields.html | 19 +++++++------ .../templates/material/_base/function.html | 4 ++- .../material/_base/languages/en.html | 28 +++++++++++++++++++ .../material/_base/languages/zh.html | 28 +++++++++++++++++++ .../python/templates/material/language.html | 7 +++++ .../templates/material/languages/en.html | 1 + .../templates/material/languages/zh.html | 1 + .../readthedocs/docstring/attributes.html | 5 +++- .../docstring/other_parameters.html | 5 +++- .../readthedocs/docstring/parameters.html | 5 +++- .../readthedocs/docstring/raises.html | 5 +++- .../readthedocs/docstring/receives.html | 5 +++- .../readthedocs/docstring/returns.html | 5 +++- .../readthedocs/docstring/warns.html | 5 +++- .../readthedocs/docstring/yields.html | 5 +++- .../templates/readthedocs/language.html | 7 +++++ .../templates/readthedocs/languages/en.html | 11 ++++++++ .../templates/readthedocs/languages/zh.html | 28 +++++++++++++++++++ 27 files changed, 249 insertions(+), 73 deletions(-) create mode 100644 src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/language.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/languages/en.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/languages/zh.html create mode 100644 src/mkdocstrings_handlers/python/templates/readthedocs/language.html create mode 100644 src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html create mode 100644 src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index c5a06d0c..4887f9a7 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -180,6 +180,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. @@ -188,6 +189,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 for when rendering content. **kwargs: Same thing, but with keyword arguments. """ super().__init__(*args, **kwargs) @@ -208,6 +210,7 @@ def __init__( self._paths = search_paths self._modules_collection: ModulesCollection = ModulesCollection() self._lines_collection: LinesCollection = LinesCollection() + self._locale = locale @classmethod def load_inventory( @@ -321,7 +324,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) @@ -350,6 +359,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`. @@ -359,6 +369,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: @@ -370,4 +381,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 index 20487f20..296f1557 100644 --- 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 %} -

{{ section.title or "Attributes:" }}

+

{{ section.title or lang.t("Attributes:") }}

- - - + + + @@ -33,7 +36,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Attributes:" }}

+

{{ section.title or lang.t("Attributes:") }}

NameTypeDescription{{ lang.t("Name") }}{{ lang.t("Type") }}{{ lang.t("Description") }}
- - + + diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html index 54bbfa5d..bbec5e22 100644 --- 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") }} -

{{ section.title or "Examples:" }}

+ +{% import "language.html" as lang with context %} + +

{{ section.title or lang.t("Examples:") }}

{% 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 index 82fc493c..a8ccbd9a 100644 --- 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 %} -

{{ section.title or "Other Parameters:" }}

+

{{ section.title or lang.t("Other Parameters:") }}

{{ (section.title or "ATTRIBUTE").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
- - - + + + @@ -33,7 +36,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Other Parameters:" }}

+

{{ section.title or lang.t("Other Parameters:") }}

NameTypeDescription{{ lang.t("Name") }}{{ lang.t("Type") }}{{ lang.t("Description") }}
- - + + @@ -71,7 +74,7 @@

{% if parameter.annotation %} - TYPE: + {{ lang.t("TYPE:") }} {% with expression = parameter.annotation %} {% include "expression.html" with context %} {% 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 index b2b57509..515be812 100644 --- 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 %} -

{{ section.title or "Parameters:" }}

+

{{ section.title or lang.t("Parameters:") }}

{{ (section.title or "PARAMETER").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
- - - - + + + + @@ -33,7 +36,7 @@ {% include "expression.html" with context %} {% endwith %} {% else %} - required + {{ lang.t("required") }} {% endif %} @@ -43,7 +46,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Parameters:" }}

+

{{ section.title or lang.t("Parameters:") }}

NameTypeDescriptionDefault{{ lang.t("Name") }}{{ lang.t("Type") }}{{ lang.t("Description") }}{{ lang.t("Default") }}
- - + + @@ -81,7 +84,7 @@

{% if parameter.annotation %} - TYPE: + {{ lang.t("TYPE:") }} {% with expression = parameter.annotation %} {% include "expression.html" with context %} {% endwith %} @@ -89,7 +92,7 @@ {% endif %} {% if parameter.default %} - DEFAULT: + {{ lang.t("DEFAULT:") }} {% with expression = parameter.default %} {% include "expression.html" with context %} {% 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 index 45832d1c..e4edc66a 100644 --- 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 %} -

{{ section.title or "Raises:" }}

+

{{ section.title or lang.t("Raises:") }}

{{ (section.title or "PARAMETER").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }} {{ lang.t("DESCRIPTION") }}
- - + + @@ -31,7 +34,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Raises:" }}

+

{{ lang.t(section.title) or lang.t("Raises:") }}

TypeDescription{{ lang.t("Type") }}{{ lang.t("Description") }}
- - + + diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html index 03b241cb..09b8caed 100644 --- 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 %} -

{{ section.title or "Receives:" }}

+

{{ section.title or lang.t("Receives:") }}

{{ (section.title or "RAISES").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("RAISES")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
- {% if name_column %}{% endif %} - - + {% if name_column %}{% endif %} + + @@ -34,7 +37,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Receives:" }}

+

{{ section.title or lang.t("Receives:") }}

NameTypeDescription{{ lang.t("Name") }}{{ lang.t("Type") }}{{ lang.t("Description") }}
- - + + @@ -84,7 +87,7 @@ {% if receives.name and receives.annotation %}

- TYPE: + {{ lang.t("TYPE:") }} {% with expression = receives.annotation %} {% include "expression.html" with context %} {% 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 index ad63db83..374f8de4 100644 --- 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 %} -

{{ section.title or "Returns:" }}

+

{{ section.title or lang.t("Returns:") }}

{{ (section.title or "RECEIVES").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("RECEIVES")).rstrip(":").upper()) }}{{ lang.t("DESCRIPTION") }}
- {% if name_column %}{% endif %} - - + {% if name_column %}{% endif %} + + @@ -34,7 +37,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Returns:" }}

+

{{ section.title or lang.t("Returns:") }}

NameTypeDescription{{ lang.t("Name") }}{{ lang.t("Type") }}{{ lang.t("Description") }}
- - + + @@ -84,7 +87,7 @@ {% if returns.name and returns.annotation %}

- TYPE: + {{ lang.t("TYPE:") }} {% with expression = returns.annotation %} {% include "expression.html" with context %} {% endwith %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html index 49ae4380..cf1cc4a6 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html @@ -1,12 +1,15 @@ {{ log.debug("Rendering warns section") }} + +{% import "language.html" as lang with context %} + {% if config.docstring_section_style == "table" %} {% block table_style %} -

{{ section.title or "Warns:" }}

+

{{ section.title or lang.t("Warns:") }}

{{ (section.title or "RETURNS").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION").upper() }}
- - + + @@ -31,7 +34,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Warns:" }}

+

{{ section.title or lang.t("Warns:") }}

TypeDescription{{ lang.t("Type") }}{{ lang.t("Description") }}
- - + + diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html index 93b3cfd2..06e80039 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html @@ -1,14 +1,17 @@ {{ log.debug("Rendering yields 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 %} -

{{ section.title or "Yields:" }}

+

{{ section.title or lang.t("Yields:") }}

{{ (section.title or "WARNS").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("WARNS")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
- {% if name_column %}{% endif %} - - + {% if name_column %}{% endif %} + + @@ -34,7 +37,7 @@ {% endblock table_style %} {% elif config.docstring_section_style == "list" %} {% block list_style %} -

{{ section.title or "Yields:" }}

+

{{ section.title or lang.t("Yields:") }}

NameTypeDescription{{ lang.t("Name") }}{{ lang.t("Type") }}{{ lang.t("Description") }}
- - + + @@ -84,7 +87,7 @@ {% if yields.name and yields.annotation %}

- TYPE: + {{ lang.t("TYPE") }}: {% with expression = yields.annotation %} {% include "expression.html" with context %} {% endwith %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html b/src/mkdocstrings_handlers/python/templates/material/_base/function.html index 70c26892..4ae53337 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html @@ -1,5 +1,7 @@ {{ log.debug("Rendering " + function.path) }} +{% import "language.html" as lang with context %} +

{% with html_id = function.path %} @@ -61,7 +63,7 @@ {% if config.show_source and function.source %}
- Source code in {{ function.relative_filepath }} + {{ lang.t("Source code in") }} {{ function.relative_filepath }} {{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }}
{% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html new file mode 100644 index 00000000..5836cccf --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/en.html @@ -0,0 +1,28 @@ + +{% macro t(key) %}{{ { + "ATTRIBUTE": "ATTRIBUTE", + "Attributes:": "Attributes:", + "DEFAULT:": "DEFAULT:", + "Default": "Default", + "DESCRIPTION": "DESCRIPTION", + "Description": "Description", + "Examples:": "Examples:", + "Name": "Name", + "Other Parameters:": "Other Parameters:", + "PARAMETER": "PARAMETER", + "Parameters:": "Parameters:", + "RAISES": "RAISES", + "Raises:" : "Raises:", + "RECEIVES": "RECEIVES", + "Receives:": "Receives:", + "required": "required", + "RETURNS": "RETURNS", + "Returns:": "Returns:", + "Source code in": "Source code in", + "TYPE:": "TYPE:", + "Type": "Type", + "WARNS": "WARNS", + "Warns:": "Warns:", + "YIELDS": "YIELDS", + "Yields:": "Yields:", + }[key] }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html new file mode 100644 index 00000000..a1516f15 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html @@ -0,0 +1,28 @@ + +{% macro t(key) %}{{ { + "ATTRIBUTE": "属性", + "Attributes:": "属性：", + "DEFAULT:": "默认：", + "Default": "默认", + "DESCRIPTION": "描述", + "Description": "描述", + "Examples:": "示例：", + "Name": "名称", + "Other Parameters:": "其他参数：", + "PARAMETER": "参数", + "Parameters:": "参数：", + "RAISES": "引发", + "Raises:" : "引发：", + "Receives:": "接收：", + "RECEIVES": "接收", + "required": "必需", + "RETURNS": "返回", + "Returns:": "返回：", + "Source code in": "源代码位于：", + "TYPE:": "类型：", + "Type": "类型", + "Warns:": "警告：", + "WARNS": "警告", + "YIELDS": "产生", + "Yields:": "产生：", + }[key] }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/language.html b/src/mkdocstrings_handlers/python/templates/material/language.html new file mode 100644 index 00000000..f98d16a7 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/language.html @@ -0,0 +1,7 @@ + + +{% import "languages/" ~ locale ~ ".html" as lang %} +{% import "_base/languages/en.html" as fallback %} + + +{% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/languages/en.html b/src/mkdocstrings_handlers/python/templates/material/languages/en.html new file mode 100644 index 00000000..eab0a3f3 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/languages/en.html @@ -0,0 +1 @@ +{% extends "_base/languages/en.html" %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/languages/zh.html b/src/mkdocstrings_handlers/python/templates/material/languages/zh.html new file mode 100644 index 00000000..90aeae6f --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/languages/zh.html @@ -0,0 +1 @@ +{% extends "_base/languages/zh.html" %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html index 3ed566d5..6f597cd1 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/attributes.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} +
{{ (section.title or "YIELDS").rstrip(":").upper() }}DESCRIPTION{{ (section.title or lang.t("YIELDS")).rstrip(":").upper() }}{{ lang.t("DESCRIPTION") }}
@@ -6,7 +9,7 @@ - +
{{ section.title or "Attributes:" }}{{ section.title or lang.t("Attributes:") }}
    {% for attribute in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html index c5b4b039..d37bc8cb 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/other_parameters.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} + @@ -6,7 +9,7 @@ - +
    {{ section.title or "Other parameters:" }}{{ section.title or lang.t("Other parameters:") }}
      {% for parameter in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html index b05733a7..461fe2a1 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/parameters.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} + @@ -6,7 +9,7 @@ - +
      {{ section.title or "Parameters:" }}{{ section.title or lang.t("Parameters:") }}
        {% for parameter in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html index b744df22..f82437dd 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/raises.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} + @@ -6,7 +9,7 @@ - +
        {{ section.title or "Raises:" }}{{ section.title or lang.t("Raises:") }}
          {% for raises in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html index 127bcd3c..f112351d 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/receives.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} + @@ -6,7 +9,7 @@ - +
          {{ section.title or "Receives:" }}{{ section.title or lang.t("Receives:") }}
            {% for receives in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html index 92f29e31..28b83774 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/returns.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} + @@ -6,7 +9,7 @@ - +
            {{ section.title or "Returns:" }}{{ section.title or lang.t("Returns:") }}
              {% for returns in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html index 12631784..35aff0b1 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/warns.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} + @@ -6,7 +9,7 @@ - +
              {{ section.title or "Warns:" }}{{ section.title or lang.t("Warns:") }}
                {% for warns in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html index 86e8ff7b..7838a66a 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/docstring/yields.html @@ -1,4 +1,7 @@ {{ log.debug() }} + +{% import "language.html" as lang with context %} + @@ -6,7 +9,7 @@ - +
                {{ section.title or "Yields:" }}{{ section.title or lang.t("Yields:") }}
                  {% for yields in section.value %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html new file mode 100644 index 00000000..b092e54f --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html @@ -0,0 +1,7 @@ + + +{% import "languages/" ~ locale ~ ".html" as lang %} +{% import "languages/en.html" as fallback %} + + +{% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html new file mode 100644 index 00000000..acc6d5a7 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/en.html @@ -0,0 +1,11 @@ + +{% macro t(key) %}{{ { + "Attributes:": "Attributes:", + "Other parameters:": "Other parameters:", + "Parameters:": "Parameters:", + "Raises:" : "Raises:", + "Receives:": "Receives:", + "Returns:": "Returns:", + "Warns:": "Warns:", + "Yields:": "Yields:", + }[key] }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html new file mode 100644 index 00000000..8571a16f --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html @@ -0,0 +1,28 @@ + +{% macro t(key) %}{{ { + "Source code in": "源代码位于：", + "Attributes:": "属性：", + "Name": "名称", + "Type": "类型", + "Description": "描述", + "ATTRIBUTE": "属性", + "DESCRIPTION": "描述", + "Examples:": "例子：", + "Other Parameters:": "其他参数：", + "PARAMETER": "参数", + "TYPE:": "类型：", + "Parameters:": "参数：", + "Default": "默认", + "required": "必需", + "DEFAULT:": "默认：", + "Raises:" : "引发：", + "RAISES": "引发", + "Receives:": "接收：", + "RECEIVES": "接收", + "Returns:": "返回：", + "RETURNS": "返回", + "Warns:": "警告：", + "WARNS": "警告", + "Yields:": "产生：", + "YIELDS": "产生", + }[key] }}{% endmacro %} \ No newline at end of file From ec80c3907b50cd58fef247c5373222597bff212e Mon Sep 17 00:00:00 2001 From: BlueGlassBlock Date: Thu, 15 Jun 2023 20:43:31 +0800 Subject: [PATCH 2/6] feat(i18n): ja + fix zh_CN fmt Co-authored-by: AFLeartLey <54972556+AFLeartLey@users.noreply.github.com> --- .../material/_base/languages/ja.html | 28 +++++++++++++++++++ .../templates/material/languages/ja.html | 1 + .../templates/readthedocs/languages/ja.html | 11 ++++++++ .../templates/readthedocs/languages/zh.html | 17 ----------- 4 files changed, 40 insertions(+), 17 deletions(-) create mode 100644 src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html create mode 100644 src/mkdocstrings_handlers/python/templates/material/languages/ja.html create mode 100644 src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html new file mode 100644 index 00000000..6b52ebcd --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html @@ -0,0 +1,28 @@ + +{% macro t(key) %}{{ { + "ATTRIBUTE": "属性", + "Attributes:": "属性：", + "DEFAULT:": "デフォルト：", + "Default": "デフォルト", + "DESCRIPTION": "デスクリプション", + "Description": "デスクリプション", + "Examples:": "例：", + "Name": "名前", + "Other Parameters:": "他の引数：", + "PARAMETER": "引数", + "Parameters:": "引数：", + "RAISES": "発生", + "Raises:" : "発生：", + "RECEIVES": "取得", + "Receives:": "取得：", + "required": "必須", + "RETURNS": "戻り値", + "Returns:": "戻り値：", + "Source code in": "ソースコード位置：", + "TYPE:": "タイプ：", + "Type": "タイプ", + "WARNS": "警告", + "Warns:": "警告：", + "YIELDS": "返す", + "Yields:": "返す：", +}[key] }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/material/languages/ja.html b/src/mkdocstrings_handlers/python/templates/material/languages/ja.html new file mode 100644 index 00000000..0463322d --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/material/languages/ja.html @@ -0,0 +1 @@ +{% extends "_base/languages/ja.html" %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html new file mode 100644 index 00000000..9ae4a568 --- /dev/null +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html @@ -0,0 +1,11 @@ + +{% macro t(key) %}{{ { + "Attributes:": "属性：", + "Other Parameters:": "他の引数：", + "Parameters:": "引数：", + "Raises:" : "発生：", + "Receives:": "取得：", + "Returns:": "戻り値：", + "Warns:": "警告：", + "Yields:": "返す：", + }[key] }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html index 8571a16f..42184f9c 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html @@ -1,28 +1,11 @@ {% macro t(key) %}{{ { - "Source code in": "源代码位于：", "Attributes:": "属性：", - "Name": "名称", - "Type": "类型", - "Description": "描述", - "ATTRIBUTE": "属性", - "DESCRIPTION": "描述", - "Examples:": "例子：", "Other Parameters:": "其他参数：", - "PARAMETER": "参数", - "TYPE:": "类型：", "Parameters:": "参数：", - "Default": "默认", - "required": "必需", - "DEFAULT:": "默认：", "Raises:" : "引发：", - "RAISES": "引发", "Receives:": "接收：", - "RECEIVES": "接收", "Returns:": "返回：", - "RETURNS": "返回", "Warns:": "警告：", - "WARNS": "警告", "Yields:": "产生：", - "YIELDS": "产生", }[key] }}{% endmacro %} \ No newline at end of file From 8b32e89ce4f57b389ae5d05f4c2471f73b85ac82 Mon Sep 17 00:00:00 2001 From: BlueGlassBlock Date: Fri, 16 Jun 2023 12:36:46 +0800 Subject: [PATCH 3/6] fix: add polyfill for locale in templates --- .../python/templates/material/language.html | 4 ++++ .../python/templates/readthedocs/language.html | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/src/mkdocstrings_handlers/python/templates/material/language.html b/src/mkdocstrings_handlers/python/templates/material/language.html index f98d16a7..8cd83a61 100644 --- a/src/mkdocstrings_handlers/python/templates/material/language.html +++ b/src/mkdocstrings_handlers/python/templates/material/language.html @@ -1,5 +1,9 @@ +{% if locale is not defined %} + {% set locale = "en" %} +{% endif %} + {% import "languages/" ~ locale ~ ".html" as lang %} {% import "_base/languages/en.html" as fallback %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html index b092e54f..ed5011e9 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html @@ -1,5 +1,9 @@ +{% if locale is not defined %} + {% set locale = "en" %} +{% endif %} + {% import "languages/" ~ locale ~ ".html" as lang %} {% import "languages/en.html" as fallback %} From 6c028af9ca470f323e03f103b1e0b908383e8759 Mon Sep 17 00:00:00 2001 From: BlueGlassBlock Date: Mon, 19 Jun 2023 12:45:06 +0800 Subject: [PATCH 4/6] fix: provide default locale when testing reverts 8b32e89ce4f57b389ae5d05f4c2471f73b85ac82 --- .../python/templates/material/language.html | 4 ---- .../python/templates/readthedocs/language.html | 4 ---- tests/test_handler.py | 2 +- 3 files changed, 1 insertion(+), 9 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/language.html b/src/mkdocstrings_handlers/python/templates/material/language.html index 8cd83a61..f98d16a7 100644 --- a/src/mkdocstrings_handlers/python/templates/material/language.html +++ b/src/mkdocstrings_handlers/python/templates/material/language.html @@ -1,9 +1,5 @@ -{% if locale is not defined %} - {% set locale = "en" %} -{% endif %} - {% import "languages/" ~ locale ~ ".html" as lang %} {% import "_base/languages/en.html" as fallback %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html index ed5011e9..b092e54f 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html @@ -1,9 +1,5 @@ -{% if locale is not defined %} - {% set locale = "en" %} -{% endif %} - {% import "languages/" ~ locale ~ ".html" as lang %} {% import "languages/en.html" as fallback %} diff --git a/tests/test_handler.py b/tests/test_handler.py index fc31942c..1a970016 100644 --- a/tests/test_handler.py +++ b/tests/test_handler.py @@ -63,7 +63,7 @@ def test_render_docstring_examples_section(handler: PythonHandler) -> None: ], ) template = handler.env.get_template("docstring/examples.html") - rendered = template.render(section=section) + rendered = template.render(section=section, locale="en") assert "

                  This is an example.

                  " in rendered assert "print" in rendered assert "Hello" in rendered From 1dd2bb0af27e6ac512aa3bbb8e1c5c87a0dceff6 Mon Sep 17 00:00:00 2001 From: BlueGlassBlock Date: Tue, 20 Jun 2023 20:55:45 +0800 Subject: [PATCH 5/6] fix: handle case when locale file does not exists --- src/mkdocstrings_handlers/python/handler.py | 1 + .../python/templates/material/language.html | 8 +++++++- .../python/templates/readthedocs/language.html | 8 +++++++- tests/test_handler.py | 1 + 4 files changed, 16 insertions(+), 2 deletions(-) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 4887f9a7..1b21c997 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -346,6 +346,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: diff --git a/src/mkdocstrings_handlers/python/templates/material/language.html b/src/mkdocstrings_handlers/python/templates/material/language.html index f98d16a7..01ae9f0e 100644 --- a/src/mkdocstrings_handlers/python/templates/material/language.html +++ b/src/mkdocstrings_handlers/python/templates/material/language.html @@ -1,6 +1,12 @@ -{% import "languages/" ~ locale ~ ".html" as lang %} +{% set lang_pth = "languages/" ~ locale ~ ".html" %} +{% if lang_pth is existing_template %} + {% import lang_pth as lang %} +{% else %} + {% import "languages/en.html" as lang %} +{% endif %} + {% import "_base/languages/en.html" as fallback %} diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html index b092e54f..2a2c4892 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html @@ -1,6 +1,12 @@ -{% import "languages/" ~ locale ~ ".html" as lang %} +{% set lang_pth = "languages/" ~ locale ~ ".html" %} +{% if lang_pth is existing_template %} + {% import lang_pth as lang %} +{% else %} + {% import "languages/en.html" as lang %} +{% endif %} + {% import "languages/en.html" as fallback %} diff --git a/tests/test_handler.py b/tests/test_handler.py index 1a970016..4971e132 100644 --- a/tests/test_handler.py +++ b/tests/test_handler.py @@ -64,6 +64,7 @@ def test_render_docstring_examples_section(handler: PythonHandler) -> None: ) template = handler.env.get_template("docstring/examples.html") rendered = template.render(section=section, locale="en") + template.render(section=section, locale="not_existing") assert "

                  This is an example.

                  " in rendered assert "print" in rendered assert "Hello" in rendered From 981cf4788dad5c40d7973d7598d0f403bc0a216e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 13 Jul 2023 19:10:52 +0200 Subject: [PATCH 6/6] fixup! feat(i18n): infra + simplified chinese --- src/mkdocstrings_handlers/python/handler.py | 2 +- .../templates/material/_base/docstring/yields.html | 2 +- .../python/templates/material/language.html | 9 +++------ .../python/templates/readthedocs/language.html | 9 +++------ 4 files changed, 8 insertions(+), 14 deletions(-) diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 1b21c997..0a77d3ba 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -189,7 +189,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 for when rendering content. + locale: The locale to use when rendering content. **kwargs: Same thing, but with keyword arguments. """ super().__init__(*args, **kwargs) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html index 06e80039..9a0db29c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html @@ -87,7 +87,7 @@ {% if yields.name and yields.annotation %}

                  - {{ lang.t("TYPE") }}: + {{ lang.t("TYPE:") }}: {% with expression = yields.annotation %} {% include "expression.html" with context %} {% endwith %} diff --git a/src/mkdocstrings_handlers/python/templates/material/language.html b/src/mkdocstrings_handlers/python/templates/material/language.html index 01ae9f0e..26647ff3 100644 --- a/src/mkdocstrings_handlers/python/templates/material/language.html +++ b/src/mkdocstrings_handlers/python/templates/material/language.html @@ -1,13 +1,10 @@ - {% set lang_pth = "languages/" ~ locale ~ ".html" %} {% if lang_pth is existing_template %} {% import lang_pth as lang %} + {% import "languages/en.html" as fallback %} + {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} {% else %} {% import "languages/en.html" as lang %} + {% macro t(key) %}{{ lang.t(key) }}{% endmacro %} {% endif %} - -{% import "_base/languages/en.html" as fallback %} - - -{% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} \ No newline at end of file diff --git a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html index 2a2c4892..26647ff3 100644 --- a/src/mkdocstrings_handlers/python/templates/readthedocs/language.html +++ b/src/mkdocstrings_handlers/python/templates/readthedocs/language.html @@ -1,13 +1,10 @@ - {% set lang_pth = "languages/" ~ locale ~ ".html" %} {% if lang_pth is existing_template %} {% import lang_pth as lang %} + {% import "languages/en.html" as fallback %} + {% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} {% else %} {% import "languages/en.html" as lang %} + {% macro t(key) %}{{ lang.t(key) }}{% endmacro %} {% endif %} - -{% import "languages/en.html" as fallback %} - - -{% macro t(key) %}{{ lang.t(key) or fallback.t(key) }}{% endmacro %} \ No newline at end of file