springbootAI 1.8.0__py3-none-any.whl

spring/i18n/__init__.py

@@ -0,0 +1,97 @@
+"""SpringBootAI i18n 国际化模块 —— 注解驱动的消息源与区域解析（对齐 Spring ``MessageSource`` +
+``LocaleResolver`` 体系）。
+
+模块组成（镜像 ``org.springframework.context.*`` / ``org.springframework.web.servlet.i18n.*``）：
+
+- **locale**:          ``Locale`` 区域对象（``language``/``country``/``variant``），对齐
+                        ``java.util.Locale`` 的字符串表示（``en``/``en_US``/``zh_CN``）
+- **message_source**:  ``MessageSource`` 接口 + ``AbstractMessageSource`` 抽象基类 +
+                        ``NoSuchMessageException`` + ``MessageSourceResolvable``
+- **sources**:         ``StaticMessageSource``（编程式）/ ``ResourceBundleMessageSource``
+                        （资源包加载，支持 ``.properties`` 与 ``.yml``）/ ``DelegatingMessageSource``
+                        （父级回退，对齐 ``AbstractApplicationContext`` 的内嵌实现）
+- **locale_resolver**: ``LocaleResolver`` 接口 + ``LocaleContext`` + ``AcceptHeaderLocaleResolver``
+                        / ``FixedLocaleResolver`` / ``SessionLocaleResolver`` / ``CookieLocaleResolver``
+- **holder**:          ``LocaleContextHolder`` 线程/协程安全上下文持有器（``ContextVar``）
+- **accessor**:        ``MessageSourceAccessor`` 便捷访问器（提供无异常 ``getMessage`` 变体）
+- **properties**:      Java 风格 ``.properties`` 文件解析器（UTF-8，支持转义/续行）
+- **middleware**:      ``LocaleResolverMiddleware`` Starlette 中间件，从请求解析并设置 ``LocaleContext``
+- **auto_config**:     ``MessageSourceAutoConfiguration`` 默认装配（``spring.messages.basename``）
+
+设计原则：**复用项目既有范式，不重复造轮子**。本模块：
+- 不依赖任何第三方库（``.properties`` 解析自实现，``.yml`` 复用项目核心依赖 ``pyyaml``）。
+- 注解描述符范式与 ``spring.excel`` / ``spring.csv`` 一致。
+- ``LocaleContextHolder`` 复用 ``ContextVar`` 模式，与 ``spring.datasource`` 动态路由一致。
+
+与 Java 的差异：
+- Spring 用 ``ResourceBundle`` 加载类路径资源；本实现用文件系统路径 + ``basenames`` 列表。
+- ``MessageFormat`` 类型子模式（``{0,number,#.##}``）降级为 ``str.format``，类型符忽略；
+  位置占位符 ``{0}``/``{1}`` 与 Java 行为一致。
+- 不支持 ``ResourceBundle.Control`` 自定义加载策略（可按需扩展）。
+"""
+from .locale import (
+    Locale,
+    LOCALE_EN, LOCALE_US, LOCALE_UK,
+    LOCALE_CHINA, LOCALE_TAIWAN, LOCALE_JAPAN, LOCALE_KOREA,
+    LOCALE_GERMANY, LOCALE_FRANCE,
+    parse_locale,
+)
+from .message_source import (
+    MessageSource,
+    AbstractMessageSource,
+    NoSuchMessageException,
+    MessageSourceResolvable,
+    DefaultMessageSourceResolvable,
+)
+from .sources import (
+    StaticMessageSource,
+    ResourceBundleMessageSource,
+    DelegatingMessageSource,
+)
+from .locale_resolver import (
+    LocaleResolver,
+    LocaleContext,
+    SimpleLocaleContext,
+    SimpleTimeZoneAwareLocaleContext,
+    AcceptHeaderLocaleResolver,
+    FixedLocaleResolver,
+    SessionLocaleResolver,
+    CookieLocaleResolver,
+    parse_accept_language,
+)
+from .holder import LocaleContextHolder
+from .accessor import MessageSourceAccessor
+from .properties import load_properties, parse_properties
+from .middleware import LocaleResolverMiddleware, get_request_locale
+from .auto_config import MessageSourceAutoConfiguration, configure_message_source
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Locale
+    "Locale",
+    "LOCALE_EN", "LOCALE_US", "LOCALE_UK",
+    "LOCALE_CHINA", "LOCALE_TAIWAN", "LOCALE_JAPAN", "LOCALE_KOREA",
+    "LOCALE_GERMANY", "LOCALE_FRANCE",
+    "parse_locale",
+    # MessageSource
+    "MessageSource", "AbstractMessageSource",
+    "NoSuchMessageException", "MessageSourceResolvable", "DefaultMessageSourceResolvable",
+    # Sources
+    "StaticMessageSource", "ResourceBundleMessageSource", "DelegatingMessageSource",
+    # LocaleResolver
+    "LocaleResolver", "LocaleContext", "SimpleLocaleContext",
+    "SimpleTimeZoneAwareLocaleContext",
+    "AcceptHeaderLocaleResolver", "FixedLocaleResolver",
+    "SessionLocaleResolver", "CookieLocaleResolver",
+    "parse_accept_language",
+    # Holder / Accessor
+    "LocaleContextHolder", "MessageSourceAccessor",
+    # Properties
+    "load_properties", "parse_properties",
+    # Middleware
+    "LocaleResolverMiddleware", "get_request_locale",
+    # Auto config
+    "MessageSourceAutoConfiguration", "configure_message_source",
+    "__version__",
+]

