feat: prefer language, add docs

Author: BlueGlassBlock

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.

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,
     )

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 %}