lingora-cli 0.1.0rc1__py3-none-any.whl

lingora_cli/cli.py

@@ -0,0 +1,1383 @@
+"""提供 CLI 执行入口、公开 HTTP 传输与 Android 翻译资源的安全同步校验。"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import math
+import os
+import re
+import shutil
+import sys
+import tempfile
+import uuid
+import zipfile
+from collections.abc import Callable, Mapping
+from contextlib import redirect_stderr, redirect_stdout
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from importlib.resources import files
+from pathlib import Path, PurePosixPath
+from typing import Any, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener, urlopen
+from xml.etree import ElementTree as ET
+
+DEFAULT_CONFIG = ".lingorarc"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+MAX_RESPONSE_BYTES = 50 * 1024 * 1024
+MAX_ZIP_ENTRIES = 1_000
+MAX_EXPANDED_ZIP_BYTES = 100 * 1024 * 1024
+ANDROID_PLURAL_QUANTITIES = {"zero", "one", "two", "few", "many", "other"}
+JAVA_PLACEHOLDER_RE = re.compile(
+    r"%(?:(\d+)\$)?([-#+ 0,(<]*)(\d*)(?:\.(\d+))?([tT]?[a-zA-Z%])"
+)
+
+
+# 表示可向使用者报告的同步错误。
+class ScriptError(RuntimeError):
+    """Expected configuration, validation, or remote API failure."""
+
+
+@dataclass(frozen=True)
+# 记录单个源资源及其语言和命名空间。
+class PushFile:
+    path: Path
+    language: str
+    namespace: str
+
+
+@dataclass(frozen=True)
+# 保存不依赖本地资源的项目连接信息。
+class ProjectConfig:
+    api_url: str
+    project_id: str
+    branch: Optional[str]
+
+
+@dataclass(frozen=True)
+# 保存校验后的同步配置，不包含密钥。
+class Config:
+    config_path: Path
+    api_url: str
+    project_id: str
+    branch: Optional[str]
+    format: str
+    base_language: str
+    target_languages: tuple[str, ...]
+    namespace: str
+    push_files: tuple[PushFile, ...]
+    pull_path: Path
+    push_force_mode: str
+    push_override_mode: str
+    push_error_on_unresolved_conflict: Optional[bool]
+    push_override_key_descriptions: bool
+    push_convert_placeholders_to_icu: bool
+    push_tag_new_keys: tuple[str, ...]
+    push_remove_other_keys: bool
+    pull_namespaces: tuple[str, ...]
+    pull_states: tuple[str, ...]
+    pull_file_structure_template: str
+    pull_empty_dir: bool
+    content_deliveries: dict[str, str]
+    pull_tags: tuple[str, ...] = ()
+    pull_exclude_tags: tuple[str, ...] = ()
+    pull_support_arrays: bool = False
+    pull_include_empty: bool = False
+
+
+@dataclass(frozen=True)
+# 保存 HTTP 状态、响应头与原始内容。
+class HttpResponse:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+@dataclass(frozen=True)
+# 保存 Android 资源类型和值。
+class AndroidResource:
+    kind: str
+    values: Any
+
+
+Requester = Callable[..., HttpResponse]
+
+
+# 读取非空字符串配置。
+def _required_string(data: dict[str, Any], key: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ScriptError(f"Configuration field {key!r} must be a non-empty string")
+    return value.strip()
+
+
+# 读取对象类型配置。
+def _required_object(data: dict[str, Any], key: str) -> dict[str, Any]:
+    value = data.get(key)
+    if not isinstance(value, dict):
+        raise ScriptError(f"Configuration field {key!r} must be an object")
+    return value
+
+
+# 读取并校验唯一字符串列表。
+def _string_list(data: dict[str, Any], key: str, *, required: bool) -> tuple[str, ...]:
+    value = data.get(key)
+    if value is None and not required:
+        return ()
+    if not isinstance(value, list) or (required and not value):
+        qualifier = "non-empty " if required else ""
+        raise ScriptError(
+            f"Configuration field {key!r} must be a {qualifier}array of strings"
+        )
+    if any(not isinstance(item, str) or not item.strip() for item in value):
+        raise ScriptError(f"Configuration field {key!r} must contain strings")
+    normalized = tuple(item.strip() for item in value)
+    if len(set(normalized)) != len(normalized):
+        raise ScriptError(f"Configuration field {key!r} must contain unique values")
+    return normalized
+
+
+# 读取严格布尔配置。
+def _boolean(data: dict[str, Any], key: str, default: bool) -> bool:
+    value = data.get(key, default)
+    if not isinstance(value, bool):
+        raise ScriptError(f"Configuration field {key!r} must be a boolean")
+    return value
+
+
+# 校验公开 HTTP 地址并拒绝内嵌凭据。
+def _validate_url(value: str, field: str) -> str:
+    normalized = value.rstrip("/")
+    try:
+        parsed = urlsplit(normalized)
+        port = parsed.port
+    except ValueError as exc:
+        raise ScriptError(
+            f"Configuration field {field!r} has an invalid host or port"
+        ) from exc
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ScriptError(f"Configuration field {field!r} must be an HTTP(S) URL")
+    if not parsed.hostname or port == 0:
+        raise ScriptError(f"Configuration field {field!r} has an invalid host or port")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ScriptError(
+            f"Configuration field {field!r} must not contain credentials, query, or fragment"
+        )
+    return normalized
+
+
+# 加载已合并参数的配置，按操作校验输入并保护输出边界。
+def load_config(
+    path: Path, *, data: dict[str, Any] | None = None, operation: str = "all"
+) -> Config:
+    if data is None:
+        try:
+            config_path = path.expanduser().resolve(strict=True)
+            data = json.loads(config_path.read_text(encoding="utf-8"))
+        except FileNotFoundError as exc:
+            raise ScriptError(f"Configuration file not found: {path}") from exc
+        except json.JSONDecodeError as exc:
+            raise ScriptError(f"Invalid JSON configuration: {exc}") from exc
+    else:
+        config_path = path.expanduser().resolve()
+    if not isinstance(data, dict):
+        raise ScriptError("Configuration root must be a JSON object")
+
+    api_url = ""
+    project_id = ""
+    if operation != "extract" or "apiUrl" in data:
+        api_url = _validate_url(_required_string(data, "apiUrl"), "apiUrl")
+    if operation != "extract" or "projectId" in data:
+        project_id = _required_string(data, "projectId")
+        try:
+            uuid.UUID(project_id)
+        except ValueError as exc:
+            raise ScriptError("Configuration field 'projectId' must be a UUID") from exc
+
+    branch_value = data.get("branch")
+    if branch_value is not None and (
+        not isinstance(branch_value, str) or not branch_value.strip()
+    ):
+        raise ScriptError(
+            "Configuration field 'branch' must be a non-empty string when set"
+        )
+    branch = branch_value.strip() if isinstance(branch_value, str) else None
+    if "apiKey" in data:
+        raise ScriptError(
+            "Configuration field 'apiKey' is not allowed; use LINGORA_API_KEY or --api-key"
+        )
+
+    format_name = _required_string(data, "format")
+    if format_name != "ANDROID_XML":
+        raise ScriptError("Configuration field 'format' must be 'ANDROID_XML'")
+
+    push = _required_object(data, "push")
+    files = push.get("files")
+    if not isinstance(files, list) or not files:
+        raise ScriptError(
+            "Configuration field 'push.files' must contain at least one Android base file"
+        )
+    push_file_values: list[tuple[str, str, str]] = []
+    for index, item in enumerate(files):
+        if not isinstance(item, dict):
+            raise ScriptError(
+                f"Configuration field 'push.files[{index}]' must be an object"
+            )
+        path_value = _required_string(item, "path")
+        language = _required_string(item, "language")
+        namespace_value = item.get("namespace", data.get("defaultNamespace", ""))
+        if not isinstance(namespace_value, str):
+            raise ScriptError(
+                f"Configuration field 'push.files[{index}].namespace' must be a string"
+            )
+        push_file_values.append((path_value, language, namespace_value.strip()))
+
+    base_language = push_file_values[0][1]
+    namespace = push_file_values[0][2]
+    if any(language != base_language for _, language, _ in push_file_values):
+        raise ScriptError(
+            "All Android base files in 'push.files' must use the same language"
+        )
+    if any(file_namespace != namespace for _, _, file_namespace in push_file_values):
+        raise ScriptError(
+            "All Android base files in 'push.files' must use the same namespace"
+        )
+
+    force_mode = str(push.get("forceMode", "NO_FORCE")).upper()
+    if force_mode not in {"KEEP", "OVERRIDE", "NO_FORCE"}:
+        raise ScriptError("Configuration field 'push.forceMode' is invalid")
+    override_mode = str(push.get("overrideMode", "RECOMMENDED")).upper()
+    if override_mode not in {"RECOMMENDED", "ALL"}:
+        raise ScriptError("Configuration field 'push.overrideMode' is invalid")
+    error_choice = push.get("errorOnUnresolvedConflict", "auto")
+    error_mapping = {"yes": True, "no": False, "auto": None}
+    if not isinstance(error_choice, str) or error_choice not in error_mapping:
+        raise ScriptError(
+            "Configuration field 'push.errorOnUnresolvedConflict' must be yes, no, or auto"
+        )
+    tag_new_keys = _string_list(push, "tagNewKeys", required=False)
+
+    pull = data.get("pull", {})
+    if not isinstance(pull, dict):
+        raise ScriptError("Configuration field 'pull' must be an object")
+    target_languages = _string_list(
+        pull, "languages", required=operation in {"all", "pull", "validate", "delivery"}
+    )
+    if base_language in target_languages:
+        raise ScriptError(
+            "Configuration field 'pull.languages' must exclude the base language"
+        )
+    pull_namespaces = _string_list(pull, "namespaces", required=False) or (namespace,)
+    if pull_namespaces != (namespace,):
+        raise ScriptError(
+            "Configuration field 'pull.namespaces' must match push.files[0].namespace"
+        )
+    pull_states = _string_list(pull, "states", required=False) or (
+        "TRANSLATED",
+        "REVIEWED",
+    )
+    if any(
+        state not in {"UNTRANSLATED", "TRANSLATED", "REVIEWED"} for state in pull_states
+    ):
+        raise ScriptError("Configuration field 'pull.states' contains an invalid state")
+    file_structure_template = pull.get(
+        "fileStructureTemplate", "values-{androidLanguageTag}/strings.xml"
+    )
+    if not isinstance(file_structure_template, str) or not file_structure_template:
+        raise ScriptError("Configuration field 'pull.fileStructureTemplate' is invalid")
+    pull_empty_dir = _boolean(pull, "emptyDir", False)
+
+    raw_deliveries = data.get("contentDeliveries", {})
+    if not isinstance(raw_deliveries, dict):
+        raise ScriptError("Configuration field 'contentDeliveries' must be an object")
+    content_deliveries: dict[str, str] = {}
+    for name, value in raw_deliveries.items():
+        if not isinstance(name, str) or not name.strip() or not isinstance(value, str):
+            raise ScriptError("Content Delivery names and URLs must be strings")
+        content_deliveries[name] = _validate_url(value, f"contentDeliveries.{name}")
+
+    base_dir = config_path.parent
+    push_files = tuple(
+        PushFile(
+            path=(base_dir / path_value).resolve(),
+            language=language,
+            namespace=file_namespace,
+        )
+        for path_value, language, file_namespace in push_file_values
+    )
+    if len({item.path for item in push_files}) != len(push_files):
+        raise ScriptError("Configuration field 'push.files' contains duplicate paths")
+    if len({item.path.name for item in push_files}) != len(push_files):
+        raise ScriptError(
+            "Android base files in 'push.files' must have unique filenames"
+        )
+    pull_path = (
+        base_dir
+        / _required_string({"path": pull.get("path", "generated/lingora/res")}, "path")
+    ).resolve()
+    if pull_path in config_path.parents or any(
+        pull_path in item.path.parents for item in push_files
+    ):
+        raise ScriptError(
+            "Pull output must not contain configuration or base resource files"
+        )
+    output_paths = [
+        render_export_path(file_structure_template, language, namespace)
+        for language in target_languages
+    ]
+    if len(set(output_paths)) != len(output_paths):
+        raise ScriptError("Target languages resolve to duplicate pull output paths")
+    if any(
+        pull_path.joinpath(*output_path.parts) == push_file.path
+        for output_path in output_paths
+        for push_file in push_files
+    ):
+        raise ScriptError(
+            "Pull output must not overwrite the base Android resource file"
+        )
+
+    return Config(
+        config_path=config_path,
+        api_url=api_url,
+        project_id=project_id,
+        branch=branch,
+        format=format_name,
+        base_language=base_language,
+        target_languages=target_languages,
+        namespace=namespace,
+        push_files=push_files,
+        pull_path=pull_path,
+        push_force_mode=force_mode,
+        push_override_mode=override_mode,
+        push_error_on_unresolved_conflict=error_mapping[error_choice],
+        push_override_key_descriptions=_boolean(push, "overrideKeyDescriptions", True),
+        push_convert_placeholders_to_icu=_boolean(
+            push, "convertPlaceholdersToIcu", True
+        ),
+        push_tag_new_keys=tag_new_keys,
+        push_remove_other_keys=_boolean(push, "removeOtherKeys", False),
+        pull_namespaces=pull_namespaces,
+        pull_states=pull_states,
+        pull_file_structure_template=file_structure_template,
+        pull_empty_dir=pull_empty_dir,
+        content_deliveries=content_deliveries,
+        pull_tags=_string_list(pull, "tags", required=False),
+        pull_exclude_tags=_string_list(pull, "excludeTags", required=False),
+        pull_support_arrays=_boolean(pull, "supportArrays", False),
+        pull_include_empty=_boolean(pull, "includeEmptyTranslations", False),
+    )
+
+
+# 从调用者的当前目录选择默认配置。
+def default_config_path() -> Path:
+    return Path(DEFAULT_CONFIG)
+
+
+# 按参数、环境、配置顺序选择分支。
+def select_branch(
+    command_line: Optional[str],
+    configured: Optional[str],
+    environ: Mapping[str, str] = os.environ,
+) -> str:
+    candidate = command_line or environ.get("LINGORA_BRANCH") or configured
+    if not candidate or not candidate.strip():
+        raise ScriptError(
+            "Branch is required: pass --branch, set LINGORA_BRANCH, or configure 'branch'"
+        )
+    return candidate.strip()
+
+
+# 读取密钥但不持久化。
+def require_api_key(
+    command_line: Optional[str] = None,
+    environ: Mapping[str, str] = os.environ,
+) -> str:
+    value = command_line or environ.get("LINGORA_API_KEY") or ""
+    if not value.strip():
+        raise ScriptError("API key is required: pass --api-key or set LINGORA_API_KEY")
+    return value.strip()
+
+
+# 限制远端响应大小。
+def _read_limited(stream: Any, limit: int = MAX_RESPONSE_BYTES) -> bytes:
+    body = stream.read(limit + 1)
+    if len(body) > limit:
+        raise ScriptError(f"Remote response exceeds {limit} bytes")
+    return body
+
+
+# 提取远端错误和冲突键摘要。
+def _error_message(status: int, body: bytes) -> str:
+    try:
+        payload = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return f"HTTP {status}"
+    if not isinstance(payload, dict):
+        return f"HTTP {status}"
+    message = payload.get("message")
+    error = payload.get("error")
+    code = error.get("code") if isinstance(error, dict) else None
+    suffix = f" ({code})" if code is not None else ""
+    details = error.get("details") if isinstance(error, dict) else None
+    conflict_suffix = _format_conflict_keys(details)
+    return f"HTTP {status}: {message or 'request failed'}{suffix}{conflict_suffix}"
+
+
+# 生成长度受限的冲突提示。
+def _format_conflict_keys(value: Any) -> str:
+    if not isinstance(value, list):
+        return ""
+    keys = list(
+        dict.fromkeys(
+            str(item["key"])
+            for item in value
+            if isinstance(item, dict)
+            and isinstance(item.get("key"), str)
+            and item["key"]
+        )
+    )
+    if not keys:
+        return ""
+    visible = ", ".join(keys[:10])
+    remaining = max(0, len(keys) - 10)
+    more = f" (+{remaining} more)" if remaining else ""
+    return f"; conflicting keys: {visible}{more}"
+
+
+# 限制认证 HTTP 请求的重定向来源。
+class ApiRedirectHandler(HTTPRedirectHandler):
+    # 认证请求只接受同源重定向，避免密钥被转发给第三方地址。
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        original = urlsplit(req.full_url)
+        target = urlsplit(newurl)
+        if (original.scheme, original.hostname, original.port) != (
+            target.scheme,
+            target.hostname,
+            target.port,
+        ):
+            raise ScriptError(
+                "Authenticated API redirect to a different origin is not allowed"
+            )
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+# 调用公开 API，并在认证请求重定向时保护密钥。
+def http_request(
+    url: str,
+    *,
+    method: str = "GET",
+    api_key: Optional[str] = None,
+    data: Optional[bytes] = None,
+    content_type: Optional[str] = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> HttpResponse:
+    headers = {"Accept": "application/json"}
+    if api_key:
+        headers["X-API-Key"] = api_key
+    if content_type:
+        headers["Content-Type"] = content_type
+    request = Request(url, data=data, headers=headers, method=method)
+    try:
+        opener = build_opener(ApiRedirectHandler()).open if api_key else urlopen
+        with opener(request, timeout=timeout) as response:
+            return HttpResponse(
+                status=response.status,
+                headers=dict(response.headers.items()),
+                body=_read_limited(response),
+            )
+    except HTTPError as exc:
+        body = _read_limited(exc)
+        raise ScriptError(_error_message(exc.code, body)) from exc
+    except URLError as exc:
+        raise ScriptError(f"Request failed: {exc.reason}") from exc
+
+
+# 校验 API 响应并提取业务数据。
+def api_data(response: HttpResponse) -> Any:
+    try:
+        payload = json.loads(response.body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ScriptError("Lingora returned an invalid JSON response") from exc
+    if (
+        not 200 <= response.status < 300
+        or not isinstance(payload, dict)
+        or payload.get("code") != response.status
+    ):
+        raise ScriptError("Lingora returned an invalid API response envelope")
+    return payload.get("data")
+
+
+# 按精确名称获取唯一分支 UUID。
+def resolve_branch(
+    config: Config | ProjectConfig,
+    api_key: str,
+    branch_name: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    requester: Requester = http_request,
+) -> str:
+    response = requester(
+        f"{config.api_url}/api/v1/projects/{config.project_id}/branches",
+        api_key=api_key,
+        timeout=timeout,
+    )
+    branches = api_data(response)
+    if not isinstance(branches, list):
+        raise ScriptError("Branch list response must contain an array")
+    matches = [
+        item
+        for item in branches
+        if isinstance(item, dict) and item.get("name") == branch_name
+    ]
+    if len(matches) > 1:
+        raise ScriptError(
+            f"Branch name {branch_name!r} is not unique in Project {config.project_id}"
+        )
+    if not matches:
+        available = sorted(
+            str(item["name"])
+            for item in branches
+            if isinstance(item, dict) and isinstance(item.get("name"), str)
+        )
+        choices = ", ".join(available) if available else "(none)"
+        raise ScriptError(
+            f"Branch {branch_name!r} not found. Available branches: {choices}"
+        )
+    branch_id = matches[0].get("id")
+    try:
+        return str(uuid.UUID(str(branch_id)))
+    except ValueError as exc:
+        raise ScriptError(f"Branch {branch_name!r} has an invalid UUID") from exc
+
+
+# 构造多文件导入请求并清理文件名。
+def build_multipart(
+    fields: dict[str, str], files: tuple[tuple[str, bytes], ...]
+) -> tuple[bytes, str]:
+    boundary = f"----lingora-{uuid.uuid4().hex}"
+    chunks: list[bytes] = []
+    for name, value in fields.items():
+        chunks.extend(
+            [
+                f"--{boundary}\r\n".encode(),
+                f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode(),
+                value.encode("utf-8"),
+                b"\r\n",
+            ]
+        )
+    for filename, content in files:
+        safe_filename = filename.replace('"', "").replace("\r", "").replace("\n", "")
+        chunks.extend(
+            [
+                f"--{boundary}\r\n".encode(),
+                (
+                    'Content-Disposition: form-data; name="files"; '
+                    f'filename="{safe_filename}"\r\n'
+                ).encode(),
+                b"Content-Type: application/xml\r\n\r\n",
+                content,
+                b"\r\n",
+            ]
+        )
+    chunks.append(f"--{boundary}--\r\n".encode())
+    return b"".join(chunks), f"multipart/form-data; boundary={boundary}"
+
+
+# 校验源资源后一次性上传所有文件。
+def push_resources(
+    config: Config,
+    api_key: str,
+    branch_name: str,
+    force_mode: str,
+    remove_other_keys: bool,
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    requester: Requester = http_request,
+) -> dict[str, Any]:
+    resources = parse_push_resources(config)
+    if not resources:
+        raise ScriptError(
+            "Configured Android base files contain no supported resources: "
+            + ", ".join(str(item.path) for item in config.push_files)
+        )
+    branch_id = resolve_branch(
+        config, api_key, branch_name, timeout=timeout, requester=requester
+    )
+    params = {
+        "forceMode": force_mode,
+        "overrideMode": config.push_override_mode,
+        "errorOnUnresolvedConflict": config.push_error_on_unresolved_conflict,
+        "languageMappings": None,
+        "fileMappings": [
+            {
+                "fileName": item.path.name,
+                "namespace": item.namespace,
+                "format": config.format,
+                "languageTag": item.language,
+                "languageTagsToImport": [],
+            }
+            for item in config.push_files
+        ],
+        "overrideKeyDescriptions": config.push_override_key_descriptions,
+        "convertPlaceholdersToIcu": config.push_convert_placeholders_to_icu,
+        "createNewKeys": True,
+        "tagNewKeys": list(config.push_tag_new_keys),
+        "removeOtherKeys": remove_other_keys,
+    }
+    body, content_type = build_multipart(
+        {"params": json.dumps(params, separators=(",", ":"))},
+        tuple((item.path.name, item.path.read_bytes()) for item in config.push_files),
+    )
+    response = requester(
+        f"{config.api_url}/api/v1/projects/{config.project_id}/branches/"
+        f"{branch_id}/imports/single-step",
+        method="POST",
+        api_key=api_key,
+        data=body,
+        content_type=content_type,
+        timeout=timeout,
+    )
+    result = api_data(response)
+    if not isinstance(result, dict):
+        raise ScriptError("Import response data must be an object")
+    conflicts = result.get("unresolvedConflicts")
+    conflict_summary = _format_conflict_keys(conflicts)
+    if conflict_summary:
+        print(
+            "Push warning: Lingora kept protected or disabled server values"
+            f"{conflict_summary}",
+            file=sys.stderr,
+        )
+    print(
+        f"Push completed: branch={branch_name} branchId={branch_id} "
+        f"affected={result.get('affected', 0)} deleted={result.get('deleted', 0)}"
+    )
+    return result
+
+
+# 转换语言标记为 Android 限定符。
+def android_language_tag(language: str) -> str:
+    parts = language.replace("_", "-").split("-")
+    base = parts[0].lower()
+    region = next(
+        (
+            part
+            for part in parts[1:]
+            if (len(part) == 2 and part.isalpha())
+            or (len(part) == 3 and part.isdigit())
+        ),
+        None,
+    )
+    return base if region is None else f"{base}-r{region.upper()}"
+
+
+# 渲染并校验导出相对路径。
+def render_export_path(
+    template: str,
+    language: str,
+    namespace: str,
+) -> PurePosixPath:
+    try:
+        rendered = template.format(
+            namespace=namespace,
+            languageTag=language,
+            androidLanguageTag=android_language_tag(language),
+            snakeLanguageTag=language.replace("-", "_"),
+            extension="xml",
+        )
+    except (KeyError, ValueError) as exc:
+        raise ScriptError(
+            "Configuration field 'pull.fileStructureTemplate' is invalid"
+        ) from exc
+    return _safe_zip_path(rendered)
+
+
+# 拒绝归档中的绝对路径和目录穿越。
+def _safe_zip_path(name: str) -> PurePosixPath:
+    if not name or "\\" in name or name.startswith(("/", "\\")):
+        raise ScriptError(f"Unsafe ZIP entry path: {name!r}")
+    path = PurePosixPath(name)
+    if any(part in {"", ".", ".."} for part in path.parts):
+        raise ScriptError(f"Unsafe ZIP entry path: {name!r}")
+    if path.parts and path.parts[0].endswith(":"):
+        raise ScriptError(f"Unsafe ZIP entry path: {name!r}")
+    return path
+
+
+# 限量解压导出结果并拒绝符号链接。
+def extract_export(
+    response: HttpResponse,
+    destination: Path,
+    languages: tuple[str, ...],
+    file_structure_template: str,
+    namespace: str,
+) -> None:
+    response_headers = {
+        key.casefold(): value for key, value in response.headers.items()
+    }
+    content_type = response_headers.get("content-type", "").split(";", 1)[0].lower()
+    archive = io.BytesIO(response.body)
+    if content_type == "application/zip" or zipfile.is_zipfile(archive):
+        archive.seek(0)
+        with zipfile.ZipFile(archive) as bundle:
+            entries = bundle.infolist()
+            if len(entries) > MAX_ZIP_ENTRIES:
+                raise ScriptError("Export ZIP contains too many entries")
+            if sum(item.file_size for item in entries) > MAX_EXPANDED_ZIP_BYTES:
+                raise ScriptError("Expanded export ZIP is too large")
+            for item in entries:
+                path = _safe_zip_path(item.filename)
+                mode = (item.external_attr >> 16) & 0o170000
+                if mode == 0o120000:
+                    raise ScriptError(
+                        f"ZIP symbolic links are not allowed: {item.filename}"
+                    )
+                target = destination.joinpath(*path.parts)
+                if item.is_dir():
+                    target.mkdir(parents=True, exist_ok=True)
+                    continue
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with bundle.open(item) as source, target.open("wb") as output:
+                    shutil.copyfileobj(source, output)
+        return
+
+    if len(languages) != 1:
+        raise ScriptError("Lingora returned one XML file for a multi-language export")
+    try:
+        ET.fromstring(response.body)
+    except ET.ParseError as exc:
+        raise ScriptError(
+            "Lingora export is neither a ZIP nor valid Android XML"
+        ) from exc
+    relative = render_export_path(file_structure_template, languages[0], namespace)
+    target = destination.joinpath(*relative.parts)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(response.body)
+
+
+# 替换生成目录，失败时恢复旧目录。
+def _replace_directory(staging: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    backup = destination.parent / f".{destination.name}.backup-{uuid.uuid4().hex}"
+    moved_old = False
+    installed = False
+    try:
+        if destination.exists():
+            os.replace(destination, backup)
+            moved_old = True
+        os.replace(staging, destination)
+        installed = True
+    except OSError:
+        if moved_old and not destination.exists() and backup.exists():
+            os.replace(backup, destination)
+        raise
+    finally:
+        # 恢复本身失败时必须保留备份，不能把唯一的原文件清理掉。
+        if installed and backup.exists():
+            shutil.rmtree(backup)
+
+
+# 校验通过后安装暂存翻译。
+def _install_export(staging: Path, destination: Path, empty_dir: bool) -> None:
+    if empty_dir:
+        _replace_directory(staging, destination)
+        return
+    destination.mkdir(parents=True, exist_ok=True)
+    for source in sorted(path for path in staging.rglob("*") if path.is_file()):
+        relative = source.relative_to(staging)
+        target = destination / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(source, target)
+
+
+# 下载并暂存翻译，校验通过后更新输出。
+def pull_resources(
+    config: Config,
+    api_key: str,
+    branch_name: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    requester: Requester = http_request,
+) -> dict[str, Any]:
+    branch_id = resolve_branch(
+        config, api_key, branch_name, timeout=timeout, requester=requester
+    )
+    payload = {
+        "languages": list(config.target_languages),
+        "namespaces": list(config.pull_namespaces),
+        "states": list(config.pull_states),
+        "includeEmptyTranslations": config.pull_include_empty,
+        "format": config.format,
+        "fileStructureTemplate": config.pull_file_structure_template,
+        "zip": True,
+        "filterTagIn": list(config.pull_tags),
+        "filterTagNotIn": list(config.pull_exclude_tags),
+        "supportArrays": config.pull_support_arrays,
+    }
+    response = requester(
+        f"{config.api_url}/api/v1/projects/{config.project_id}/branches/{branch_id}/exports",
+        method="POST",
+        api_key=api_key,
+        data=json.dumps(payload, separators=(",", ":")).encode("utf-8"),
+        content_type="application/json",
+        timeout=timeout,
+    )
+
+    destination = config.pull_path
+    if destination.exists() and not destination.is_dir():
+        raise ScriptError(f"Pull path is not a directory: {destination}")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(
+        tempfile.mkdtemp(prefix=f".{destination.name}.staging-", dir=destination.parent)
+    )
+    try:
+        extract_export(
+            response,
+            staging,
+            config.target_languages,
+            config.pull_file_structure_template,
+            config.namespace,
+        )
+        exported_languages = validate_resources(
+            config,
+            pull_path=staging,
+            fallback_incomplete_arrays=True,
+        )
+        _install_export(staging, destination, config.pull_empty_dir)
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging)
+    print(
+        f"Pull completed: branch={branch_name} branchId={branch_id} "
+        f"requested={','.join(config.target_languages)} "
+        f"exported={','.join(exported_languages) or 'none'} output={destination}"
+    )
+    if not exported_languages:
+        print(
+            "Pull notice: no non-empty translations matched states="
+            f"{','.join(config.pull_states)}; adding a language alone does not create "
+            "an Android locale file."
+        )
+    return {
+        "branch": branch_name,
+        "branchId": branch_id,
+        "requested": list(config.target_languages),
+        "exported": list(exported_languages),
+        "path": str(destination),
+    }
+
+
+# 去除 XML 命名空间。
+def _local_name(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+# 读取资源元素的完整文本。
+def _element_text(element: ET.Element) -> str:
+    return "".join(element.itertext())
+
+
+# 解析资源并拒绝重复键。
+def parse_android_resources(path: Path) -> dict[str, AndroidResource]:
+    try:
+        root = ET.parse(path).getroot()
+    except FileNotFoundError as exc:
+        raise ScriptError(f"Android resource file not found: {path}") from exc
+    except ET.ParseError as exc:
+        raise ScriptError(f"Invalid Android XML {path}: {exc}") from exc
+    if _local_name(root.tag) != "resources":
+        raise ScriptError(f"Android XML root must be <resources>: {path}")
+
+    resources: dict[str, AndroidResource] = {}
+    for element in root:
+        kind = _local_name(element.tag)
+        if kind not in {"string", "plurals", "string-array"}:
+            continue
+        name = element.get("name", "").strip()
+        if not name:
+            raise ScriptError(f"Android resource without a name in {path}")
+        if name in resources:
+            raise ScriptError(f"Duplicate Android resource {name!r} in {path}")
+        if kind == "string":
+            values: Any = _element_text(element)
+        elif kind == "string-array":
+            values = tuple(
+                _element_text(item)
+                for item in element
+                if _local_name(item.tag) == "item"
+            )
+        else:
+            forms: dict[str, str] = {}
+            for item in element:
+                if _local_name(item.tag) != "item":
+                    continue
+                quantity = item.get("quantity", "")
+                if quantity not in ANDROID_PLURAL_QUANTITIES:
+                    raise ScriptError(
+                        f"Unsupported plural quantity {quantity!r} for {name!r} in {path}"
+                    )
+                if quantity in forms:
+                    raise ScriptError(
+                        f"Duplicate plural quantity {quantity!r} for {name!r}"
+                    )
+                forms[quantity] = _element_text(item)
+            if "other" not in forms:
+                raise ScriptError(
+                    f"Plural resource {name!r} must include quantity 'other'"
+                )
+            values = forms
+        resources[name] = AndroidResource(kind=kind, values=values)
+    return resources
+
+
+# 合并源文件并拒绝跨文件重复键。
+def parse_push_resources(config: Config) -> dict[str, AndroidResource]:
+    resources: dict[str, AndroidResource] = {}
+    resource_paths: dict[str, Path] = {}
+    for item in config.push_files:
+        parsed = parse_android_resources(item.path)
+        duplicate_names = sorted(set(resources) & set(parsed))
+        if duplicate_names:
+            name = duplicate_names[0]
+            raise ScriptError(
+                f"Duplicate Android resource {name!r} across "
+                f"{resource_paths[name]} and {item.path}"
+            )
+        resources.update(parsed)
+        resource_paths.update({name: item.path for name in parsed})
+    return resources
+
+
+# 规范化 printf 占位符签名。
+def placeholder_signature(value: str) -> tuple[tuple[int, str], ...]:
+    implicit_position = 1
+    previous_position: Optional[int] = None
+    signature: list[tuple[int, str]] = []
+    for match in JAVA_PLACEHOLDER_RE.finditer(value):
+        specifier = match.group(5).lower()
+        if specifier in {"%", "n"}:
+            continue
+        flags = match.group(2)
+        if match.group(1):
+            position = int(match.group(1))
+        elif "<" in flags:
+            if previous_position is None:
+                raise ScriptError(f"Invalid relative printf placeholder in {value!r}")
+            position = previous_position
+        else:
+            position = implicit_position
+            implicit_position += 1
+        previous_position = position
+        if specifier.startswith("t"):
+            category = "datetime"
+        elif specifier[-1:] in {"d", "o", "x"}:
+            category = "integer"
+        elif specifier[-1:] in {"a", "e", "f", "g"}:
+            category = "float"
+        elif specifier[-1:] == "c":
+            category = "character"
+        elif specifier[-1:] == "b":
+            category = "boolean"
+        else:
+            category = "string"
+        signature.append((position, category))
+    return tuple(sorted(signature))
+
+
+# 校验类型、数组长度与占位符。
+def _validate_resource_value(
+    key: str, base: AndroidResource, target: AndroidResource, target_path: Path
+) -> None:
+    if base.kind != target.kind:
+        raise ScriptError(
+            f"Resource type mismatch for {key!r} in {target_path}: "
+            f"expected {base.kind}, got {target.kind}"
+        )
+    if base.kind == "string":
+        if placeholder_signature(base.values) != placeholder_signature(target.values):
+            raise ScriptError(f"Placeholder mismatch for {key!r} in {target_path}")
+        return
+    if base.kind == "string-array":
+        if len(base.values) != len(target.values):
+            raise ScriptError(f"Array length mismatch for {key!r} in {target_path}")
+        for index, (base_value, target_value) in enumerate(
+            zip(base.values, target.values)
+        ):
+            if placeholder_signature(base_value) != placeholder_signature(target_value):
+                raise ScriptError(
+                    f"Placeholder mismatch for {key!r}[{index}] in {target_path}"
+                )
+        return
+
+    base_signatures = {placeholder_signature(value) for value in base.values.values()}
+    if len(base_signatures) != 1:
+        raise ScriptError(
+            f"Base plural {key!r} has inconsistent placeholder signatures"
+        )
+    expected = next(iter(base_signatures))
+    for quantity, value in target.values.items():
+        if placeholder_signature(value) != expected:
+            raise ScriptError(
+                f"Placeholder mismatch for {key!r}[{quantity}] in {target_path}"
+            )
+
+
+# 移除不完整数组以回退基础资源。
+def _remove_incomplete_arrays(
+    path: Path, base: dict[str, AndroidResource]
+) -> tuple[tuple[str, int, int], ...]:
+    parser = ET.XMLParser(target=ET.TreeBuilder(insert_comments=True))
+    try:
+        tree = ET.parse(path, parser=parser)
+    except ET.ParseError as exc:
+        raise ScriptError(f"Invalid Android XML {path}: {exc}") from exc
+    root = tree.getroot()
+    removed: list[tuple[str, int, int]] = []
+    for element in list(root):
+        if (
+            not isinstance(element.tag, str)
+            or _local_name(element.tag) != "string-array"
+        ):
+            continue
+        name = element.get("name", "").strip()
+        base_resource = base.get(name)
+        if base_resource is None or base_resource.kind != "string-array":
+            continue
+        item_count = sum(
+            1
+            for item in element
+            if isinstance(item.tag, str) and _local_name(item.tag) == "item"
+        )
+        expected_count = len(base_resource.values)
+        if item_count < expected_count:
+            root.remove(element)
+            removed.append((name, item_count, expected_count))
+    if removed:
+        ET.indent(tree, space="  ")
+        tree.write(path, encoding="utf-8", xml_declaration=True)
+    return tuple(removed)
+
+
+# 校验生成路径和翻译资源兼容性。
+def validate_resources(
+    config: Config,
+    *,
+    pull_path: Optional[Path] = None,
+    fallback_incomplete_arrays: bool = False,
+) -> tuple[str, ...]:
+    destination = pull_path or config.pull_path
+    base = parse_push_resources(config)
+    expected = {
+        render_export_path(
+            config.pull_file_structure_template,
+            language,
+            config.namespace,
+        ): language
+        for language in config.target_languages
+    }
+    if destination.exists():
+        unexpected = sorted(
+            {
+                p.relative_to(destination).parts[0]
+                for p in destination.rglob("*")
+                if p.is_file()
+                and PurePosixPath(p.relative_to(destination).as_posix()) not in expected
+            }
+        )
+        if unexpected:
+            raise ScriptError(
+                f"Generated resources contain unexpected={','.join(unexpected)}"
+            )
+    validated_languages = []
+    fallbacks = []
+    for relative, language in sorted(expected.items(), key=lambda item: str(item[0])):
+        path = destination.joinpath(*relative.parts)
+        if not path.is_file():
+            continue
+        if fallback_incomplete_arrays:
+            fallbacks.extend(
+                (language, name, actual, expected_count)
+                for name, actual, expected_count in _remove_incomplete_arrays(
+                    path, base
+                )
+            )
+        target = parse_android_resources(path)
+        unknown = sorted(set(target) - set(base))
+        if unknown:
+            raise ScriptError(
+                f"Generated resource contains unknown keys in {path}: {', '.join(unknown)}"
+            )
+        for key, resource in target.items():
+            _validate_resource_value(key, base[key], resource, path)
+        validated_languages.append(language)
+    if fallbacks:
+        details = ", ".join(
+            f"{language}:{name}({actual}/{expected_count})"
+            for language, name, actual, expected_count in fallbacks
+        )
+        print(f"Array fallback applied: {details}")
+    print(
+        f"Validation completed: languages={','.join(validated_languages) or 'none'} "
+        f"directory={destination}"
+    )
+    return tuple(validated_languages)
+
+
+# 从已安装包元数据读取唯一版本。
+def installed_version() -> str:
+    try:
+        return version("lingora-cli")
+    except PackageNotFoundError:
+        return "0.0.0.dev0"
+
+
+# 只创建无密钥配置，可填入显式连接参数，不覆盖已有文件。
+def initialize_config(path: Path, overrides: dict[str, str] | None = None) -> None:
+    template = (
+        files("lingora_cli").joinpath("config.example.json").read_text(encoding="utf-8")
+    )
+    if overrides:
+        if set(overrides) - {"apiUrl", "projectId", "branch"}:
+            raise ScriptError(
+                "init only accepts API URL, project ID and branch overrides"
+            )
+        data = json.loads(template)
+        if "apiUrl" in overrides:
+            _validate_url(overrides["apiUrl"], "apiUrl")
+        if "projectId" in overrides:
+            try:
+                uuid.UUID(overrides["projectId"])
+            except ValueError as exc:
+                raise ScriptError(
+                    "Configuration field 'projectId' must be a UUID"
+                ) from exc
+        if any(not value.strip() for value in overrides.values()):
+            raise ScriptError(
+                "Initial configuration parameters must be non-empty strings"
+            )
+        data.update(overrides)
+        template = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    with path.expanduser().open("x", encoding="utf-8") as output:
+        output.write(template)
+    print(
+        f"Created {path}; configure your API URL, project, branch and resource paths."
+    )
+
+
+# 声明独立操作及完整参数，不编排消费项目的 CI。
+def build_parser() -> argparse.ArgumentParser:
+    from .options import build_parser as parser
+
+    return parser(installed_version())
+
+
+# 按命令路径查询帮助，不加载配置或触发任何 I/O。
+def command_help(parser: argparse.ArgumentParser, topic: list[str]) -> str:
+    for name in topic:
+        children = next(
+            (
+                action
+                for action in parser._actions
+                if isinstance(action, argparse._SubParsersAction)
+            ),
+            None,
+        )
+        if children is None or name not in children.choices:
+            raise ScriptError(f"Unknown help topic: {name}")
+        parser = children.choices[name]
+    return parser.format_help()
+
+
+# 执行一个独立操作并返回可序列化的数据；写操作保留各自的确认门禁。
+def execute(
+    args: argparse.Namespace, parser: argparse.ArgumentParser
+) -> tuple[object, int]:
+    from . import commands, delivery, options
+
+    if not math.isfinite(args.timeout) or args.timeout <= 0:
+        raise ScriptError("--timeout must be greater than zero")
+    if args.config is not None and args.no_config:
+        raise ScriptError("--config and --no-config cannot be combined")
+    if args.command == "help":
+        return {"usage": command_help(parser, args.topic)}, 0
+    if args.command == "init":
+        path = args.config or default_config_path()
+        overrides = {
+            key: value
+            for key, value in (
+                ("apiUrl", args.api_url),
+                ("projectId", args.project_id),
+                ("branch", args.branch),
+            )
+            if value is not None
+        }
+        initialize_config(path, overrides)
+        return {"path": str(path.resolve())}, 0
+    path, data = options.read_options(args)
+    if args.command == "delivery":
+        if args.url:
+            if args.namespace is None or not args.languages:
+                raise ScriptError(
+                    "delivery check --url requires --namespace and --languages (including base)"
+                )
+            return delivery.check_url(
+                args.url, args.namespace, args.languages, args.timeout
+            ), 0
+        config = load_config(path, data=data, operation="delivery")
+        return delivery.check_delivery(config, args.alias, args.timeout), 0
+    if args.command in {"branch", "merge", "tag"}:
+        connection = options.project_config(data)
+        api_key = require_api_key(args.api_key)
+        return getattr(commands, args.command)(connection, api_key, args), 0
+    config = load_config(
+        path, data=options.resource_config(args, data), operation=args.command
+    )
+    if args.command == "extract":
+        result = commands.extracted(config)
+        if args.extract_command == "check":
+            return {"valid": True, "keyCount": len(result["keys"])}, 0
+        return result, 0
+    if args.command == "validate":
+        return {
+            "languages": list(validate_resources(config)),
+            "path": str(config.pull_path),
+        }, 0
+    branch = select_branch(args.branch, config.branch)
+    api_key = require_api_key(args.api_key)
+    if args.command == "push":
+        return push_resources(
+            config,
+            api_key,
+            branch,
+            config.push_force_mode,
+            config.push_remove_other_keys,
+            timeout=args.timeout,
+        ), 0
+    if args.command == "pull":
+        return pull_resources(config, api_key, branch, timeout=args.timeout), 0
+    if args.command == "compare":
+        result = commands.compare(config, api_key, branch, args.timeout)
+        in_sync = not result["added"] and not result["unused"]
+        return {**result, "inSync": in_sync}, int(args.check and not in_sync)
+    if args.command == "sync":
+        return commands.sync(config, api_key, branch, args), 0
+    raise ScriptError("Unsupported command")
+
+
+# 屏蔽环境密钥和命令行密钥，包括参数解析尚未成功的情况。
+def redact(text: str, tokens: list[str]) -> str:
+    secrets = [os.environ.get("LINGORA_API_KEY", "")]
+    for index, token in enumerate(tokens):
+        if token == "--api-key" and index + 1 < len(tokens):
+            secrets.append(tokens[index + 1])
+        elif token.startswith("--api-key="):
+            secrets.append(token.split("=", 1)[1])
+    for secret in secrets:
+        if secret:
+            text = text.replace(secret, "[REDACTED]")
+    return text
+
+
+# 先屏蔽字符串值再序列化，避免含引号或换行的密钥破坏 JSON 或绕过脱敏。
+def safe_json(value: object, tokens: list[str], *, indent: int | None = None) -> str:
+    # 只递归清理数据，不修改固定协议字段的名称。
+    def clean(item: object) -> object:
+        if isinstance(item, str):
+            return redact(item, tokens)
+        if isinstance(item, dict):
+            return {key: clean(child) for key, child in item.items()}
+        if isinstance(item, (list, tuple)):
+            return [clean(child) for child in item]
+        return item
+
+    return json.dumps(clean(value), ensure_ascii=False, indent=indent)
+
+
+# 为人和 MCP 提供同一个入口；JSON 模式的 stdout 只包含一个结果，诊断输出保留在 stderr。
+def main(argv: Optional[list[str]] = None) -> int:
+    tokens = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    defaults = argparse.Namespace(
+        config=None,
+        no_config=False,
+        api_url=None,
+        project_id=None,
+        api_key=None,
+        branch=None,
+        timeout=DEFAULT_TIMEOUT_SECONDS,
+        json=False,
+    )
+    parse_error = io.StringIO()
+    try:
+        with redirect_stderr(parse_error):
+            args = parser.parse_args(tokens, namespace=defaults)
+    except SystemExit as exc:
+        if exc.code and "--json" in tokens:
+            print(
+                safe_json(
+                    {
+                        "ok": False,
+                        "command": None,
+                        "data": None,
+                        "error": {"message": parse_error.getvalue().strip()},
+                        "exitCode": 2,
+                    },
+                    tokens,
+                )
+            )
+            return 2
+        print(redact(parse_error.getvalue(), tokens), end="", file=sys.stderr)
+        raise
+    output = io.StringIO()
+    warnings = io.StringIO()
+    error = None
+    data = None
+    try:
+        with redirect_stdout(output), redirect_stderr(warnings):
+            data, status = execute(args, parser)
+        if status:
+            error = {"message": "Local and remote key sets differ"}
+    except (ScriptError, OSError, zipfile.BadZipFile) as exc:
+        status = 1
+        error = {"message": str(exc), "details": getattr(exc, "details", {})}
+    command = " ".join(
+        filter(
+            None,
+            (
+                args.command,
+                getattr(args, "extract_command", None),
+                getattr(args, "delivery_command", None),
+            ),
+        )
+    )
+    if args.json:
+        print(
+            safe_json(
+                {
+                    "ok": status == 0,
+                    "command": command,
+                    "data": data,
+                    "error": error,
+                    "exitCode": status,
+                },
+                tokens,
+            )
+        )
+    elif error:
+        print(redact(f"error: {error['message']}", tokens), file=sys.stderr)
+    elif args.command == "help":
+        print(data["usage"], end="")
+    elif output.getvalue():
+        print(redact(output.getvalue(), tokens), end="")
+    else:
+        print(safe_json(data, tokens, indent=2))
+    if warnings.getvalue():
+        print(redact(warnings.getvalue(), tokens), end="", file=sys.stderr)
+    return status
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())