spring/i18n/accessor.py

@@ -0,0 +1,94 @@
+"""``MessageSourceAccessor`` 便捷访问器（对齐 Spring ``MessageSourceAccessor``）。
+
+包装一个 ``MessageSource`` + 默认 ``Locale``，提供更简洁的 API：
+
+- ``getMessage(code, args, locale)``           — 抛异常变体
+- ``getMessage(code, args, default, locale)``  — 默认消息变体
+- ``getMessage(resolvable, locale)``           — resolvable 变体
+
+所有 ``locale`` 参数可选，缺省用构造时传入的默认 locale（对齐 Spring 同名行为）。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .locale import Locale
+from .message_source import (
+    MessageArgs,
+    MessageSource,
+    MessageSourceResolvable,
+    NoSuchMessageException,
+)
+
+
+class MessageSourceAccessor:
+    """``MessageSource`` 便捷访问器。
+
+    Args:
+        message_source: 被包装的消息源。
+        default_locale: 默认 locale（请求未指定时使用）。
+    """
+
+    def __init__(self, message_source: MessageSource, default_locale: Optional[Locale] = None):
+        self._source = message_source
+        self._default_locale = default_locale if default_locale is not None else Locale("")
+
+    @property
+    def message_source(self) -> MessageSource:
+        return self._source
+
+    @property
+    def default_locale(self) -> Locale:
+        return self._default_locale
+
+    def set_default_locale(self, locale: Locale) -> None:
+        self._default_locale = locale
+
+    # ==================== 便捷方法 ====================
+
+    def getMessage(  # noqa: N802 - 保留 Java 驼峰命名以对齐 Spring API
+        self,
+        code: str,
+        args: MessageArgs = None,
+        locale: Optional[Locale] = None,
+    ) -> str:
+        """按 code 解析消息，找不到抛 ``NoSuchMessageException``。"""
+        return self._source.getMessage(code, args, self._locale(locale))
+
+    def getMessageOrDefault(
+        self,
+        code: str,
+        args: MessageArgs = None,
+        default_message: Optional[str] = None,
+        locale: Optional[Locale] = None,
+    ) -> Optional[str]:
+        """按 code 解析消息，找不到返回 ``default_message``。"""
+        return self._source.getMessageOrDefault(code, args, default_message, self._locale(locale))
+
+    def getMessageFromResolvable(
+        self,
+        resolvable: MessageSourceResolvable,
+        locale: Optional[Locale] = None,
+    ) -> str:
+        return self._source.getMessageFromResolvable(resolvable, self._locale(locale))
+
+    # 别名（Python 风格）
+    def get_message(self, code: str, args: MessageArgs = None, locale: Optional[Locale] = None) -> str:
+        return self.getMessage(code, args, locale)
+
+    def get_message_or_default(
+        self,
+        code: str,
+        args: MessageArgs = None,
+        default_message: Optional[str] = None,
+        locale: Optional[Locale] = None,
+    ) -> Optional[str]:
+        return self.getMessageOrDefault(code, args, default_message, locale)
+
+    # ==================== 内部 ====================
+
+    def _locale(self, locale: Optional[Locale]) -> Locale:
+        return locale if locale is not None else self._default_locale
+
+
+__all__ = ["MessageSourceAccessor"]

spring/i18n/auto_config.py

@@ -0,0 +1,177 @@
+"""``MessageSourceAutoConfiguration`` 默认装配（对齐 Spring Boot
+``MessageSourceAutoConfiguration``）。
+
+从 ``application.yml`` 读取 ``spring.messages.basename`` / ``spring.messages.encoding``
+等配置，构造默认 ``ResourceBundleMessageSource`` 并注册为容器单例 Bean。
+
+配置示例（``application.yml``）::
+
+    spring:
+      messages:
+        basename: messages,errors     # 资源基名列表（逗号分隔），默认 messages
+        encoding: UTF-8                # 资源文件编码，默认 UTF-8
+        base-dir: classpath:i18n       # 资源根目录，默认 classpath:i18n
+        fallback-to-system-locale: true
+        use-code-as-default-message: false
+
+``base-dir`` 取值：
+- ``classpath:xxx`` → 相对当前工作目录的 ``xxx`` 子目录（对齐 Spring ``classpath:`` 前缀语义）
+- 绝对/相对路径 → 直接使用
+- 未配置 → 默认 ``i18n``（即 ``./i18n/messages_*.properties``）
+
+集成方式：
+1. ``configure_message_source(config_loader)`` 工厂函数：从配置构造消息源。
+2. ``ApplicationContext`` 启动时调用本模块注册 ``messageSource`` Bean（见下方钩子）。
+3. 应用层通过 ``context.get_bean("messageSource")`` 或 ``get_bean_by_type(MessageSource)`` 获取。
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Iterable, List, Optional
+
+from .locale import Locale
+from .message_source import MessageSource
+from .sources import ResourceBundleMessageSource
+
+
+# Bean 名称（对齐 Spring ``messageSource``）
+MESSAGE_SOURCE_BEAN_NAME = "messageSource"
+
+
+def _split_basenames(raw: str) -> List[str]:
+    """逗号分隔的 basename 列表解析；去除空白与空项。"""
+    if not raw:
+        return ["messages"]
+    return [b.strip() for b in raw.split(",") if b.strip()]
+
+
+def _resolve_base_dir(raw: str) -> str:
+    """解析 ``base-dir`` 配置。
+
+    - ``classpath:xxx`` → ``xxx``（相对工作目录；Spring ``classpath:`` 在此实现为文件系统等价）
+    - 其他 → 原样返回
+    - 未提供 → ``i18n``
+    """
+    if not raw:
+        return "i18n"
+    if raw.startswith("classpath:"):
+        return raw[len("classpath:"):]
+    return raw
+
+
+def configure_message_source(
+    config_loader: Optional[Any] = None,
+    basenames: Optional[Iterable[str]] = None,
+    base_dir: Optional[str] = None,
+    encoding: Optional[str] = None,
+    fallback_to_system_locale: Optional[bool] = None,
+    use_code_as_default_message: Optional[bool] = None,
+    default_locale: Optional[Locale] = None,
+) -> ResourceBundleMessageSource:
+    """从 ``config_loader`` 与显式参数构造 ``ResourceBundleMessageSource``。
+
+    优先级：显式参数 > ``config_loader`` 读取的 ``spring.messages.*`` > 默认值。
+
+    Args:
+        config_loader:                ``spring.config.ConfigLoader`` 实例（可为 None）。
+        basenames:                    资源基名列表。
+        base_dir:                     资源根目录。
+        encoding:                     资源编码。
+        fallback_to_system_locale:    locale 未命中是否回退到系统 locale。
+        use_code_as_default_message:  找不到消息时是否把 code 作为默认消息。
+        default_locale:               默认 locale。
+
+    Returns:
+        配置好的 ``ResourceBundleMessageSource`` 单例（每次调用返回新实例）。
+    """
+    # 从 config_loader 读取默认值
+    cfg_basenames = ["messages"]
+    cfg_base_dir = "i18n"
+    cfg_encoding = "utf-8"
+    cfg_fallback = True
+    cfg_use_code = False
+
+    if config_loader is not None:
+        try:
+            msgs_cfg = config_loader.get_prefix_config("spring.messages") or {}
+            if msgs_cfg.get("basename"):
+                cfg_basenames = _split_basenames(msgs_cfg["basename"])
+            if msgs_cfg.get("base-dir") or msgs_cfg.get("base_dir"):
+                cfg_base_dir = _resolve_base_dir(
+                    msgs_cfg.get("base-dir") or msgs_cfg.get("base_dir")
+                )
+            if msgs_cfg.get("encoding"):
+                cfg_encoding = msgs_cfg["encoding"]
+            if msgs_cfg.get("fallback-to-system-locale") is not None:
+                cfg_fallback = bool(msgs_cfg.get("fallback-to-system-locale"))
+            if msgs_cfg.get("use-code-as-default-message") is not None:
+                cfg_use_code = bool(msgs_cfg.get("use-code-as-default-message"))
+        except Exception:
+            # 配置缺失或异常：用默认值
+            pass
+
+    final_basenames = list(basenames) if basenames is not None else cfg_basenames
+    final_base_dir = base_dir if base_dir is not None else cfg_base_dir
+    final_encoding = encoding if encoding is not None else cfg_encoding
+    final_fallback = fallback_to_system_locale if fallback_to_system_locale is not None else cfg_fallback
+    final_use_code = use_code_as_default_message if use_code_as_default_message is not None else cfg_use_code
+    final_default_locale = default_locale if default_locale is not None else Locale("")
+
+    source = ResourceBundleMessageSource(
+        basenames=final_basenames,
+        base_dir=final_base_dir,
+        default_encoding=final_encoding,
+        fallback_to_system_locale=final_fallback,
+        default_locale=final_default_locale,
+    )
+    if final_use_code:
+        source.set_use_code_as_default_message(True)
+    return source
+
+
+class MessageSourceAutoConfiguration:
+    """消息源自动配置（对齐 Spring Boot ``MessageSourceAutoConfiguration``）。
+
+    静态方法 ``register(context)``：从 ``context.config_loader`` 读取配置，构造
+    ``ResourceBundleMessageSource`` 并注册为 ``messageSource`` Bean。若已存在同名 Bean 则跳过。
+    """
+
+    @staticmethod
+    def register(context: Any) -> Optional[MessageSource]:
+        """向 ``ApplicationContext`` 注册 ``messageSource`` Bean。
+
+        Returns:
+            注册的消息源实例；若已存在同名 Bean 则返回该实例。
+        """
+        bean_factory = getattr(context, "bean_factory", None) or getattr(context, "_bean_factory", None)
+        if bean_factory is None:
+            return None
+        # 已存在同名 Bean：跳过（对齐 Spring ``@ConditionalOnMissingBean``）
+        existing = bean_factory._bean_definitions.get(MESSAGE_SOURCE_BEAN_NAME) \
+            if hasattr(bean_factory, "_bean_definitions") else None
+        if existing is not None:
+            try:
+                return bean_factory.get_bean(MESSAGE_SOURCE_BEAN_NAME)
+            except Exception:
+                return None
+
+        config_loader = getattr(context, "config_loader", None)
+        source = configure_message_source(config_loader)
+
+        # 注册为实例（BeanFactory.register_instance 直接放 _bean_instances）
+        try:
+            bean_factory.register_instance(MESSAGE_SOURCE_BEAN_NAME, source)
+            # 同步 type_to_name 索引（register_instance 已做，保险起见）
+            from .message_source import MessageSource as _MS
+            bean_factory._type_to_name.setdefault(_MS, MESSAGE_SOURCE_BEAN_NAME)
+            bean_factory._type_to_name.setdefault(ResourceBundleMessageSource, MESSAGE_SOURCE_BEAN_NAME)
+        except Exception:
+            pass
+        return source
+
+
+__all__ = [
+    "MESSAGE_SOURCE_BEAN_NAME",
+    "configure_message_source",
+    "MessageSourceAutoConfiguration",
+]

