From 4494d4efd62447c189c0ecafee1c530344a44b51 Mon Sep 17 00:00:00 2001
From: BlueGlassBlock <blueglassblock@outlook.com>
Date: Thu, 18 Jan 2024 12:57:23 +0800
Subject: [PATCH] feat: prefer `language`, add docs

---
 docs/usage/index.md                                | 12 ++++++++++++
 src/mkdocstrings_handlers/python/handler.py        | 14 +++++++-------
 .../python/templates/material/language.html        |  2 +-
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/docs/usage/index.md b/docs/usage/index.md
index 670f6e5..dadb2ad 100644
--- a/docs/usage/index.md
+++ b/docs/usage/index.md
@@ -58,6 +58,18 @@ with the `handler` option:
     handler: python
 ```
 
+## Internationalization (i18n)
+
+The Python handler of *mkdocstrings* supports changing the output language.
+
+The following languages can be used by enabling in [mkdocstrings configuration](https://mkdocstrings.github.io/usage/#internationalization-i18n):
+
+Currently supported languages:
+
+- :flag_us: `en`: English (default) 
+- :flag_cn: `zh`: Chinese (Simplified) 
+- :flag_jp: `ja`: Japanese 
+
 ## Configuration
 
 When installed, the Python handler becomes the default *mkdocstrings* handler.
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
index 9f6cae4..02dd3d7 100644
--- a/src/mkdocstrings_handlers/python/handler.py
+++ b/src/mkdocstrings_handlers/python/handler.py
@@ -189,7 +189,7 @@ def __init__(
         *args: Any,
         config_file_path: str | None = None,
         paths: list[str] | None = None,
-        locale: str = "en",
+        language: str = "en",
         load_external_modules: bool = False,
         **kwargs: Any,
     ) -> None:
@@ -199,7 +199,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.
+            language: The language to use when rendering content.
             load_external_modules: Load external modules when resolving aliases.
             **kwargs: Same thing, but with keyword arguments.
         """
@@ -222,7 +222,7 @@ def __init__(
         self._paths = search_paths
         self._modules_collection: ModulesCollection = ModulesCollection()
         self._lines_collection: LinesCollection = LinesCollection()
-        self._locale = locale
+        self._language = language
 
     @classmethod
     def load_inventory(
@@ -357,8 +357,8 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa
                 "config": final_config,
                 data.kind.value: data,
                 "heading_level": heading_level,
+                "language": self._language,
                 "root": True,
-                "locale": self._locale,
             },
         )
 
@@ -431,7 +431,7 @@ def get_handler(
     custom_templates: str | None = None,
     config_file_path: str | None = None,
     paths: list[str] | None = None,
-    locale: str = "en",
+    language: str = "en",
     load_external_modules: bool = False,
     **config: Any,  # noqa: ARG001
 ) -> PythonHandler:
@@ -442,7 +442,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.
+        language: The language to use when rendering content.
         load_external_modules: Load external modules when resolving aliases.
         **config: Configuration passed to the handler.
 
@@ -455,6 +455,6 @@ def get_handler(
         custom_templates=custom_templates,
         config_file_path=config_file_path,
         paths=paths,
-        locale=locale,
+        language=language,
         load_external_modules=load_external_modules,
     )
diff --git a/src/mkdocstrings_handlers/python/templates/material/language.html b/src/mkdocstrings_handlers/python/templates/material/language.html
index 26647ff..a9f2b78 100644
--- a/src/mkdocstrings_handlers/python/templates/material/language.html
+++ b/src/mkdocstrings_handlers/python/templates/material/language.html
@@ -1,5 +1,5 @@
 <!-- Import translations for given language and fallback -->
-{% set lang_pth = "languages/" ~ locale ~ ".html" %}
+{% set lang_pth = "languages/" ~ language ~ ".html" %}
 {% if lang_pth is existing_template %}
     {% import lang_pth as lang %}
     {% import "languages/en.html" as fallback %}