Lingora CLI 命令手册

需要 Python 3.12+。以下示例假设已安装指定版本 lingora-cli；示例 UUID、域名和分支均为占位值， 不包含真实凭据。所有 HTTP 操作都使用 Lingora 公开 API。

安装与首次配置

# 本地试用；CI 和消费项目应改为固定版本 lingora-cli==x.y.z。
uv tool install --python 3.12 lingora-cli
lingora --version

# 使用包内的 lingora_example.json 模板，在当前目录创建 .lingorarc；不会联网，也不会覆盖已有文件。
lingora config init

同时同步 Apple .strings + .stringsdict 时使用 Web 同名的导出格式；每个 namespace 都提供一对基础文件：

{
  "push": {
    "files": [
      {"path": "Resources/en-US.lproj/app.strings", "language": "en-US", "namespace": "app"},
      {"path": "Resources/en-US.lproj/app.stringsdict", "language": "en-US", "namespace": "app"},
      {"path": "Resources/en-US.lproj/common.strings", "language": "en-US", "namespace": "common"},
      {"path": "Resources/en-US.lproj/common.stringsdict", "language": "en-US", "namespace": "common"}
    ]
  },
  "pull": {
    "format": "apple-strings-stringdict",
    "path": "Generated",
    "languages": ["ja", "zh-CN"],
    "namespaces": ["app", "common"],
    "fileStructureTemplate": "{languageTag}.lproj/{namespace}.{extension}",
    "emptyDir": true
  }
}

创建完成后，至少需要把 .lingorarc 中的 apiUrl、projectId、branch、 push.files 和 pull.languages 改成目标项目的真实值，后续命令会默认读取该文件。 API Key 不得写入配置文件，应通过 LINGORA_API_KEY 或临时的 --api-key 参数提供。

1. 命令总览

lingora --help 显示顶层命令；lingora COMMAND --help 显示参数； lingora help COMMAND [SUBCOMMAND] 返回同一份帮助并支持 --json；lingora --version 显示安装包版本。这些帮助命令不会读取配置或访问网络。

不提供项目级 mock-ci 命令。消费项目自行编排 lingora push && lingora pull。 正常 Android Gradle 或 iOS Xcode 构建不执行这些命令。

push / pull / validate 支持 Web 页面公开的完整导入、导出格式矩阵。同次 push 使用一个基础语言， 每个文件可属于不同 namespace；pull namespace 独立选择，省略或配置空数组表示服务端全部 namespace。 Android XML 与 Apple 资源会做键、类型、placeholder 等本地深度校验； 其他格式由服务端解析，CLI 在上传前校验文件存在且非空，在下载后校验归档路径、文件集合和非空内容。 extract、compare、sync 仅支持有本地解析器的 Android XML 与 Apple 资源，并会对其他格式明确报错。 extract 不扫描 Kotlin、Swift、React、Vue、Svelte 或 Angular 源码；不提供自定义执行器、 持续 watch、浏览器登录或本机凭据存储。sync 是资源键同步，不是上传后再下载。 这些未实现能力不会注册为空壳命令。

2. 通用参数与优先级

通用参数可放在命令前后，嵌套命令同样适用，例如 lingora --json branch 和 lingora delivery check --alias current --json。

默认读取当前目录的 .lingorarc；没有该文件时，可仅通过完整参数执行。 显式配置缺失、内容非法或含 apiKey 时必须失败，不静默忽略。

配置优先级：命令参数 > LINGORA_API_URL / LINGORA_PROJECT_ID / LINGORA_BRANCH > JSON。 凭据优先级：--api-key > LINGORA_API_KEY。凭据不写入配置、安装包或本机凭据文件。 文件中资源相对路径以配置目录为准；命令行 --files、--path 相对路径以当前目录为准。

lingora config init
# 或者指定文件并在首次创建时填入连接信息；已有文件时不可再次创建。
lingora config init --config ci/lingora.json \
  --api-url https://lingora.example.com \
  --project-id 11111111-1111-1111-1111-111111111111 --branch develop
