springbootAI 1.8.0__py3-none-any.whl

spring/i18n/locale_resolver.py

@@ -0,0 +1,367 @@
+"""``LocaleResolver`` 区域解析器（对齐 Spring ``org.springframework.web.servlet.i18n``）。
+
+核心抽象：
+- ``LocaleResolver``：策略接口，从 HTTP 请求解析 ``LocaleContext`` / 写回响应。
+- ``LocaleContext``：携带当前 locale（可选时区）的上下文对象。
+- ``AcceptHeaderLocaleResolver``：从请求 ``Accept-Language`` 头解析（默认推荐）。
+- ``FixedLocaleResolver``：永远返回固定 locale（对齐 Spring 同名类）。
+- ``SessionLocaleResolver``：从会话读写 locale（Starlette SessionMiddleware 风格）。
+- ``CookieLocaleResolver``：从 Cookie 读写 locale。
+
+设计要点：
+- 复用 Starlette ``Request``/``Response`` 抽象，不直接依赖 FastAPI。
+- ``AcceptHeaderLocaleResolver`` 实现 RFC 7231 简化版：解析 q 值排序 + locale 前缀回退。
+- ``SessionLocaleResolver`` 需要应用先注册 ``SessionMiddleware``（Starlette 标准做法）。
+"""
+from __future__ import annotations
+
+import re
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+from .locale import Locale
+
+
+# ==================== LocaleContext ====================
+
+class LocaleContext:
+    """区域上下文（对齐 Spring ``LocaleContext``）。"""
+
+    def get_locale(self) -> Locale:
+        raise NotImplementedError
+
+    def is_fallback(self) -> bool:
+        """是否为回退 locale（部分实现标记）。默认 False。"""
+        return False
+
+
+class SimpleLocaleContext(LocaleContext):
+    """简单 ``LocaleContext`` 实现（对齐 Spring ``SimpleLocaleContext``）。"""
+
+    def __init__(self, locale: Optional[Locale]):
+        self._locale = locale if locale is not None else Locale()
+
+    def get_locale(self) -> Locale:
+        return self._locale
+
+    def __repr__(self) -> str:
+        return f"SimpleLocaleContext({self._locale!r})"
+
+
+class SimpleTimeZoneAwareLocaleContext(LocaleContext):
+    """带时区的 ``LocaleContext``（对齐 Spring ``SimpleTimeZoneAwareLocaleContext``）。
+
+    本实现保留 ``time_zone`` 字段但不参与解析逻辑（仅元数据语义）。
+    """
+
+    def __init__(self, locale: Optional[Locale], time_zone: Optional[str] = None):
+        self._locale = locale if locale is not None else Locale()
+        self._time_zone = time_zone
+
+    def get_locale(self) -> Locale:
+        return self._locale
+
+    def get_time_zone(self) -> Optional[str]:
+        return self._time_zone
+
+    def __repr__(self) -> str:
+        return f"SimpleTimeZoneAwareLocaleContext({self._locale!r}, tz={self._time_zone!r})"
+
+
+# ==================== LocaleResolver 接口 ====================
+
+class LocaleResolver:
+    """区域解析器策略接口（对齐 Spring ``LocaleResolver``）。
+
+    子类需实现 ``resolve_locale(request)`` 返回 ``LocaleContext``。
+    ``set_locale_context(request, response, context)`` 用于写回（部分实现支持）。
+    """
+
+    def resolve_locale(self, request) -> LocaleContext:  # noqa: D401 - 接口方法
+        raise NotImplementedError
+
+    def set_locale_context(self, request, response, context: LocaleContext) -> None:
+        """写回 locale 到响应（``FixedLocaleResolver`` 不支持，抛 ``UnsupportedOperation``）。"""
+        raise NotImplementedError(f"{type(self).__name__} does not support set_locale_context")
+
+
+# ==================== AcceptHeaderLocaleResolver ====================
+
+# Accept-Language 头解析：zh-CN,zh;q=0.9,en;q=0.8
+_ACCEPT_LANG_RE = re.compile(
+    r"\s*([a-zA-Z]{1,8}(?:-[a-zA-Z0-9]{1,8})*)\s*(?:;\s*q\s*=\s*([0-9.]+))?\s*,?",
+    re.IGNORECASE,
+)
+
+
+def parse_accept_language(header: str) -> List[Tuple[Locale, float]]:
+    """解析 ``Accept-Language`` 头，返回 ``[(Locale, q), ...]`` 按 q 降序。
+
+    q 默认 1.0；q=0 表示不可接受（仍保留在列表中，调用方可过滤）。
+    """
+    if not header:
+        return []
+    result: List[Tuple[Locale, float]] = []
+    for match in _ACCEPT_LANG_RE.finditer(header):
+        tag = match.group(1)
+        q_str = match.group(2)
+        try:
+            q = float(q_str) if q_str else 1.0
+        except ValueError:
+            q = 1.0
+        result.append((Locale.parse(tag), q))
+    # q 降序，稳定排序（保留声明顺序）
+    result.sort(key=lambda x: -x[1])
+    return result
+
+
+class AcceptHeaderLocaleResolver(LocaleResolver):
+    """从 ``Accept-Language`` 头解析 locale（对齐 Spring ``AcceptHeaderLocaleResolver``）。
+
+    Args:
+        supported_locales: 支持的 locale 列表；为空时返回请求 locale 原样。
+        default_locale:    无匹配时返回的默认 locale；``None`` 时返回 ``Locale("")``。
+
+    匹配算法（简化 RFC 4647 过滤）：
+        1. 按 q 降序遍历 Accept-Language；
+        2. 精确匹配 supported（language + country）；
+        3. language 前缀匹配 supported；
+        4. 全部不匹配返回 ``default_locale``。
+    """
+
+    def __init__(
+        self,
+        supported_locales: Optional[Sequence[Locale]] = None,
+        default_locale: Optional[Locale] = None,
+    ):
+        self._supported: List[Locale] = list(supported_locales) if supported_locales else []
+        self._default: Locale = default_locale if default_locale is not None else Locale("")
+
+    @property
+    def supported_locales(self) -> List[Locale]:
+        return list(self._supported)
+
+    def set_supported_locales(self, locales: Sequence[Locale]) -> None:
+        self._supported = list(locales)
+
+    def set_default_locale(self, locale: Locale) -> None:
+        self._default = locale
+
+    def resolve_locale(self, request) -> LocaleContext:
+        header = _get_header(request, "accept-language", "")
+        candidates = parse_accept_language(header)
+        if not candidates:
+            return SimpleLocaleContext(self._default)
+        if not self._supported:
+            # 无 supported 列表：直接返回最高 q 的 locale
+            best = candidates[0][0]
+            return SimpleLocaleContext(best if best.is_empty is False else self._default)
+
+        for cand, q in candidates:
+            if q <= 0:
+                continue
+            # 精确匹配
+            for sup in self._supported:
+                if cand == sup:
+                    return SimpleLocaleContext(sup)
+            # language 前缀匹配
+            for sup in self._supported:
+                if cand.language and cand.language == sup.language:
+                    return SimpleLocaleContext(sup)
+        return SimpleLocaleContext(self._default)
+
+    def set_locale_context(self, request, response, context: LocaleContext) -> None:
+        # Accept-Header 解析器不支持写回（对齐 Spring 同名行为）
+        raise NotImplementedError(
+            "AcceptHeaderLocaleResolver 不支持 set_locale_context；"
+            "如需写回请使用 SessionLocaleResolver 或 CookieLocaleResolver"
+        )
+
+
+# ==================== FixedLocaleResolver ====================
+
+class FixedLocaleResolver(LocaleResolver):
+    """固定 locale 解析器（对齐 Spring ``FixedLocaleResolver``）。
+
+    所有请求返回同一 ``LocaleContext``，``set_locale_context`` 抛 ``UnsupportedOperation``。
+    """
+
+    def __init__(
+        self,
+        locale: Optional[Locale] = None,
+        time_zone: Optional[str] = None,
+    ):
+        self._locale = locale if locale is not None else Locale("")
+        self._time_zone = time_zone
+
+    def resolve_locale(self, request) -> LocaleContext:
+        return SimpleTimeZoneAwareLocaleContext(self._locale, self._time_zone)
+
+    def set_locale_context(self, request, response, context: LocaleContext) -> None:
+        raise NotImplementedError(
+            "FixedLocaleResolver 不支持 set_locale_context（locale 固定不可变）"
+        )
+
+
+# ==================== SessionLocaleResolver ====================
+
+class SessionLocaleResolver(LocaleResolver):
+    """会话级 locale 解析器（对齐 Spring ``SessionLocaleResolver``）。
+
+    依赖 Starlette ``SessionMiddleware``；通过 ``request.session`` 读写 locale 字符串。
+    """
+
+    def __init__(
+        self,
+        session_attribute_name: str = "spring_locale",
+        default_locale: Optional[Locale] = None,
+    ):
+        self._session_attr = session_attribute_name
+        self._default = default_locale if default_locale is not None else Locale("")
+
+    def resolve_locale(self, request) -> LocaleContext:
+        session = _get_session(request)
+        loc_str = session.get(self._session_attr) if session else None
+        if loc_str:
+            return SimpleLocaleContext(Locale.parse(loc_str))
+        return SimpleLocaleContext(self._default)
+
+    def set_locale_context(self, request, response, context: LocaleContext) -> None:
+        session = _get_session(request)
+        if session is None:
+            raise RuntimeError(
+                "SessionLocaleResolver 需要 SessionMiddleware；请先注册 starlette SessionMiddleware"
+            )
+        session[self._session_attr] = context.get_locale().to_string()
+
+
+# ==================== CookieLocaleResolver ====================
+
+class CookieLocaleResolver(LocaleResolver):
+    """Cookie 级 locale 解析器（对齐 Spring ``CookieLocaleResolver``）。
+
+    Args:
+        cookie_name:     Cookie 名称，默认 ``spring_locale``。
+        cookie_max_age:  Cookie Max-Age（秒），默认 1 年。
+        cookie_path:     Cookie Path，默认 ``/``。
+        cookie_domain:   Cookie Domain，默认 None。
+        cookie_secure:   是否 Secure，默认 False。
+        cookie_httponly: 是否 HttpOnly，默认 True。
+        default_locale:  Cookie 不存在时的默认 locale。
+    """
+
+    def __init__(
+        self,
+        cookie_name: str = "spring_locale",
+        cookie_max_age: int = 365 * 24 * 3600,
+        cookie_path: str = "/",
+        cookie_domain: Optional[str] = None,
+        cookie_secure: bool = False,
+        cookie_httponly: bool = True,
+        default_locale: Optional[Locale] = None,
+    ):
+        self._cookie_name = cookie_name
+        self._max_age = cookie_max_age
+        self._path = cookie_path
+        self._domain = cookie_domain
+        self._secure = cookie_secure
+        self._httponly = cookie_httponly
+        self._default = default_locale if default_locale is not None else Locale("")
+
+    def resolve_locale(self, request) -> LocaleContext:
+        cookies = _get_cookies(request)
+        loc_str = cookies.get(self._cookie_name) if cookies else None
+        if loc_str:
+            return SimpleLocaleContext(Locale.parse(loc_str))
+        return SimpleLocaleContext(self._default)
+
+    def set_locale_context(self, request, response, context: LocaleContext) -> None:
+        _set_cookie(
+            response,
+            name=self._cookie_name,
+            value=context.get_locale().to_language_tag(),
+            max_age=self._max_age,
+            path=self._path,
+            domain=self._domain,
+            secure=self._secure,
+            httponly=self._httponly,
+        )
+
+
+# ==================== Starlette Request/Response 兼容工具 ====================
+
+def _get_header(request, name: str, default: str) -> str:
+    """从请求对象取头；兼容 Starlette ``Request`` 与 dict-like。"""
+    if request is None:
+        return default
+    headers = getattr(request, "headers", None)
+    if headers is None:
+        return default
+    try:
+        # Starlette Headers 对象支持 .get 大小写不敏感
+        return headers.get(name, default)
+    except AttributeError:
+        try:
+            return dict(headers).get(name, default)
+        except Exception:
+            return default
+
+
+def _get_session(request):
+    """获取 Starlette ``request.session``；不存在返回 None。"""
+    if request is None:
+        return None
+    return getattr(request, "session", None)
+
+
+def _get_cookies(request):
+    """获取 Starlette ``request.cookies``；不存在返回 None。"""
+    if request is None:
+        return None
+    cookies = getattr(request, "cookies", None)
+    if cookies is None:
+        return None
+    try:
+        return dict(cookies)
+    except Exception:
+        return cookies
+
+
+def _set_cookie(response, name: str, value: str, max_age: int, path: str,
+                domain: Optional[str], secure: bool, httponly: bool) -> None:
+    """写回 Cookie；兼容 Starlette ``Response`` 与自定义响应对象。"""
+    if response is None:
+        return
+    set_cookie = getattr(response, "set_cookie", None)
+    if callable(set_cookie):
+        set_cookie(
+            key=name, value=value, max_age=max_age, path=path,
+            domain=domain, secure=secure, httponly=httponly,
+        )
+        return
+    # 兜底：手动拼 Set-Cookie 头
+    parts = [f"{name}={value}", f"Path={path}", f"Max-Age={max_age}"]
+    if domain:
+        parts.append(f"Domain={domain}")
+    if secure:
+        parts.append("Secure")
+    if httponly:
+        parts.append("HttpOnly")
+    headers = getattr(response, "headers", None)
+    if headers is not None:
+        try:
+            headers.append("set-cookie", "; ".join(parts))
+        except AttributeError:
+            pass
+
+
+__all__ = [
+    "LocaleContext",
+    "SimpleLocaleContext",
+    "SimpleTimeZoneAwareLocaleContext",
+    "LocaleResolver",
+    "AcceptHeaderLocaleResolver",
+    "FixedLocaleResolver",
+    "SessionLocaleResolver",
+    "CookieLocaleResolver",
+    "parse_accept_language",
+]

