SuperAPI AI 工具集

asc-subscription-localization

部署与运维

查看项目

更新于 10-16 10:52

技能介绍

该技能通过 asc 命令行工具,实现 App Store Connect 中订阅、订阅组与内购项目展示名称的批量本地化,适用于需要为多个 App Store 地区设置相同或翻译后展示名称的场景,替代逐语言手动点击的过程。

使用前提:需已配置 asc 认证(通过 asc auth login 或 ASC_* 环境变量),已知应用 ID(ASC_APP_ID 或 --app),且订阅组与订阅已存在。

API 范围选择:API 4.4.1 为内购、订阅和订阅组引入了独立的版本资源,版本 ID 与产品、订阅或组 ID 不同。所有新的本地化工作应使用 asc ... versions localizations ... 命令,不要使用产品级或组级的 v1 本地化命令,这些资源在 API 4.4.1 中已被弃用,CLI 会对其兼容命令发出迁移警告。切勿将产品、订阅或组 ID 传给版本级命令。

版本解析:先列出并解析出唯一的可变版本。对内购、订阅和订阅组版本分别执行 versions list(配合 --state PREPARE_FOR_SUBMISSION、--paginate 与 --output table)。根据列表结果独立分支:零匹配表示创建,一匹配表示复用该版本 ID,多于一个匹配则停止并要求显式指定版本 ID。创建命令仅在零匹配分支执行。三类版本均无删除命令;存在多个匹配时需显式指定 ID,且不要假设删除父级会清理为测试创建的版本。

支持的语言环境:ar-SA、ca、cs、da、de-DE、el、en-AU、en-CA、en-GB、en-US、es-ES、es-MX、fi、fr-CA、fr-FR、he、hi、hr、hu、id、it、ja、ko、ms、nl-NL、no、pl、pt-BR、pt-PT、ro、ru、sk、sv、th、tr、uk、vi、zh-Hans、zh-Hant。

从文件导入多个地区:将每个地区映射到其字段,写入一个 JSON 文件,再导入到已解析的版本 ID。导入会创建缺失地区、仅更新有差异字段、不会清空或删除,并报告每个地区的失败。可先使用 --dry-run 预览,再用 --confirm 执行。内购版本的 localizations import 使用相同的 name 与 description 字段;订阅组版本使用 name 与 customAppName。每个新增的订阅或内购地区都必须有非空描述。

主要工作流:

  1. 订阅版本(v2):列出已有本地化,仅为缺失地区创建,并核验。更新命令可区分省略值、非空字符串与 JSON null。不要将值标志与其对应的 --clear-name 或 --clear-description 标志组合使用。Apple 在线服务目前会拒绝空的 --description 和 --clear-description(因描述至少需一个字符)。因此,创建缺失的订阅版本本地化需要非空描述;仅更新名称的运行可以更新已有本地化的名称,但在用户提供非空的地区特定或共享回退描述之前,不得创建缺失地区。
  2. 订阅组版本(v2):列出、创建、更新并核验。清空元数据是单独且需明确选择的操作;仅在确认用户要移除已有自定义应用名后,才使用 --clear-custom-app-name。标准批量本地化工作流中不要包含 --clear-name 或 --clear-custom-app-name。
  3. 内购版本(v2):列出、创建、更新并核验。Apple 在线服务同样会拒绝空描述和 --clear-description,即使 4.4.1 schema 允许 JSON null。与订阅类似,仅更新名称的运行可以更新已有内购本地化,但在有非空描述之前不得创建缺失地区。
  4. 应用内全部订阅版本:先列出组并解析每个组唯一的可变版本,本地化组版本;再列出订阅并解析每个订阅唯一的可变版本,本地化订阅版本。对每个版本列表应用相同的零/一/多规则。

建议的代理行为:仅使用版本级 v2 资源进行新本地化工作;将版本 ID 与产品、订阅、组 ID 分开;始终先列出已有本地化以避免重复创建错误;缺失地区则创建,已有值不同则按解析出的本地化 ID 更新,已匹配则不做操作;用户提供单一展示名称时用于所有地区,提供各地区翻译名称时按地区使用;订阅与内购版本本地化在每次创建时要求非空 --description,若用户仅提供展示名称,则更新已有本地化、跳过缺失地区的创建,并在创建前询问地区特定描述或一个非空回退描述;对已有订阅或内购版本本地化的更新,除非用户提供了新的非空值,否则省略 --description,不得推断为空值或清空;订阅组版本本地化没有描述字段,正常创建或更新其名称,仅在用户提供该值时使用 --custom-app-name;核验步骤使用 --output table 以便目视确认;中间自动化步骤使用显式 --output json;批量写入后始终运行 list 命令核验完整性;订阅较多的应用按组顺序处理以保持输出可读;若某地区创建或更新失败,记录该地区与错误并继续处理其余地区,批次完成后统一报告所有失败。

说明:订阅展示名称是用户在订阅管理表单和购买对话框中看到的内容;为已存在的地区创建本地化会失败,需先列出再更新解析出的 ID;Apple 没有批量本地化端点,localizations import 会先校验整个文件再逐地区写入;列表命令应使用 --paginate 确保返回所有已有本地化;若只有应用名称而非 ID,可使用 asc-id-resolver 技能。

限制:该技能依赖已存在的订阅组、订阅与内购项目,不负责创建它们;三类版本均无删除命令;Apple 在线服务对空描述与清空描述存在拒绝行为;批量写入需逐地区进行,无原生批量端点。