lingora push --config ci/lingora.json --branch develop
lingora pull --config ci/lingora.json --branch develop --json

lingora init 保留为兼容入口，行为与 lingora config init 相同。查看命令级帮助：

lingora help config init
lingora push --help

3. 配置文件完整说明

3.1 创建配置

lingora config init [--config PATH] [--api-url URL] [--project-id UUID] [--branch NAME]

命令使用排他创建，不覆盖已有文件；即使传入 --api-key，密钥也不会写入模板。

3.2 完整模板

包内 lingora_example.json 模板及 config init 生成的 .lingorarc 内容如下；字段用途、是否必填和默认值见下一节。

{
  "apiUrl": "https://lingora.example.com",
  "projectId": "00000000-0000-0000-0000-000000000000",
  "branch": "your-branch",
  "push": {
    "files": [
      {
        "path": "app/src/main/res/values/strings.xml",
        "language": "en",
        "namespace": "app"
      }
    ],
    "forceMode": "NO_FORCE",
    "overrideMode": "RECOMMENDED",
    "errorOnUnresolvedConflict": "auto",
    "overrideKeyDescriptions": false,
    "convertPlaceholdersToIcu": false,
    "tagNewKeys": [],
    "removeOtherKeys": false
  },
  "pull": {
    "format": "android-xml",
    "path": "generated/lingora/res",
    "languages": ["zh-CN"],
    "namespaces": ["app"],
    "states": ["TRANSLATED", "REVIEWED"],
    "fileStructureTemplate": "values-{androidLanguageTag}/{namespace}.xml",
    "emptyDir": true,
    "tags": [],
    "excludeTags": [],
    "supportArrays": false,
    "includeEmptyTranslations": false
  }
}

3.3 顶层字段

配置优先级为命令参数 > 环境变量 > JSON。配置中的相对资源路径以配置文件目录为基准； 命令行传入的相对路径以当前工作目录为基准。

3.4 push 字段

3.5 pull 字段

3.6 Web 格式矩阵

push.files[].format 可省略并按扩展名检测；同扩展名存在不同语义时应显式填写：

pull.format 接受 Web 页面公开的导出 ID：

flat-json, nested-json, xliff, gettext-po, java-properties,
flat-yaml, structured-yaml, csv, xlsx, apple-strings-stringdict,
apple-xliff, apple-xcstrings, apple-sdk, android-xml, android-sdk,
compose-xml, flutter-arb, ruby-yaml, i18next-json,
i18next-structured-json, resx

csv、xlsx、apple-xcstrings 是多语言单文件，默认输出为 {namespace}/translations.{extension}；android-sdk 还会生成根目录 manifest.json。 旧配置中的顶层 ANDROID_XML 和 APPLE_STRINGS 仍兼容，分别映射到 android-xml 和 apple-strings-stringdict。使用 Apple 本地深度校验时，每个包含 Apple 基础资源的 namespace 必须同时配置 .strings 和 .stringsdict；JSON 等其他基础格式仍可导出为 Apple 文件。

3.7 contentDeliveries 字段

每个键是本地别名，每个值是公开 Delivery 根 URL。例如：

{
  "contentDeliveries": {
    "current": "https://cdn.example.com/project/channel"
  }
}

随后可运行 lingora delivery check --alias current。该 URL 只用于 CLI 检查；Android App 仍需在自己的运行时配置中设置 Delivery URL，并确保 URL 与 namespace 对应同一份资源。

4. push：完整参数上传

所有必要配置都可以直接跟在 push 后面，无须 .lingorarc。先通过安全的个人环境或 CI Secret 注入 LINGORA_API_KEY，不要将真实密钥直接写在示例命令或版本化文件里。

lingora push \
  --no-config \
  --api-url https://lingora.example.com \
  --project-id 11111111-1111-1111-1111-111111111111 \
  --branch develop \
  --files app/src/main/res/values/strings.xml app/src/main/res/values/arrays.xml \
  --base-language en-US \
  --namespace app \
  --format ANDROID_XML \
  --force-mode NO_FORCE \
  --override-mode RECOMMENDED \
  --error-on-unresolved-conflict auto \
  --no-override-key-descriptions \
  --no-convert-placeholders-to-icu \
  --no-remove-other-keys \
  --json

