Lingora CLI

独立安装的翻译同步工具；只调用 Lingora 公开 HTTP API，不依赖后端源码或 Android 仓库中的脚本。 需要 Python 3.12+。CLI 与后端、Maven SDK 的版本互不绑定。

安装与使用

首次 PyPI 发布完成后使用固定版本安装（当前代码不代表包已发布）：

uv tool install --python 3.12 "lingora-cli==0.1.0"
lingora --version
lingora init

编辑生成的 .lingorarc：设置 apiUrl、projectId、branch、源文件、目标语言和 Delivery URL。 init 不联网、不创建服务端项目、不覆盖已有配置；不要把 API Key 写进配置。 所有资源相对路径以配置文件所在目录为基准。多文件通过 push.files 配置，必须使用相同语言和 namespace、不同文件名，不允许重复资源键。 默认模板 namespace 为 app，与 Demo 的 app/{languageTag}.json 一致。

# 通过个人环境或 CI Secret 提供 LINGORA_API_KEY；不要将真实值写入文档。
lingora push
lingora pull
lingora validate
lingora delivery check --alias current

# 公共参数可放在子命令前后。
lingora pull --config ci/lingora.json --branch your-branch

CLI 只提供独立操作，不提供 mock-ci。上传、下载和构建的编排由消费项目的脚本或 CI 负责：

lingora push && lingora pull

push 会写入服务端；pull 只下载并校验资源，失败时不会触发上传。 完整参数、分支与 Key 管理、无配置调用、JSON 协议及 MCP 接入示例见独立的 命令手册。也可执行 lingora help push、lingora pull --help。

分支优先级：--branch > LINGORA_BRANCH > 配置；连接参数支持 LINGORA_API_URL、 LINGORA_PROJECT_ID，同样由命令参数优先覆盖。凭据优先级：--api-key > LINGORA_API_KEY。 建议使用环境变量，避免凭据出现在进程参数中。错误返回 1，参数用法错误返回 2。 pull.emptyDir=true 只应用于专门的生成目录；下载或校验失败不替换原目录。 不完整数组被移除，让 Android 回退基础资源；类型、占位符、未知键和额外文件仍然报错。

CLI 的 Delivery 检查 URL 与 App 的运行时 URL 分别配置，使用者需要确保二者指向同一资源且 namespace 一致。 Android 构建不执行 CLI，不上传翻译，也不读取 CLI 实现。

开发与验证

cd cli
make sync
make check
make test
make build

运行时无第三方依赖。构建使用 setuptools/setuptools-scm；开发依赖用于自动版本分析、lint 和安装包校验。 尚未正式发布前可在隔离环境安装本地 wheel 验证，但消费项目不应依赖本仓库的源码路径。

自动发布

专用工作流 .github/workflows/cli.yml：PR 只检查；develop 自动发布 rc 预发布，main 自动发布正式版。 只分析 CLI 相关 Conventional Commits：fix 升 patch，feat 升 minor，! 或 BREAKING CHANGE 升 major；docs、test、chore 不发版。 首次正式版本为 0.1.0。示例：

Tag 是版本来源，命令从安装元数据读取版本；不回写受保护分支，不移动 Tag，不覆盖 PyPI 包。 发版产物包含 SHA、版本、Tag 和 SHA256 清单；重跑同一 Actions run 时复用已上传的原产物。 失败后用 Actions 的 Re-run failed jobs 恢复，不新建同版本或手工移动 Tag。

所有者的一次性配置

1. 在 PyPI 创建 lingora-cli 的 pending Trusted Publisher：owner brain、repository lingora、workflow cli.yml、environment lingora-cli-pypi。
2. 在 GitHub 创建该 Environment，只允许 main 和 develop，不设置人工审批，以保留自动发版。
3. 确保 Actions 可以创建 lingora-cli-* Tag；限制其他身份修改、删除版本 Tag，不给予受保护分支绕过权限。
4. PyPI 配置或权限缺失会导致发布失败，不能当作发布成功。无需长期 PyPI Token。

首版成功发布且干净环境安装验收后，再删除主仓库及 Android 仓库的旧翻译脚本。 Android 的 sdk_release.py 等 Maven 发布脚本不属于待删除对象。

自动发版使用 Python Semantic Release 与 PyPI Trusted Publisher。