spring/i18n/holder.py

@@ -0,0 +1,106 @@
+"""``LocaleContextHolder`` 区域上下文持有器（对齐 Spring ``LocaleContextHolder``）。
+
+使用 ``ContextVar`` 保证线程与 ``asyncio`` 协程间的隔离（与 ``spring.datasource`` 动态路由
+的 ``ContextVar`` 模式一致）。
+
+核心 API：
+- ``set_locale_context(ctx)`` / ``get_locale_context()``：设置/获取 ``LocaleContext``
+  - ``set_locale_context`` 返回 token，可用 ``reset_locale_context(token)`` 精确复位
+- ``set_locale(locale)`` / ``get_locale()``：便捷方法，等价于包装/解包 ``SimpleLocaleContext``
+- ``reset_locale_context(token=None)``：清除当前上下文（对齐 Spring ``resetLocaleContext``）
+- ``set_default_locale(locale)``：设置全局默认 locale（对齐 Spring 同名静态方法）
+
+嵌套调用：``ContextVar.reset(token)`` 天然支持嵌套——内层请求退出后自动恢复外层 locale，
+与 ``spring.datasource.DataSourceContextHolder`` 完全一致。
+"""
+from __future__ import annotations
+
+import contextvars
+import threading
+from typing import Optional
+
+from .locale import Locale
+from .locale_resolver import LocaleContext, SimpleLocaleContext
+
+
+# ContextVar：协程安全 + 线程安全（Python 3.10+ 推荐）
+_locale_context_var: "contextvars.ContextVar[Optional[LocaleContext]]" = contextvars.ContextVar(
+    "spring_locale_context", default=None
+)
+
+# 全局默认 locale（进程级，所有线程/协程共享）
+_default_locale_lock = threading.Lock()
+_default_locale: Optional[Locale] = None
+
+
+class LocaleContextHolder:
+    """区域上下文持有器（对齐 Spring ``LocaleContextHolder``）。
+
+    所有方法均为 ``@staticmethod``，状态保存在 ``ContextVar`` 与全局默认变量中。
+    """
+
+    @staticmethod
+    def set_locale_context(context: Optional[LocaleContext]):
+        """设置当前上下文的 ``LocaleContext``；``None`` 等价于清除。
+
+        返回 ``ContextVar.set`` 的 token，可用 ``reset_locale_context(token)`` 精确复位。
+        """
+        return _locale_context_var.set(context)
+
+    @staticmethod
+    def get_locale_context() -> LocaleContext:
+        """获取当前 ``LocaleContext``；不存在时返回 ``SimpleLocaleContext(default_locale)``。"""
+        ctx = _locale_context_var.get()
+        if ctx is not None:
+            return ctx
+        return SimpleLocaleContext(LocaleContextHolder.get_default_locale())
+
+    @staticmethod
+    def set_locale(locale: Optional[Locale]):
+        """便捷方法：用 ``SimpleLocaleContext`` 包装 locale 设置到上下文。返回 token。"""
+        return LocaleContextHolder.set_locale_context(
+            SimpleLocaleContext(locale) if locale is not None else None
+        )
+
+    @staticmethod
+    def get_locale() -> Locale:
+        """获取当前 locale；上下文未设置时返回全局默认 locale（可能为空 ``Locale``）。"""
+        return LocaleContextHolder.get_locale_context().get_locale()
+
+    @staticmethod
+    def reset_locale_context(token=None) -> None:
+        """清除当前上下文（对齐 Spring ``resetLocaleContext``）。
+
+        - 传入 ``token``：精确复位到 ``set_locale_context`` 之前的值（支持嵌套）。
+        - 不传 ``token``：直接置为 None（慎用，会丢失嵌套层级）。
+        """
+        if token is not None:
+            try:
+                _locale_context_var.reset(token)
+                return
+            except (ValueError, LookupError):
+                # token 不属于当前上下文（跨协程误用），兜底置 None
+                pass
+        _locale_context_var.set(None)
+
+    # 兼容简短别名
+    @staticmethod
+    def reset(token=None) -> None:
+        LocaleContextHolder.reset_locale_context(token)
+
+    @staticmethod
+    def set_default_locale(locale: Optional[Locale]) -> None:
+        """设置进程级默认 locale；未设置上下文时 ``get_locale`` 返回此值。"""
+        global _default_locale
+        with _default_locale_lock:
+            _default_locale = locale
+
+    @staticmethod
+    def get_default_locale() -> Locale:
+        """获取进程级默认 locale；未设置返回空 ``Locale``。"""
+        with _default_locale_lock:
+            loc = _default_locale
+        return loc if loc is not None else Locale()
+
+
+__all__ = ["LocaleContextHolder"]