spring/i18n/message_source.py

@@ -0,0 +1,250 @@
+"""``MessageSource`` 接口与抽象基类（对齐 Spring ``org.springframework.context.MessageSource``）。
+
+核心抽象：
+- ``MessageSource``：策略接口，按 ``code`` + ``Locale`` 解析消息。
+- ``AbstractMessageSource``：实现公共逻辑——参数格式化、默认消息回退、父级委派、
+  ``MessageSourceResolvable`` 多 code 解析。子类只需实现 ``resolve_code``。
+- ``NoSuchMessageException``：找不到消息时抛出（对齐 Spring 同名异常）。
+- ``MessageSourceResolvable`` / ``DefaultMessageSourceResolvable``：多 code + 参数 + 默认消息
+  的可解析对象，用于 ``ObjectError``/``FieldError`` 等校验场景。
+
+消息格式（对齐 ``java.text.MessageFormat`` 的常见用法）：
+- 位置占位符 ``{0}``/``{1}``：用 ``args`` 列表按序替换。
+- 类型子模式 ``{0,number,#.##}``：忽略类型符，等价于 ``{0}``（Python 无等价格式化）。
+- 关键字占位符 ``{name}``：当 ``args`` 为字典时使用。
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable, List, Optional, Sequence, Union
+
+from .locale import Locale
+
+
+class NoSuchMessageException(Exception):
+    """找不到消息时抛出（对齐 Spring ``NoSuchMessageException``）。"""
+
+    def __init__(self, code: str, locale: Optional[Locale] = None):
+        self.code = code
+        self.locale = locale
+        loc_str = locale.to_string() if locale else "default"
+        super().__init__(f"No message found under code '{code}' for locale '{loc_str}'.")
+
+
+# ==================== 消息参数类型 ====================
+# args 可以是：列表/元组（位置参数 {0}{1}），或字典（关键字参数 {name}）
+MessageArgs = Optional[Union[Sequence[Any], dict]]
+
+
+# ==================== MessageFormat 兼容格式化 ====================
+
+# 匹配 {0}、{1,number}、{0,date,yyyy-MM-dd} 等 Java MessageFormat 占位符
+_JAVA_MSGFMT = re.compile(r"\{(\d+)(?:,[a-zA-Z]+(?:,[^}]+)?)?\}")
+
+
+def _format_message(template: str, args: MessageArgs, locale: Optional[Locale]) -> str:
+    """按 Java ``MessageFormat`` 兼容方式格式化模板。
+
+    - ``args`` 为列表/元组：用 ``{0}``/``{1}`` 位置替换；同时剥离 Java 类型子模式
+      （``{0,number}`` → ``{0}``），使其兼容 ``str.format``。
+    - ``args`` 为字典：用 ``{name}`` 关键字替换（不支持 Java 类型子模式）。
+    - ``args`` 为 None：原样返回。
+    - 格式化失败（参数不足/类型不匹配）原样返回模板，避免抛异常（对齐 Spring 容错）。
+    """
+    if args is None:
+        return template
+    try:
+        if isinstance(args, dict):
+            return template.format(**args)
+        # 序列：先剥离 Java 类型子模式，再 str.format
+        seq = list(args)
+        stripped = _JAVA_MSGFMT.sub(r"{\1}", template)
+        return stripped.format(*seq)
+    except (IndexError, KeyError, ValueError, TypeError):
+        return template
+
+
+# ==================== MessageSourceResolvable ====================
+
+class MessageSourceResolvable:
+    """可解析消息对象（对齐 Spring ``MessageSourceResolvable``）。
+
+    持有多个候选 ``codes``（按优先级降序）、可选 ``arguments``、可选默认消息。
+    ``MessageSource.getMessage(resolvable, locale)`` 会按顺序尝试每个 code，第一个命中即返回。
+    """
+
+    def __init__(
+        self,
+        codes: Optional[Sequence[str]],
+        arguments: MessageArgs = None,
+        default_message: Optional[str] = None,
+    ):
+        self.codes: List[str] = list(codes) if codes else []
+        self.arguments = arguments
+        self.default_message = default_message
+
+    def get_codes(self) -> List[str]:
+        return self.codes
+
+    def get_arguments(self) -> MessageArgs:
+        return self.arguments
+
+    def get_default_message(self) -> Optional[str]:
+        return self.default_message
+
+
+class DefaultMessageSourceResolvable(MessageSourceResolvable):
+    """``MessageSourceResolvable`` 的默认实现（对齐 Spring 同名类）。"""
+
+    def __init__(
+        self,
+        codes: Optional[Sequence[str]],
+        arguments: MessageArgs = None,
+        default_message: Optional[str] = None,
+    ):
+        super().__init__(codes, arguments, default_message)
+
+
+# ==================== MessageSource 接口 ====================
+
+class MessageSource:
+    """消息源策略接口（对齐 Spring ``MessageSource``）。
+
+    子类必须实现 ``resolve_code``；本类提供 ``getMessage`` 的公共入口与默认消息回退逻辑。
+    """
+
+    def getMessage(  # noqa: N802 - 保留 Java 驼峰命名以对齐 Spring API
+        self,
+        code: str,
+        args: MessageArgs = None,
+        locale: Optional[Locale] = None,
+    ) -> str:
+        """按 ``code`` + ``locale`` 解析消息，找不到抛 ``NoSuchMessageException``。"""
+        msg = self._resolve_with_fallback(code, args, locale, default=None)
+        if msg is None:
+            raise NoSuchMessageException(code, locale)
+        return msg
+
+    def getMessageOrDefault(  # 便利方法，Python 风格命名
+        self,
+        code: str,
+        args: MessageArgs = None,
+        default_message: Optional[str] = None,
+        locale: Optional[Locale] = None,
+    ) -> Optional[str]:
+        """按 ``code`` + ``locale`` 解析消息，找不到返回 ``default_message``（None 表示无默认）。"""
+        return self._resolve_with_fallback(code, args, locale, default=default_message)
+
+    def getMessageFromResolvable(  # 对齐 Spring ``getMessage(resolvable, locale)``
+        self,
+        resolvable: MessageSourceResolvable,
+        locale: Optional[Locale] = None,
+    ) -> str:
+        """按 ``resolvable.codes`` 顺序解析；全部未命中时返回 ``default_message``，
+        若默认消息为 None 则抛 ``NoSuchMessageException``。"""
+        loc = locale or Locale("")
+        for code in resolvable.get_codes():
+            msg = self._resolve_with_fallback(code, resolvable.get_arguments(), loc, default=None)
+            if msg is not None:
+                return msg
+        default = resolvable.get_default_message()
+        if default is not None:
+            return _format_message(default, resolvable.get_arguments(), loc)
+        raise NoSuchMessageException(resolvable.get_codes()[0] if resolvable.get_codes() else "",
+                                     loc)
+
+    # ==================== 子类实现点 ====================
+
+    def resolve_code(self, code: str, locale: Locale) -> Optional[str]:
+        """子类实现：返回原始（未格式化）消息模板，找不到返回 None。
+
+        默认实现总是返回 None（等价于空消息源）。
+        """
+        return None
+
+    # ==================== 内部 ====================
+
+    def _resolve_with_fallback(
+        self,
+        code: str,
+        args: MessageArgs,
+        locale: Optional[Locale],
+        default: Optional[str],
+    ) -> Optional[str]:
+        loc = locale or Locale("")
+        msg = self.resolve_code(code, loc)
+        if msg is None:
+            return default
+        return _format_message(msg, args, loc)
+
+
+# ==================== AbstractMessageSource ====================
+
+class AbstractMessageSource(MessageSource):
+    """``MessageSource`` 抽象基类（对齐 Spring ``AbstractMessageSource``）。
+
+    扩展点：
+    - ``resolve_code``：子类必须覆盖，返回原始消息模板。
+    - ``resolve_code_without_args``：可选覆盖，返回无参数消息模板（默认走 ``resolve_code``）。
+
+    特性：
+    - ``parent_message_source``：父消息源；当前未命中时委派父级。
+    - ``use_code_as_default_message``：找不到时把 ``code`` 作为默认消息（不抛异常）。
+      对齐 Spring ``AbstractMessageSource.setUseCodeAsDefaultMessage``。
+    """
+
+    def __init__(self, parent: Optional[MessageSource] = None):
+        self._parent: Optional[MessageSource] = parent
+        self._use_code_as_default_message: bool = False
+
+    @property
+    def parent_message_source(self) -> Optional[MessageSource]:
+        return self._parent
+
+    @parent_message_source.setter
+    def parent_message_source(self, value: Optional[MessageSource]) -> None:
+        self._parent = value
+
+    def set_use_code_as_default_message(self, flag: bool) -> None:
+        self._use_code_as_default_message = flag
+
+    def resolve_code_without_args(self, code: str, locale: Locale) -> Optional[str]:
+        """无参数解析（子类可覆盖以优化性能）。默认走 ``resolve_code``。"""
+        return self.resolve_code(code, locale)
+
+    def resolve_code(self, code: str, locale: Locale) -> Optional[str]:  # 子类覆盖
+        return None
+
+    # ==================== 重写公共入口，加入父级委派 ====================
+
+    def _resolve_with_fallback(
+        self,
+        code: str,
+        args: MessageArgs,
+        locale: Optional[Locale],
+        default: Optional[str],
+    ) -> Optional[str]:
+        loc = locale or Locale("")
+        # 1. 当前消息源
+        if args is None:
+            msg = self.resolve_code_without_args(code, loc)
+        else:
+            msg = self.resolve_code(code, loc)
+        # 2. 父级委派
+        if msg is None and self._parent is not None:
+            return self._parent.getMessageOrDefault(code, args, default, loc)
+        if msg is None:
+            if self._use_code_as_default_message:
+                return code
+            return default
+        return _format_message(msg, args, loc)
+
+
+__all__ = [
+    "NoSuchMessageException",
+    "MessageArgs",
+    "MessageSourceResolvable",
+    "DefaultMessageSourceResolvable",
+    "MessageSource",
+    "AbstractMessageSource",
+]

spring/i18n/middleware.py

@@ -0,0 +1,79 @@
+"""``LocaleResolverMiddleware`` Starlette 中间件（对齐 Spring ``LocaleChangeInterceptor`` +
+``DispatcherServlet`` 的 locale 解析逻辑）。
+
+中间件在每个请求开始时：
+1. 用配置的 ``LocaleResolver`` 从请求解析 ``LocaleContext``；
+2. 写入 ``LocaleContextHolder``（``ContextVar``，协程安全）；
+3. 把 ``LocaleContext`` 挂到 ``request.state.locale_context`` 供后续路由读取；
+4. 请求结束 ``reset_locale_context()``，避免泄漏。
+
+中间件不依赖 FastAPI，仅依赖 Starlette ``BaseHTTPMiddleware`` / ``Request``。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+
+from .holder import LocaleContextHolder
+from .locale import Locale
+from .locale_resolver import (
+    AcceptHeaderLocaleResolver,
+    LocaleContext,
+    LocaleResolver,
+    SimpleLocaleContext,
+)
+
+
+class LocaleResolverMiddleware(BaseHTTPMiddleware):
+    """HTTP 中间件：解析 locale 并写入 ``LocaleContextHolder``。
+
+    Args:
+        app:             ASGI 应用。
+        locale_resolver: 区域解析器；默认 ``AcceptHeaderLocaleResolver``。
+    """
+
+    def __init__(self, app, locale_resolver: Optional[LocaleResolver] = None):
+        super().__init__(app)
+        self._resolver: LocaleResolver = locale_resolver or AcceptHeaderLocaleResolver()
+
+    @property
+    def locale_resolver(self) -> LocaleResolver:
+        return self._resolver
+
+    async def dispatch(self, request: Request, call_next):
+        # 1. 解析 locale
+        try:
+            context = self._resolver.resolve_locale(request)
+        except Exception:
+            # 解析失败兜底：空 locale，避免中间件把请求 500
+            context = SimpleLocaleContext(Locale(""))
+        # 2. 写入 ContextVar（协程安全），返回 token 用于精确复位（支持嵌套）
+        token = LocaleContextHolder.set_locale_context(context)
+        # 3. 挂到 request.state 供路由读取
+        try:
+            request.state.locale_context = context
+        except Exception:
+            pass
+        try:
+            response = await call_next(request)
+        finally:
+            # 4. 请求结束用 token 复位（即使异常也复位，支持嵌套调用）
+            LocaleContextHolder.reset_locale_context(token)
+        return response
+
+
+def get_request_locale(request: Optional[Request]) -> Locale:
+    """从请求 ``state.locale_context`` 或 ``LocaleContextHolder`` 取当前 locale。
+
+    优先级：``request.state.locale_context`` > ``LocaleContextHolder`` > 空 ``Locale``。
+    """
+    if request is not None:
+        ctx = getattr(getattr(request, "state", None), "locale_context", None)
+        if isinstance(ctx, LocaleContext):
+            return ctx.get_locale()
+    return LocaleContextHolder.get_locale()
+
+
+__all__ = ["LocaleResolverMiddleware", "get_request_locale"]