push 仅要求连接、分支和源文件信息，不要求配置下载目标语言。

push.files 的多个文件通过一次 multipart import 提交，而不是分别上传后删除彼此的资源。 配置文件可为每个文件分别指定 format；命令行 --format 会应用到本次所有 --files。 服务端保护、权限不足或冲突仍会使操作失败，CLI 不绕过限制。

5. pull 与 validate：下载和本地校验

lingora pull \
  --no-config \
  --api-url https://lingora.example.com \
  --project-id 11111111-1111-1111-1111-111111111111 \
  --branch develop \
  --files app/src/main/res/values/strings.xml app/src/main/res/values/arrays.xml \
  --base-language en-US \
  --namespace app \
  --format android-xml \
  --languages ja zh-CN \
  --path generated/lingora/res \
  --states TRANSLATED REVIEWED \
  --file-structure-template 'values-{androidLanguageTag}/{namespace}.xml' \
  --empty-dir \
  --json

lingora validate --config .lingorarc --json

Android XML 和 Apple 基础文件用于类型、占位符和数组长度等深度校验；其他格式由服务端解析， 本地只校验输出路径、文件集合和非空内容。基础文件不会随下载覆盖。 pull / validate 可使用 --files、--base-language、--namespace、--format，以及：

validate 不联网、不写文件；下载相关筛选参数仅影响 pull 的请求。 下载、解包或校验失败不替换旧目录；Android 不完整目标数组在下载暂存目录中整组移除，以使用 APK fallback。 不允许输出目录包含配置或源资源，也不允许 ZIP 路径穿越、额外文件或覆盖基础文件。 没有目标翻译时可成功但显示 exported=none；本地 validate 的 languages=[] 不代表翻译已下载。

6. extract、compare、sync：资源键工作流

# 本地读取资源键；数组转换为 days[0]、days[1] 等键。
lingora extract print --config .lingorarc --json
lingora extract check --config .lingorarc --json

# 仅比较键名集合，不比较所有翻译值；--check 在有差异时返回 1。
lingora compare --config .lingorarc --branch develop --json
lingora compare --config .lingorarc --check --json

# 先预览，再明确批准补齐缺失键。不会覆盖已有值或描述，不下载资源。
lingora sync --config .lingorarc --dry-run --json
lingora sync --config .lingorarc --yes --tag-new-keys added-by-cli --json

# 可选删除当前 namespace 内未出现在本地输入中的键。
lingora sync --config .lingorarc --yes --remove-unused --json

三个命令都可使用 --files、--base-language、--namespace 和导入 --format 指定源资源， 也支持第 2 节的通用参数。

以上命令只支持 Android XML 与 Apple .strings + .stringsdict 的本地解析；其他导入格式会明确失败。 配置含多个 push namespace 时必须传 --namespace，命令只读取并写入该 namespace；sync 不会上传其他 namespace。 extract 不要求服务地址、项目 ID 或密钥。 compare 和 sync 需要项目、分支和凭据，不要求下载配置。 sync 固定使用 KEEP，只有差异需要写入时才要求 --yes；--remove-unused 不从配置自动开启。 unused 仅表示“不在这组输入文件里”，并不证明项目没有使用这些键；不要未审查就自动删除。 服务器键分页不完整、重复或总数变化时会失败，不拿部分列表继续写操作。

7. tag：管理 Key 标签

# 必须指定 namespace，以及 --keys 或 --all 范围。
lingora tag --config .lingorarc --namespace app \
  --keys hello welcome --tag android release --dry-run --json

lingora tag --config .lingorarc --namespace app \
  --keys hello welcome --tag android release --yes --json

lingora tag --config .lingorarc --namespace app --all \
  --filter-tag 'old-*' --filter-no-tag protected \
  --untag 'old-*' --tag current --yes --json

