Skip to content

Commit b053b29

Browse files
BlueGlassBlockBlueGlassBlock
authored
feat: Setup infrastructure for I18N, add translations for simplified chinese and japanese
PR #77: #77
1 parent ae42356 commit b053b29

31 files changed

+281
-74
lines changed

‎src/mkdocstrings_handlers/python/handler.py‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,7 @@ def __init__(
187187
*args: Any,
188188
config_file_path: str | None = None,
189189
paths: list[str] | None = None,
190+
locale: str = "en",
190191
**kwargs: Any,
191192
) -> None:
192193
"""Initialize the handler.
@@ -195,6 +196,7 @@ def __init__(
195196
*args: Handler name, theme and custom templates.
196197
config_file_path: The MkDocs configuration file path.
197198
paths: A list of paths to use as Griffe search paths.
199+
locale: The locale to use when rendering content.
198200
**kwargs: Same thing, but with keyword arguments.
199201
"""
200202
super().__init__(*args, **kwargs)
@@ -215,6 +217,7 @@ def __init__(
215217
self._paths = search_paths
216218
self._modules_collection: ModulesCollection = ModulesCollection()
217219
self._lines_collection: LinesCollection = LinesCollection()
220+
self._locale = locale
218221

219222
@classmethod
220223
def load_inventory(
@@ -328,7 +331,13 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str: # noqa
328331
final_config["signature_crossrefs"] = False
329332

330333
return template.render(
331-
**{"config": final_config, data.kind.value: data, "heading_level": heading_level, "root": True},
334+
**{
335+
"config": final_config,
336+
data.kind.value: data,
337+
"heading_level": heading_level,
338+
"root": True,
339+
"locale": self._locale,
340+
},
332341
)
333342

334343
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
344353
self.env.filters["filter_objects"] = rendering.do_filter_objects
345354
self.env.filters["stash_crossref"] = lambda ref, length: ref
346355
self.env.filters["get_template"] = rendering.do_get_template
356+
self.env.tests["existing_template"] = lambda template_name: template_name in self.env.list_templates()
347357

348358
def get_anchors(self, data: CollectorItem) -> set[str]: # noqa: D102 (ignore missing docstring)
349359
try:
@@ -357,6 +367,7 @@ def get_handler(
357367
custom_templates: str | None = None,
358368
config_file_path: str | None = None,
359369
paths: list[str] | None = None,
370+
locale: str = "en",
360371
**config: Any, # noqa: ARG001
361372
) -> PythonHandler:
362373
"""Simply return an instance of `PythonHandler`.
@@ -366,6 +377,7 @@ def get_handler(
366377
custom_templates: Directory containing custom templates.
367378
config_file_path: The MkDocs configuration file path.
368379
paths: A list of paths to use as Griffe search paths.
380+
locale: The locale to use when rendering content.
369381
**config: Configuration passed to the handler.
370382
371383
Returns:
@@ -377,4 +389,5 @@ def get_handler(
377389
custom_templates=custom_templates,
378390
config_file_path=config_file_path,
379391
paths=paths,
392+
locale=locale,
380393
)

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
11
{{ log.debug("Rendering attributes section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
25
{% if config.docstring_section_style == "table" %}
36
{% block table_style %}
4-
<p><strong>{{ section.title or "Attributes:" }}</strong></p>
7+
<p><strong>{{ section.title or lang.t("Attributes:") }}</strong></p>
58
<table>
69
<thead>
710
<tr>
8-
<th>Name</th>
9-
<th>Type</th>
10-
<th>Description</th>
11+
<th>{{ lang.t("Name") }}</th>
12+
<th>{{ lang.t("Type") }}</th>
13+
<th>{{ lang.t("Description") }}</th>
1114
</tr>
1215
</thead>
1316
<tbody>
@@ -33,7 +36,7 @@
3336
{% endblock table_style %}
3437
{% elif config.docstring_section_style == "list" %}
3538
{% block list_style %}
36-
<p>{{ section.title or "Attributes:" }}</p>
39+
<p>{{ section.title or lang.t("Attributes:") }}</p>
3740
<ul>
3841
{% for attribute in section.value %}
3942
<li class="field-body">
@@ -56,8 +59,8 @@
5659
<table>
5760
<thead>
5861
<tr>
59-
<th><b>{{ (section.title or "ATTRIBUTE").rstrip(":").upper() }}</b></th>
60-
<th><b>DESCRIPTION</b></th>
62+
<th><b>{{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }}</b></th>
63+
<th><b>{{ lang.t("DESCRIPTION") }}</b></th>
6164
</tr>
6265
</thead>
6366
<tbody>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/examples.html‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
{{ log.debug("Rendering examples section") }}
2-
<p><strong>{{ section.title or "Examples:" }}</strong></p>
2+
3+
{% import "language.html" as lang with context %}
4+
5+
<p><strong>{{ section.title or lang.t("Examples:") }}</strong></p>
36
{% for section_type, sub_section in section.value %}
47
{% if section_type.value == "text" %}
58
{{ sub_section|convert_markdown(heading_level, html_id) }}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
11
{{ log.debug("Rendering other parameters section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
25
{% if config.docstring_section_style == "table" %}
36
{% block table_style %}
4-
<p><strong>{{ section.title or "Other Parameters:" }}</strong></p>
7+
<p><strong>{{ section.title or lang.t("Other Parameters:") }}</strong></p>
58
<table>
69
<thead>
710
<tr>
8-
<th>Name</th>
9-
<th>Type</th>
10-
<th>Description</th>
11+
<th>{{ lang.t("Name") }}</th>
12+
<th>{{ lang.t("Type") }}</th>
13+
<th>{{ lang.t("Description") }}</th>
1114
</tr>
1215
</thead>
1316
<tbody>
@@ -33,7 +36,7 @@
3336
{% endblock table_style %}
3437
{% elif config.docstring_section_style == "list" %}
3538
{% block list_style %}
36-
<p>{{ section.title or "Other Parameters:" }}</p>
39+
<p>{{ section.title or lang.t("Other Parameters:") }}</p>
3740
<ul>
3841
{% for parameter in section.value %}
3942
<li class="field-body">
@@ -56,8 +59,8 @@
5659
<table>
5760
<thead>
5861
<tr>
59-
<th><b>{{ (section.title or "PARAMETER").rstrip(":").upper() }}</b></th>
60-
<th><b>DESCRIPTION</b></th>
62+
<th><b>{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }}</b></th>
63+
<th><b>{{ lang.t("DESCRIPTION") }}</b></th>
6164
</tr>
6265
</thead>
6366
<tbody>
@@ -71,7 +74,7 @@
7174
<p>
7275
{% if parameter.annotation %}
7376
<span class="doc-param-annotation">
74-
<b>TYPE:</b>
77+
<b>{{ lang.t("TYPE:") }}</b>
7578
{% with expression = parameter.annotation %}
7679
<code>{% include "expression.html" with context %}</code>
7780
{% endwith %}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
{{ log.debug("Rendering parameters section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
25
{% if config.docstring_section_style == "table" %}
36
{% block table_style %}
4-
<p><strong>{{ section.title or "Parameters:" }}</strong></p>
7+
<p><strong>{{ section.title or lang.t("Parameters:") }}</strong></p>
58
<table>
69
<thead>
710
<tr>
8-
<th>Name</th>
9-
<th>Type</th>
10-
<th>Description</th>
11-
<th>Default</th>
11+
<th>{{ lang.t("Name") }}</th>
12+
<th>{{ lang.t("Type") }}</th>
13+
<th>{{ lang.t("Description") }}</th>
14+
<th>{{ lang.t("Default") }}</th>
1215
</tr>
1316
</thead>
1417
<tbody>
@@ -33,7 +36,7 @@
3336
<code>{% include "expression.html" with context %}</code>
3437
{% endwith %}
3538
{% else %}
36-
<em>required</em>
39+
<em>{{ lang.t("required") }}</em>
3740
{% endif %}
3841
</td>
3942
</tr>
@@ -43,7 +46,7 @@
4346
{% endblock table_style %}
4447
{% elif config.docstring_section_style == "list" %}
4548
{% block list_style %}
46-
<p>{{ section.title or "Parameters:" }}</p>
49+
<p>{{ section.title or lang.t("Parameters:") }}</p>
4750
<ul>
4851
{% for parameter in section.value %}
4952
<li class="field-body">
@@ -66,8 +69,8 @@
6669
<table>
6770
<thead>
6871
<tr>
69-
<th><b>{{ (section.title or "PARAMETER").rstrip(":").upper() }}</b></th>
70-
<th><b>DESCRIPTION</b></th>
72+
<th><b>{{ (section.title or lang.t("PARAMETER")).rstrip(":").upper() }}</b></th>
73+
<th><b> {{ lang.t("DESCRIPTION") }}</b></th>
7174
</tr>
7275
</thead>
7376
<tbody>
@@ -81,15 +84,15 @@
8184
<p>
8285
{% if parameter.annotation %}
8386
<span class="doc-param-annotation">
84-
<b>TYPE:</b>
87+
<b>{{ lang.t("TYPE:") }}</b>
8588
{% with expression = parameter.annotation %}
8689
<code>{% include "expression.html" with context %}</code>
8790
{% endwith %}
8891
</span>
8992
{% endif %}
9093
{% if parameter.default %}
9194
<span class="doc-param-default">
92-
<b>DEFAULT:</b>
95+
<b>{{ lang.t("DEFAULT:") }}</b>
9396
{% with expression = parameter.default %}
9497
<code>{% include "expression.html" with context %}</code>
9598
{% endwith %}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
{{ log.debug("Rendering raises section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
25
{% if config.docstring_section_style == "table" %}
36
{% block table_style %}
4-
<p><strong>{{ section.title or "Raises:" }}</strong></p>
7+
<p><strong>{{ section.title or lang.t("Raises:") }}</strong></p>
58
<table>
69
<thead>
710
<tr>
8-
<th>Type</th>
9-
<th>Description</th>
11+
<th>{{ lang.t("Type") }}</th>
12+
<th>{{ lang.t("Description") }}</th>
1013
</tr>
1114
</thead>
1215
<tbody>
@@ -31,7 +34,7 @@
3134
{% endblock table_style %}
3235
{% elif config.docstring_section_style == "list" %}
3336
{% block list_style %}
34-
<p>{{ section.title or "Raises:" }}</p>
37+
<p>{{ lang.t(section.title) or lang.t("Raises:") }}</p>
3538
<ul>
3639
{% for raises in section.value %}
3740
<li class="field-body">
@@ -53,8 +56,8 @@
5356
<table>
5457
<thead>
5558
<tr>
56-
<th><b>{{ (section.title or "RAISES").rstrip(":").upper() }}</b></th>
57-
<th><b>DESCRIPTION</b></th>
59+
<th><b>{{ (section.title or lang.t("RAISES")).rstrip(":").upper() }}</b></th>
60+
<th><b>{{ lang.t("DESCRIPTION") }}</b></th>
5861
</tr>
5962
</thead>
6063
<tbody>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
{{ log.debug("Rendering receives section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
25
{% if config.docstring_section_style == "table" %}
36
{% block table_style %}
47
{% set name_column = section.value|selectattr("name")|any %}
5-
<p><strong>{{ section.title or "Receives:" }}</strong></p>
8+
<p><strong>{{ section.title or lang.t("Receives:") }}</strong></p>
69
<table>
710
<thead>
811
<tr>
9-
{% if name_column %}<th>Name</th>{% endif %}
10-
<th>Type</th>
11-
<th>Description</th>
12+
{% if name_column %}<th>{{ lang.t("Name") }}</th>{% endif %}
13+
<th>{{ lang.t("Type") }}</th>
14+
<th>{{ lang.t("Description") }}</th>
1215
</tr>
1316
</thead>
1417
<tbody>
@@ -34,7 +37,7 @@
3437
{% endblock table_style %}
3538
{% elif config.docstring_section_style == "list" %}
3639
{% block list_style %}
37-
<p>{{ section.title or "Receives:" }}</p>
40+
<p>{{ section.title or lang.t("Receives:") }}</p>
3841
<ul>
3942
{% for receives in section.value %}
4043
<li class="field-body">
@@ -59,8 +62,8 @@
5962
<table>
6063
<thead>
6164
<tr>
62-
<th><b>{{ (section.title or "RECEIVES").rstrip(":").upper() }}</b></th>
63-
<th><b>DESCRIPTION</b></th>
65+
<th><b>{{ (section.title or lang.t("RECEIVES")).rstrip(":").upper()) }}</b></th>
66+
<th><b>{{ lang.t("DESCRIPTION") }}</b></th>
6467
</tr>
6568
</thead>
6669
<tbody>
@@ -84,7 +87,7 @@
8487
{% if receives.name and receives.annotation %}
8588
<p>
8689
<span class="doc-receives-annotation">
87-
<b>TYPE:</b>
90+
<b>{{ lang.t("TYPE:") }}</b>
8891
{% with expression = receives.annotation %}
8992
<code>{% include "expression.html" with context %}</code>
9093
{% endwith %}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
{{ log.debug("Rendering returns section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
25
{% if config.docstring_section_style == "table" %}
36
{% block table_style %}
47
{% set name_column = section.value|selectattr("name")|any %}
5-
<p><strong>{{ section.title or "Returns:" }}</strong></p>
8+
<p><strong>{{ section.title or lang.t("Returns:") }}</strong></p>
69
<table>
710
<thead>
811
<tr>
9-
{% if name_column %}<th>Name</th>{% endif %}
10-
<th>Type</th>
11-
<th>Description</th>
12+
{% if name_column %}<th>{{ lang.t("Name") }}</th>{% endif %}
13+
<th>{{ lang.t("Type") }}</th>
14+
<th>{{ lang.t("Description") }}</th>
1215
</tr>
1316
</thead>
1417
<tbody>
@@ -34,7 +37,7 @@
3437
{% endblock table_style %}
3538
{% elif config.docstring_section_style == "list" %}
3639
{% block list_style %}
37-
<p>{{ section.title or "Returns:" }}</p>
40+
<p>{{ section.title or lang.t("Returns:") }}</p>
3841
<ul>
3942
{% for returns in section.value %}
4043
<li class="field-body">
@@ -59,8 +62,8 @@
5962
<table>
6063
<thead>
6164
<tr>
62-
<th><b>{{ (section.title or "RETURNS").rstrip(":").upper() }}</b></th>
63-
<th><b>DESCRIPTION</b></th>
65+
<th><b>{{ (section.title or lang.t("RETURNS")).rstrip(":").upper() }}</b></th>
66+
<th><b>{{ lang.t("DESCRIPTION").upper() }}</b></th>
6467
</tr>
6568
</thead>
6669
<tbody>
@@ -84,7 +87,7 @@
8487
{% if returns.name and returns.annotation %}
8588
<p>
8689
<span class="doc-returns-annotation">
87-
<b>TYPE:</b>
90+
<b>{{ lang.t("TYPE:") }}</b>
8891
{% with expression = returns.annotation %}
8992
<code>{% include "expression.html" with context %}</code>
9093
{% endwith %}

0 commit comments

Comments
 (0)