api-key-manager 2.1.0__py3-none-any.whl

key_manager/detector.py

@@ -0,0 +1,335 @@
+import asyncio
+import re
+from .providers import PROVIDERS, KEY_PREFIX_MAP, PROVIDER_ERROR_SIGNATURES
+from .providers.models_registry import PROVIDER_MODELS
+
+# Extended key patterns for better detection
+KEY_PATTERNS = {
+    # AI Providers - unique prefixes for pattern detection
+    "sk-or-v1-": "openrouter",
+    "sk-ant-api03-": "anthropic",
+    "sk-proj-": "openai",
+    "sk-sp-": "dashscope",
+    "sk-kimi-": "kimi-coding",
+    "sk-cp-": "minimax-plan",
+    "ms-": "modelscope",
+    "AIza": "google",
+    "xai-": "grok",
+    "hf_": "huggingface",
+    "r8_": "replicate",
+    "pplx-": "perplexity",
+    "gsk_": "groq",
+    "fw_": "fireworks",
+    "poe-": "poe",
+    "AKID": "cstcloud",
+    "tp-": "mimo-plan",
+}
+
+
+# Scoring weights
+WEIGHT_SELF = 100      # Self-signature match = definitive
+WEIGHT_CROSS = 10      # Cross-signature match = ambiguous
+WEIGHT_RATE_LIMITED = 60  # 429 rate limited = medium confidence (lower than 200/401/403 but still usable)
+MIN_WIN_SCORE = 50     # Minimum score to declare a winner
+MIN_LEAD = 20          # Minimum lead over second place
+
+# Unique signatures that ONLY belong to one provider.
+# These are verified by actual API testing.
+UNIQUE_SIGNATURES: dict[str, list[str]] = {
+    # ═══ 国内服务商 ═══
+    # dashscope: 实际返回 "Incorrect API key provided. For details, see: https://help.aliyun.com/zh/model-studio/error-code#apikey-error"
+    "dashscope": ["model-studio", "modelstudio", "apikey-error"],
+    "dashscope-coding": ["aliyun", "model-studio", "modelstudio"],
+    # tencent-hunyuan: 实际返回 "Incorrect API key provided: sk-inval...You can find your API key at https://console.cloud.tencent.com/hunyuan/start"
+    "tencent-hunyuan": ["hunyuan", "console.cloud.tencent.com"],
+    "baichuan": ["baichuan-ai.com", "platform.baichuan-ai.com"],
+    # minimax: 实际返回 "authorized_error", "login fail"
+    "minimax": ["authorized_error", "login fail"],
+    "minimax-plan": ["authorized_error", "login fail"],
+    # yi: 实际返回 "Illegal ApiKey"
+    "yi": ["illegal apikey"],
+    # kimi: 实际返回 "invalid_authentication_error"
+    "kimi": ["invalid_authentication_error"],
+    "kimi-coding": ["invalid_authentication_error", "the api key appears to be invalid"],
+    # siliconflow: 实际返回 "Api key is invalid" (注意大小写)
+    "siliconflow": ["api key is invalid"],
+    # stepfun: 实际返回 "Incorrect API key provided" (与 dashscope 重复，用 type 区分)
+    "stepfun": ["incorrect api key provided", "invalid_api_key"],
+    # doubao: 实际返回 "AuthenticationError"
+    "doubao": ["authenticationerror"],
+    # infini: 实际返回 "请使用正确的api key进行请求"
+    "infini": ["请使用正确的api key进行请求"],
+    "infini-coding": ["请使用正确的api key进行请求"],
+    # zhipu: 实际返回 "令牌已过期或验证不正确"
+    "zhipu": ["令牌已过期或验证不正确"],
+    "zhipu-coding": ["令牌已过期或验证不正确"],
+    # mimo: 实际返回 "Invalid API Key", "Please provide valid API Key"
+    "mimo": ["invalid api key", "please provide valid api key"],
+    "mimo-plan": ["invalid api key", "please provide valid api key"],
+    # cstcloud: 实际返回 {"code":401,"message":"Unauthorized"}
+    "cstcloud": ["cstcloud", "zhongsuanyun"],
+    "modelscope": ["modelscope"],
+    "longcat": ["longcat"],
+    "ppio": ["ppio"],
+    # ═══ 国外服务商 ═══
+    # deepseek: 实际返回 "Authentication Fails, Your api key: ****2345 is invalid"
+    "deepseek": ["authentication fails"],
+    # anthropic: 实际返回 "Request not allowed"
+    "anthropic": ["request not allowed", "anthropic", "x-api-key"],
+    # openrouter: 实际返回 "Missing Authentication header"
+    "openrouter": ["missing authentication header"],
+    # together: 实际返回 "Unauthorized"
+    "together": [],
+    "mistral": ["mistral", "la plateforme"],
+    # cohere: 实际返回 403 HTML 页面
+    "cohere": [],
+    # replicate: 实际返回 "Unauthenticated"
+    "replicate": ["unauthenticated", "you did not pass a valid authentication token"],
+    "huggingface": ["huggingface", "hf_"],
+    "fireworks": ["fireworks", "accounts/fireworks"],
+    "perplexity": ["perplexity"],
+    # grok: 实际返回 "Incorrect API key provided: sk***45...console.x.ai."
+    "grok": ["console.x.ai"],
+    "cerebras": ["cerebras"],
+    "nvidia": ["nvidia", "nim.api"],
+    # hyperbolic: 实际返回 "Could not validate credentials"
+    "hyperbolic": ["could not validate credentials"],
+    "poe": ["poe.com"],
+    "ai302": ["302.ai"],
+    # dmxapi: 实际返回 "rix_api_error"
+    "dmxapi": ["rix_api_error"],
+    # ocoolai: 实际返回 "shell_api_error"
+    "ocoolai": ["shell_api_error"],
+    # zai: 实际返回 "token expired or incorrect"
+    "zai": ["token expired or incorrect"],
+    # openai: 实际返回 "Incorrect API key provided: sk-inval...platform.openai.com..."
+    "openai": ["platform.openai.com"],
+    "google": ["generativelanguage"],
+    "groq": ["groq"],
+}
+
+# Zhipu/Z.AI key format: {id}.{secret} (dot-separated alphanumeric)
+# This format is unique and highly identifiable
+# Part 1 (id): 20-50 chars, Part 2 (secret): 10-50 chars
+ZHIPU_KEY_PATTERN = re.compile(r'^[a-zA-Z0-9]{20,50}\.[a-zA-Z0-9]{10,50}$')
+
+
+def detect_by_prefix(key: str) -> list[str]:
+    """Return candidates from the LONGEST matching prefix only."""
+    for prefix, providers in sorted(KEY_PREFIX_MAP.items(), key=lambda x: -len(x[0])):
+        if key.startswith(prefix):
+            return list(providers)
+    return []
+
+
+def detect_by_pattern(key: str) -> str:
+    """Detect provider by key pattern."""
+    for pattern, provider in sorted(KEY_PATTERNS.items(), key=lambda x: -len(x[0])):
+        if key.startswith(pattern):
+            return provider
+    return None
+
+
+def detect_by_format(key: str) -> list[str]:
+    """Detect providers by key format (e.g., Zhipu's {id}.{secret} format).
+    
+    Returns a list of candidate providers that use this format.
+    The caller will probe all candidates and return the first one that responds 200.
+    """
+    # Zhipu/Z.AI key format: {id}.{secret}
+    # This format is unique to Zhipu and Z.AI platforms
+    if ZHIPU_KEY_PATTERN.match(key):
+        return ["zhipu", "zai"]  # Both candidates, first 200 wins
+    return []
+
+
+def score_provider(provider_name: str, error_body: str, status_code: int = None) -> int:
+    """
+    Score how likely the error body belongs to this provider.
+    
+    Uses UNIQUE_SIGNATURES (verified by actual API testing).
+    Each unique signature match adds WEIGHT_SELF points.
+    429 (rate limited) gets much lower weight since it doesn't confirm key ownership.
+    """
+    body = error_body.lower()
+    score = 0
+    
+    # 429 rate limited gets reduced weight - it only means "too many requests"
+    # not "this key belongs to this provider"
+    weight = WEIGHT_RATE_LIMITED if status_code == 429 else WEIGHT_SELF
+    
+    # Check unique signatures (verified by actual API testing)
+    sigs = UNIQUE_SIGNATURES.get(provider_name, [])
+    for sig in sigs:
+        if sig.lower() in body:
+            score += weight
+    
+    return score
+
+
+async def detect_provider(client, key: str, suspected_provider: str = None) -> str:
+    """Detect provider by concurrently probing ALL providers with multiple models.
+    
+    Strategy:
+    1. If suspected_provider given, try it first
+    2. If key matches unique pattern, try that provider
+    3. Otherwise, concurrently probe ALL providers with their top 5 models
+    4. First provider returning 200 wins
+    """
+    import time
+    
+    # Step 1: If suspected provider, try it first
+    if suspected_provider:
+        provider_name = suspected_provider.lower()
+        if provider_name in PROVIDERS:
+            provider = PROVIDERS[provider_name]
+            result = await provider.check(client, key)
+            if result.valid:
+                return provider_name
+    
+    # Step 2: Try pattern matching for unique prefixes
+    pattern_match = detect_by_pattern(key)
+    if pattern_match and pattern_match in PROVIDERS:
+        provider = PROVIDERS[pattern_match]
+        result = await provider.check(client, key)
+        if result.valid:
+            return pattern_match
+    
+    # Step 3: Try format matching (e.g., Zhipu's {id}.{secret})
+    format_candidates = detect_by_format(key)
+    if format_candidates:
+        # Debug logging
+        try:
+            from webdebug import debug_logger
+            import asyncio as _asyncio
+            _asyncio.create_task(debug_logger.log(
+                category="DETECT",
+                action="detect_by_format",
+                detail=f"Key format matched {len(format_candidates)} candidates",
+                data={"key_prefix": key[:10] + "...", "candidates": format_candidates},
+                level="INFO"
+            ))
+        except ImportError:
+            pass
+        
+        # Try each format candidate
+        async def try_format(name):
+            if name in PROVIDERS:
+                result = await PROVIDERS[name].check(client, key)
+                return name, result.valid
+            return name, False
+        format_tasks = [try_format(n) for n in format_candidates]
+        format_results = await asyncio.gather(*format_tasks)
+        for name, valid in format_results:
+            if valid:
+                return name
+    # Step 4: Concurrently probe ALL providers with their top 5 models
+    # Build tasks: (provider_name, model) pairs
+    tasks = []
+    for name, provider in PROVIDERS.items():
+        models = PROVIDER_MODELS.get(name, [])
+        if not models:
+            models = [getattr(provider, 'check_model', 'gpt-3.5-turbo')]
+        
+        # Use first 5 models
+        for model in models[:5]:
+            tasks.append((name, model))
+    
+    # Concurrently check all (provider, model) pairs
+    async def try_model(name, model):
+        provider = PROVIDERS[name]
+        headers = provider.build_headers(key)
+        headers["Content-Type"] = "application/json"
+        try:
+            resp = await asyncio.wait_for(
+                client.post(
+                    f"{provider.get_base_url()}/chat/completions",
+                    headers=headers,
+                    json={"model": model, "messages": [{"role": "user", "content": "hi"}], "max_tokens": 5}
+                ),
+                timeout=10.0
+            )
+            body = resp.text[:500] if resp.text else ""
+            if resp.status_code == 200:
+                return name, True, body
+            elif resp.status_code in (401, 403):
+                # Invalid key, but return body for signature matching
+                return name, False, body
+            return name, False, body
+        except:
+            return name, False, ""
+    
+    # Fire all tasks concurrently
+    all_tasks = [try_model(name, model) for name, model in tasks]
+    
+    # Collect results for signature matching
+    valid_provider = None
+    error_bodies = {}  # name -> list of error bodies
+    
+    for coro in asyncio.as_completed(all_tasks):
+        name, valid, body = await coro
+        if valid:
+            # Found valid provider, return immediately
+            return name
+        elif body:
+            # Collect error body for signature matching
+            if name not in error_bodies:
+                error_bodies[name] = []
+            error_bodies[name].append(body)
+    
+    # No valid provider found - try signature matching on error bodies
+    # Only return if we have a VERY HIGH confidence match (multiple signatures matched)
+    best_score = -1
+    best_name = None
+    
+    for name, bodies in error_bodies.items():
+        for body in bodies:
+            score = score_provider(name, body, 401)
+            if score > best_score:
+                best_score = score
+                best_name = name
+    
+    # Debug logging for signature matching
+    try:
+        from webdebug import debug_logger
+        import asyncio as _asyncio
+        _asyncio.create_task(debug_logger.log(
+            category="DETECT",
+            action="signature_matching",
+            detail=f"best_score={best_score}, best_name={best_name}",
+            data={"best_score": best_score, "best_name": best_name, "error_bodies_count": len(error_bodies)},
+            level="INFO"
+        ))
+    except ImportError:
+        pass
+    
+    # Only return if we have a VERY HIGH confidence match
+    # Require at least 2 signature matches (200 points) to avoid false positives
+    if best_score >= 200:  # At least 2 signatures matched
+        return best_name
+    
+    # No provider found with high confidence
+    # This is better than returning a wrong provider
+    return None
+
+
+async def _try_provider(client, provider, key: str) -> dict:
+    """Probe a provider and return the result with error body for scoring."""
+    try:
+        # Use a short timeout for detection
+        result = await asyncio.wait_for(provider.probe(client, key), timeout=8.0)
+        error_body = result.response_body or ""
+        
+        return {
+            'valid': result.valid,
+            'status_code': result.status_code,
+            'error_body': error_body
+        }
+    except Exception as e:
+        import logging
+        logging.getLogger(__name__).debug(f"Probe failed for {provider.name}: {e}")
+        return {'valid': False, 'status_code': None, 'error_body': ''}
+
+
+async def _try_unknown_provider() -> dict:
+    return {'valid': False, 'status_code': None, 'error_body': ''}