--tag 增加标签，--untag 移除标签；移除和筛选支持 shell 风格通配符，使用引号避免 shell 展开。 --filter-tag 匹配任一已有标签，--filter-no-tag 排除命中标签的键。 该命令不要求 Android 文件。每个 Key 单独请求，不是跨 Key 事务；失败时 JSON 错误的 details.updatedKeyIds 给出已经写入的 Key，partial 表示是否部分完成。 不要并发运行多个标签修改器，当前接口没有跨请求的标签并发合并机制。

8. branch 与 merge：项目分支

lingora branch --config .lingorarc --json
lingora branch feature/demo --config .lingorarc --origin develop --json
lingora branch --create feature/demo --config .lingorarc --origin develop --json
lingora branch --delete feature/demo --config .lingorarc --yes --json

# 创建服务端预览，但不合并文案。
lingora merge feature/demo --config .lingorarc --json

# 再创建并检查最新预览，无未解决冲突且未过时才应用。
lingora merge feature/demo --config .lingorarc --apply --yes --json

branch 参数：

merge 参数：

这些命令不要求本地 Android 文件，支持仅用 --api-url、--project-id 和环境密钥执行。 创建分支的来源必须来自 --origin 或配置的 branch，不会猜测 Git 分支。 合并目标由服务端的来源分支关系确定；不允许 CLI 自动解决冲突或跳过过时预览检查。 只有显式传 --delete-source-branch 才在合并后请求删除来源分支，未完成任务的额外保护仍由服务端执行。 查看分支需要 translations.view，分支写入和合并需要 branch.management。

9. delivery check：公开 CDN 检查

lingora delivery check --config .lingorarc --alias current --json

# 完全独立于项目配置和 API Key；languages 包含基础语言。
lingora delivery check --no-config \
  --url https://cdn.example.com/your-prefix \
  --namespace app --languages en-US ja zh-CN --json

读取 manifest.json 和 <namespace>/<locale>.json，检查语言集合与翻译值类型。 缺少缓存头会作为 warnings 返回，不等于发布失败。 检查可读不能证明它来自最新项目或最近发布；该命令不创建或发布 Delivery。 App 仍自行配置运行时 Delivery URL，不从 CLI 配置或凭据读取。

10. JSON 协议、退出码与 MCP 调用

--json 的 stdout 只输出一个 JSON 文档，无进度文本；stderr 保留脱敏警告。

{
  "ok": true,
  "command": "push",
  "data": {"affected": 3, "deleted": 0},
  "error": null,
  "exitCode": 0
}

失败时 ok=false、error.message 给出原因；部分操作可带 error.details。 退出码：0 成功；1 执行、校验、网络或凭据失败；2 命令参数错误。 compare --check 检测到键差异也返回 1，但会保留 data 中的差异结果。 --help / --version 是终端展示选项，不返回这个 JSON 协议；需要 JSON 帮助时使用 help ... --json。

MCP 层应构造参数数组调用固定版本命令，不拼接 shell，也不要从文本日志猜结果：

import json
import os
import subprocess

result = subprocess.run(
    [
        "lingora", "push", "--no-config",
        "--api-url", "https://lingora.example.com",
        "--project-id", "11111111-1111-1111-1111-111111111111",
        "--branch", "develop",
        "--files", "app/src/main/res/values/strings.xml",
        "--base-language", "en-US", "--namespace", "app",
        "--force-mode", "NO_FORCE", "--json",
    ],
    env=os.environ.copy(),  # MCP 服务预先通过 Secret 注入 LINGORA_API_KEY。
    capture_output=True,
    text=True,
    timeout=120,
    check=False,
)
payload = json.loads(result.stdout)

MCP 还应对服务地址、可读写目录、项目和允许执行的写命令建立白名单，并在调用端获取写入授权。 stdout 与 stderr 不得混流；超时后不要盲目重试写操作，应先核对远端是否已经提交。 此处仅定义供自建 MCP 封装使用的 CLI 调用契约，不包含 CLI 的 MCP Server 实现。 Lingora 已有的 OAuth 远程 MCP 服务 直接复用后端用例， 不经过 CLI，也不使用这里的 LINGORA_API_KEY；两种接入方式的认证和调用链相互独立。