refactor: Deprecate locale option in favor of mkdocstrings'

pawamoy · web-flow · commit 17f71babf110 · 2025-07-23T19:57:18.000+02:00
PR-288: #288
diff --git a/docs/usage/index.md b/docs/usage/index.md
@@ -150,9 +150,11 @@ plugins:
   [__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package
 
 [](){#setting-locale}
-#### `locale`
+#### ~~`locale`~~
 
-The locale to use when translating template strings. The translation system is not fully ready yet, so we don't recommend setting the option for now.
+**Deprecated.** Use mkdocstrings' own `locale` setting.
+
+~~The locale to use when translating template strings.~~
 
 [](){#setting-paths}
 #### `paths`
diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py
@@ -1035,7 +1035,9 @@ class PythonInputConfig:
 
     locale: Annotated[
         str | None,
-        _Field(description="The locale to use when translating template strings."),
+        _Field(
+            description="Deprecated. Use mkdocstrings' own `locale` setting instead. The locale to use when translating template strings.",
+        ),
     ] = None
 
     @classmethod
diff --git a/src/mkdocstrings_handlers/python/_internal/handler.py b/src/mkdocstrings_handlers/python/_internal/handler.py
@@ -278,12 +278,13 @@ def collect(self, identifier: str, options: PythonOptions) -> CollectorItem:
 
         return doc_object
 
-    def render(self, data: CollectorItem, options: PythonOptions) -> str:
+    def render(self, data: CollectorItem, options: PythonOptions, locale: str | None = None) -> str:
         """Render the collected data.
 
         Parameters:
             data: The collected data.
             options: The options to use for rendering.
+            locale: The locale to use for rendering (default is "en").
 
         Returns:
             The rendered data (HTML).
@@ -300,7 +301,8 @@ def render(self, data: CollectorItem, options: PythonOptions) -> str:
                 # than as an item in a dictionary.
                 "heading_level": options.heading_level,
                 "root": True,
-                "locale": self.config.locale,
+                # YORE: Bump 2: Regex-replace ` or .+` with ` or "en",` within line.
+                "locale": locale or self.config.locale,
             },
         )
 
@@ -401,6 +403,7 @@ def get_handler(
     Parameters:
         handler_config: The handler configuration.
         tool_config: The tool (SSG) configuration.
+        **kwargs: Additional arguments to pass to the handler.
 
     Returns:
         An instance of `PythonHandler`.