key_manager/errors.py

@@ -0,0 +1,179 @@
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ErrorCode(str, Enum):
+    """Structured error codes for the API Key Manager."""
+
+    # Validation errors (1xxx)
+    VALIDATION_MISSING_KEY = "VALIDATION_MISSING_KEY"
+    VALIDATION_INVALID_FORMAT = "VALIDATION_INVALID_FORMAT"
+    VALIDATION_PROVIDER_UNKNOWN = "VALIDATION_PROVIDER_UNKNOWN"
+    VALIDATION_FILE_NOT_FOUND = "VALIDATION_FILE_NOT_FOUND"
+    VALIDATION_FILE_FORMAT = "VALIDATION_FILE_FORMAT"
+
+    # Storage errors (2xxx)
+    STORAGE_READ_ERROR = "STORAGE_READ_ERROR"
+    STORAGE_WRITE_ERROR = "STORAGE_WRITE_ERROR"
+    STORAGE_ENCRYPTION_ERROR = "STORAGE_ENCRYPTION_ERROR"
+    STORAGE_MIGRATION_ERROR = "STORAGE_MIGRATION_ERROR"
+
+    # Provider errors (3xxx)
+    PROVIDER_CHECK_FAILED = "PROVIDER_CHECK_FAILED"
+    PROVIDER_NOT_SUPPORTED = "PROVIDER_NOT_SUPPORTED"
+    PROVIDER_RATE_LIMITED = "PROVIDER_RATE_LIMITED"
+
+    # System errors (4xxx)
+    SYSTEM_INTERNAL_ERROR = "SYSTEM_INTERNAL_ERROR"
+    SYSTEM_PROGRESS_CONFLICT = "SYSTEM_PROGRESS_CONFLICT"
+
+    # Auth errors (5xxx)
+    AUTH_REQUIRED = "AUTH_REQUIRED"
+
+
+# Default HTTP status codes for each error code
+ERROR_STATUS_CODES: dict[ErrorCode, int] = {
+    ErrorCode.VALIDATION_MISSING_KEY: 400,
+    ErrorCode.VALIDATION_INVALID_FORMAT: 400,
+    ErrorCode.VALIDATION_PROVIDER_UNKNOWN: 400,
+    ErrorCode.VALIDATION_FILE_NOT_FOUND: 404,
+    ErrorCode.VALIDATION_FILE_FORMAT: 400,
+    ErrorCode.STORAGE_READ_ERROR: 500,
+    ErrorCode.STORAGE_WRITE_ERROR: 500,
+    ErrorCode.STORAGE_ENCRYPTION_ERROR: 500,
+    ErrorCode.STORAGE_MIGRATION_ERROR: 500,
+    ErrorCode.PROVIDER_CHECK_FAILED: 502,
+    ErrorCode.PROVIDER_NOT_SUPPORTED: 400,
+    ErrorCode.PROVIDER_RATE_LIMITED: 429,
+    ErrorCode.SYSTEM_INTERNAL_ERROR: 500,
+    ErrorCode.SYSTEM_PROGRESS_CONFLICT: 409,
+    ErrorCode.AUTH_REQUIRED: 401,
+}
+
+# Default human-readable messages for each error code
+DEFAULT_MESSAGES: dict[ErrorCode, str] = {
+    ErrorCode.VALIDATION_MISSING_KEY: "API key is required",
+    ErrorCode.VALIDATION_INVALID_FORMAT: "API key format is invalid",
+    ErrorCode.VALIDATION_PROVIDER_UNKNOWN: "Unable to detect provider, please select manually",
+    ErrorCode.VALIDATION_FILE_NOT_FOUND: "File not found",
+    ErrorCode.VALIDATION_FILE_FORMAT: "Unsupported file format",
+    ErrorCode.STORAGE_READ_ERROR: "Failed to read from storage",
+    ErrorCode.STORAGE_WRITE_ERROR: "Failed to write to storage",
+    ErrorCode.STORAGE_ENCRYPTION_ERROR: "Encryption/decryption operation failed",
+    ErrorCode.STORAGE_MIGRATION_ERROR: "Data migration failed",
+    ErrorCode.PROVIDER_CHECK_FAILED: "Provider key check failed",
+    ErrorCode.PROVIDER_NOT_SUPPORTED: "Provider is not supported",
+    ErrorCode.PROVIDER_RATE_LIMITED: "Provider rate limit exceeded",
+    ErrorCode.SYSTEM_INTERNAL_ERROR: "Internal server error",
+    ErrorCode.SYSTEM_PROGRESS_CONFLICT: "Another operation is already in progress",
+    ErrorCode.AUTH_REQUIRED: "Authentication required",
+}
+
+
+class ErrorDetail(BaseModel):
+    """Error detail embedded in ErrorResponse."""
+
+    code: ErrorCode
+    message: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response envelope.
+
+    JSON shape: {"error": {"code": "...", "message": "...", "details": {...}}}
+    """
+
+    error: ErrorDetail
+
+    @classmethod
+    def error_factory(
+        cls,
+        code: ErrorCode,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> "ErrorResponse":
+        return cls(
+            error=ErrorDetail(
+                code=code,
+                message=message or DEFAULT_MESSAGES.get(code, code.value),
+                details=details or {},
+            )
+        )
+
+
+class KeyManagerError(Exception):
+    """Base exception for all API Key Manager errors."""
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        self.code = code
+        self.message = message or DEFAULT_MESSAGES.get(code, code.value)
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def to_response(self, status_code: Optional[int] = None) -> tuple[int, ErrorResponse]:
+        """Convert to HTTP status code and ErrorResponse body."""
+        http_code = status_code or ERROR_STATUS_CODES.get(self.code, 500)
+        body = ErrorResponse(
+            error=ErrorDetail(
+                code=self.code,
+                message=self.message,
+                details=self.details,
+            )
+        )
+        return http_code, body
+
+
+class ValidationError(KeyManagerError):
+    """Raised for input validation failures."""
+
+    def __init__(
+        self,
+        code: ErrorCode = ErrorCode.VALIDATION_MISSING_KEY,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(code=code, message=message, details=details)
+
+
+class StorageError(KeyManagerError):
+    """Raised for storage read/write/encryption failures."""
+
+    def __init__(
+        self,
+        code: ErrorCode = ErrorCode.STORAGE_READ_ERROR,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(code=code, message=message, details=details)
+
+
+class ProviderError(KeyManagerError):
+    """Raised for provider interaction failures."""
+
+    def __init__(
+        self,
+        code: ErrorCode = ErrorCode.PROVIDER_CHECK_FAILED,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(code=code, message=message, details=details)
+
+
+class SystemError(KeyManagerError):
+    """Raised for internal system errors."""
+
+    def __init__(
+        self,
+        code: ErrorCode = ErrorCode.SYSTEM_INTERNAL_ERROR,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(code=code, message=message, details=details)

key_manager/i18n.py

@@ -0,0 +1,142 @@
+"""Internationalization (i18n) module for API Key Manager."""
+
+import json
+import threading
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Optional
+
+_I18N_DIR = Path(__file__).parent / "i18n"
+_DEFAULT_LANG = "en"
+_fallback_chain: list[str] = [_DEFAULT_LANG]
+
+_translations: dict[str, dict[str, str]] = {}
+_lock = threading.Lock()
+_context = threading.local()
+
+
+def _load_lang(lang: str) -> dict[str, str]:
+    """Load translations for a language from its JSON file, with caching."""
+    with _lock:
+        if lang in _translations:
+            return _translations[lang]
+    path = _I18N_DIR / f"{lang}.json"
+    if not path.exists():
+        with _lock:
+            _translations[lang] = {}
+        return {}
+    with open(path, encoding="utf-8") as f:
+        data: dict[str, str] = json.load(f)
+    with _lock:
+        _translations[lang] = data
+    return data
+
+
+def _get_current_lang() -> str:
+    """Get the current language from thread-local context, or default."""
+    return getattr(_context, "lang", _DEFAULT_LANG)
+
+
+def set_lang(lang: str) -> None:
+    """Set the current language for the calling thread."""
+    _context.lang = lang
+
+
+@contextmanager
+def language_context(lang: str):
+    """Context manager to temporarily set the active language."""
+    prev = getattr(_context, "lang", None)
+    _context.lang = lang
+    try:
+        yield
+    finally:
+        if prev is None:
+            _context.lang = _DEFAULT_LANG
+        else:
+            _context.lang = prev
+
+
+def get_lang_from_header(accept_language: Optional[str]) -> str:
+    """Parse Accept-Language header and return the best matching language.
+
+    Supports formats like:
+    - "zh-CN,zh;q=0.9,en;q=0.8"
+    - "en-US,en;q=0.9"
+    - "zh"
+    - "fr"
+    """
+    if not accept_language or not accept_language.strip():
+        return _DEFAULT_LANG
+
+    available = {p.stem for p in _I18N_DIR.glob("*.json")} if _I18N_DIR.exists() else set()
+
+    candidates: list[tuple[str, float]] = []
+    for part in accept_language.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        pieces = part.split(";")
+        lang_tag = pieces[0].strip().lower()
+        quality = 1.0
+        if len(pieces) > 1:
+            for param in pieces[1:]:
+                param = param.strip()
+                if param.startswith("q="):
+                    try:
+                        quality = float(param[2:])
+                    except ValueError:
+                        quality = 0.0
+        if lang_tag:
+            candidates.append((lang_tag, quality))
+
+    candidates.sort(key=lambda x: x[1], reverse=True)
+
+    for lang_tag, _ in candidates:
+        if lang_tag in available:
+            return lang_tag
+        primary = lang_tag.split("-")[0]
+        if primary in available:
+            return primary
+
+    return _DEFAULT_LANG
+
+
+def t(code: str, lang: Optional[str] = None, **kwargs: Any) -> str:
+    """Translate a message code to the current or specified language.
+
+    Falls back to English if the code is not found in the requested language.
+    Supports {key} placeholder substitution via kwargs.
+    """
+    target_lang = lang or _get_current_lang()
+
+    # Try requested language first
+    translations = _load_lang(target_lang)
+    message = translations.get(code)
+
+    # Walk fallback chain if missing
+    if message is None and target_lang != _DEFAULT_LANG:
+        for fb_lang in _fallback_chain:
+            if fb_lang == target_lang:
+                continue
+            fb_translations = _load_lang(fb_lang)
+            message = fb_translations.get(code)
+            if message is not None:
+                break
+
+    # Ultimate fallback: return the raw code
+    if message is None:
+        message = code
+
+    if kwargs:
+        try:
+            message = message.format(**kwargs)
+        except (KeyError, IndexError, ValueError):
+            pass
+
+    return message
+
+
+def reload_translations() -> None:
+    """Clear the translation cache, forcing reload on next access."""
+    with _lock:
+        _translations.clear()