spring/i18n/locale.py

@@ -0,0 +1,152 @@
+"""``Locale`` 区域对象（对齐 ``java.util.Locale``）。
+
+表示一个特定的地理、政治或文化区域。本实现采用最常见的 ``language_country`` 字符串
+表示（如 ``en``/``en_US``/``zh_CN``），同时支持 BCP 47 语言标签（``en-US``/``zh-CN``）。
+
+与 Java 的差异：
+- Java ``Locale`` 是不可变重量级对象（含 ``Locale.Builder``）；本实现是轻量不可变 dataclass 风格。
+- 不支持 ``Locale.LanguageRange`` 列表解析的完整 RFC 4647 算法，仅实现最常见的
+  前缀匹配（``AcceptHeaderLocaleResolver`` 用）。
+- ``getDisplayLanguage`` 等显示名 API 不实现（依赖 ``Locale`` 数据集），使用方可按需扩展。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class Locale:
+    """不可变区域对象。
+
+    Args:
+        language: ISO 639 语言代码（小写，如 ``en``/``zh``）。
+        country:  ISO 3166 国家代码（大写，如 ``US``/``CN``）。可选。
+        variant:  变体（任意大小写，如 ``POSIX``/``Traditional_WIN``）。可选。
+
+    规范化：
+    - ``language`` 转小写；``country`` 转大写；``variant`` 保留原样。
+    - 空/None 视为未设置。
+    """
+
+    __slots__ = ("language", "country", "variant")
+
+    def __init__(self, language: str = "", country: str = "", variant: str = ""):
+        self.language = (language or "").lower()
+        self.country = (country or "").upper()
+        self.variant = variant or ""
+
+    # ==================== 工厂 ====================
+
+    @classmethod
+    def parse(cls, tag: str) -> "Locale":
+        """从字符串解析 ``Locale``，兼容以下格式：
+
+        - ``en`` / ``zh``                         → ``Locale("en")``
+        - ``en_US`` / ``zh_CN``                   → ``Locale("en", "US")``
+        - ``en_US_POSIX``                         → ``Locale("en", "US", "POSIX")``
+        - ``en-US`` / ``zh-CN``（BCP 47，``-`` 分隔）→ 同上
+        - ``en-US-x-posix``（BCP 47 私有用）        → variant 取最后一段
+        """
+        if not tag:
+            return cls()
+        tag = tag.strip()
+        # 统一分隔符：BCP 47 用 '-'，Java 用 '_'；优先拆 '_' 再拆 '-'
+        # 仅当不含 '_' 时才替换 '-'，避免误处理含 '_' 的 variant
+        if "_" in tag:
+            parts = tag.split("_")
+        elif "-" in tag:
+            parts = tag.split("-")
+        else:
+            parts = [tag]
+        language = parts[0] if len(parts) >= 1 else ""
+        country = parts[1] if len(parts) >= 2 else ""
+        # variant：第 3 段及以上拼接（Java 风格单段 variant 取最后一段即可）
+        variant = parts[2] if len(parts) >= 3 else ""
+        # 处理 BCP 47 扩展：x-private 子段拼到 variant
+        if len(parts) > 3:
+            variant = "_".join(parts[2:])
+        return cls(language, country, variant)
+
+    # ==================== 表示 ====================
+
+    def to_string(self) -> str:
+        """Java ``toString`` 风格：``en``/``en_US``/``en_US_POSIX``。"""
+        if self.variant:
+            return f"{self.language}_{self.country}_{self.variant}" if self.country else \
+                   f"{self.language}__{self.variant}"
+        if self.country:
+            return f"{self.language}_{self.country}"
+        return self.language
+
+    def to_language_tag(self) -> str:
+        """BCP 47 语言标签：``en``/``en-US``/``zh-CN``。"""
+        if self.variant:
+            return f"{self.language}-{self.country}-{self.variant}" if self.country else \
+                   f"{self.language}-x-{self.variant}"
+        if self.country:
+            return f"{self.language}-{self.country}"
+        return self.language
+
+    def __str__(self) -> str:
+        return self.to_string()
+
+    def __repr__(self) -> str:
+        return f"Locale({self.to_string()!r})"
+
+    # ==================== 比较 / 哈希 ====================
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Locale):
+            return NotImplemented
+        return (self.language, self.country, self.variant) == \
+               (other.language, other.country, other.variant)
+
+    def __hash__(self) -> int:
+        return hash((self.language, self.country, self.variant))
+
+    # ==================== 工具 ====================
+
+    @property
+    def is_empty(self) -> bool:
+        return not (self.language or self.country or self.variant)
+
+    def matches(self, other: "Locale") -> bool:
+        """前缀匹配：``Locale("en")`` matches ``Locale("en_US")``，反之不成立。
+
+        用于 ``AcceptHeaderLocaleResolver`` 的回退匹配。
+        """
+        if self.is_empty or other.is_empty:
+            return False
+        if self.language != other.language:
+            return False
+        if self.country and other.country and self.country != other.country:
+            return False
+        if self.country and not other.country:
+            return False  # self 更具体，不能 matches 更宽泛的 other
+        return True
+
+
+# ==================== 预定义常量（对齐 Java ``Locale.*``） ====================
+
+LOCALE_EN = Locale("en")
+LOCALE_US = Locale("en", "US")
+LOCALE_UK = Locale("en", "GB")
+LOCALE_CHINA = Locale("zh", "CN")
+LOCALE_TAIWAN = Locale("zh", "TW")
+LOCALE_JAPAN = Locale("ja", "JP")
+LOCALE_KOREA = Locale("ko", "KR")
+LOCALE_GERMANY = Locale("de", "DE")
+LOCALE_FRANCE = Locale("fr", "FR")
+
+
+def parse_locale(tag: str) -> Locale:
+    """``Locale.parse`` 的函数式别名。"""
+    return Locale.parse(tag)
+
+
+__all__ = [
+    "Locale",
+    "LOCALE_EN", "LOCALE_US", "LOCALE_UK",
+    "LOCALE_CHINA", "LOCALE_TAIWAN", "LOCALE_JAPAN", "LOCALE_KOREA",
+    "LOCALE_GERMANY", "LOCALE_FRANCE",
+    "parse_locale",
+]