Metadata-Version: 2.4
Name: lingora-cli
Version: 0.1.0rc1
Summary: Lingora translation synchronization CLI
Project-URL: Repository, https://github.com/brain/lingora
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Lingora CLI

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

## 安装与使用

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

```bash
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` 一致。

```bash
# 通过个人环境或 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 负责：

```bash
lingora push && lingora pull
```

`push` 会写入服务端；`pull` 只下载并校验资源，失败时不会触发上传。
完整参数、分支与 Key 管理、无配置调用、JSON 协议及 MCP 接入示例见独立的
[命令手册](COMMANDS.md)。也可执行 `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 实现。

## 开发与验证

```bash
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。示例：

| 分支 | Git Tag | PyPI 版本 |
| --- | --- | --- |
| develop | lingora-cli-0.1.0-rc.1 | 0.1.0rc1 |
| main | lingora-cli-0.1.0 | 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](https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration-guides/monorepos.html)
与 [PyPI Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)。
