用途:覆盖“源文件到 Lokalise”方向的主流程,包括上传源翻译文件、以编程方式创建与更新键、为键打标签以便组织,以及执行批量操作。每个操作都给出 SDK 与 CLI 两种做法。
前提条件:需将 Lokalise API token 导出为 LOKALISE_API_TOKEN,项目 ID 导出为 LOKALISE_PROJECT_ID;SDK 示例需安装 @lokalise/node-api,CLI 示例需安装 lokalise2;源翻译文件需为受支持格式(JSON、XLIFF、PO、YAML 等)。
主要能力:上传源文件(异步,返回 process 对象需轮询至完成,SDK 用 Base64 编码上传,CLI 可用 --poll 等待);创建带描述、标签和初始翻译的键;更新已有键;按标签筛选键并批量打标签;批量删除键、批量更新翻译状态。
使用方式:SDK 通过 client.files().upload、client.keys().create/update/list/bulk_update/bulk_delete、client.translations().update 等调用;CLI 使用 lokalise2 file upload、key list、key update 等命令,可配合 jq 与循环处理。
适用场景:从代码扫描、CMS 导出或 CI 流水线生成键并推送;按发布版本打标签跟踪;大规模清理废弃键。
限制与错误处理:上传为异步需轮询;400 文件格式无效或键已存在(可设 replace_modified: true 或使用唯一键名);413 载荷超过 50MB 需拆分;429 超过 6 请求/秒需加约 170ms 延迟;进程状态 failed 需检查文件内容与编码;批量操作 keys 必须为数组。下载翻译与管理贡献者见 lokalise-core-workflow-b。