asc-subscription-localization

asc subscription localization

使用此 Skill 可以在所有 App Store Connect 支持的语言区中，批量创建或更新订阅、订阅组和内购项目（IAP）的显示名称及描述（若支持）。这无需再逐个点击 App Store Connect 后台的语言页面去重复填写相同名称，省去了繁琐的手工操作。

前提条件

• 已配置身份认证（运行 asc auth login 或设置 ASC_* 环境变量）。
• 明确应用 ID（使用 ASC_APP_ID 环境变量或 --app 参数）。
• 对应的订阅组和订阅项目已存在。

优先选择正确的 API 作用域

API 4.4.1 为 IAP、订阅及订阅组引入了独立的版本概念。版本 ID（Version ID）与产品 ID（Product ID）、订阅 ID（Subscription ID）或订阅组 ID（Group ID）并不相同。

• 所有新的本地化工作均须使用 asc ... versions localizations ... 路径下的命令。
• 切勿使用产品作用域或订阅组作用域的 v1 本地化命令。API 4.4.1 已经弃用了这些资源，CLI 对其兼容命令会输出迁移警告。
• 绝不要向版本作用域（version-scoped）的命令中传入产品 ID、订阅 ID 或订阅组 ID。

在进行本地化配置前，先查询或创建对应的版本：

asc iap versions list --iap-id "IAP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output table
asc subscriptions versions list --subscription-id "SUB_ID" --state PREPARE_FOR_SUBMISSION --paginate --output table
asc subscriptions groups versions list --group-id "GROUP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output table

根据各个查询结果分别分支处理：匹配数为 0 则创建版本；匹配数为 1 则复用该版本 ID；若匹配数大于 1，则停止执行并要求指定明确的版本 ID。仅在匹配数为 0 的分支下运行下列对应创建命令：

# 仅当 IAP 版本列表返回 0 个匹配项时运行：
asc iap versions create --iap-id "IAP_ID" --output json
# 仅当订阅版本列表返回 0 个匹配项时运行：
asc subscriptions versions create --subscription-id "SUB_ID" --output json
# 仅当订阅组版本列表返回 0 个匹配项时运行：
asc subscriptions groups versions create --group-id "GROUP_ID" --output json

这三类版本均未提供版本删除命令。请查询并复用唯一处于 PREPARE_FOR_SUBMISSION 状态的版本；只有在匹配数为 0 时才创建新版本，存在多个匹配时必须暂停并提示要求提供明确 ID。由于线上删除父级对象并不会级联删除对应的 IAP 或订阅版本，因此切勿假定删除父级对象就能清理掉测试时创建的版本。

支持的 App Store 语言区（Locales）

以下是 App Store Connect 为订阅及 IAP 本地化所支持的语言区代码：

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

工作流：批量本地化订阅版本（v2）

先列出已有本地化项，仅创建缺少的语言区，最后进行验证：

asc subscriptions versions localizations list --version-id "VERSION_ID" --paginate --output table
asc subscriptions versions localizations create --version-id "VERSION_ID" --locale "LOCALE" --name "Display Name" --description "Description"
asc subscriptions versions localizations list --version-id "VERSION_ID" --paginate --output table

更新时需明确区分省略值、非空字符串以及 JSON null：

asc subscriptions versions localizations update --id "LOC_ID" --name "New Name" --description "Updated description"

不要将设值参数与对应的 --clear-name 或 --clear-description 清除标志同时使用。虽然 4.4.1 Schema 允许 JSON null，但 Apple 线上服务目前会拒绝订阅版本本地化中的空 --description 和 --clear-description，因为描述内容必须至少包含一个字符。

因此，创建缺少的订阅版本本地化项时必须提供非空描述。如果执行任务时仅提供了显示名称，可以更新已有本地化项的名称，但在用户提供非空语言区专属描述或通用后备描述之前，绝不能创建新的语言区本地化项。

工作流：批量本地化订阅组版本（v2）

asc subscriptions groups versions localizations list --version-id "VERSION_ID" --paginate --output table
asc subscriptions groups versions localizations create --version-id "VERSION_ID" --locale "LOCALE" --name "Group Display Name" --custom-app-name "My App"
asc subscriptions groups versions localizations update --id "LOC_ID" --name "Updated Group Display Name" --custom-app-name "My App"
asc subscriptions groups versions localizations list --version-id "VERSION_ID" --paginate --output table

清除元数据是一项显式的独立操作。确认用户确实想要移除已有的自定义应用名称后，再执行：

asc subscriptions groups versions localizations update --id "LOC_ID" --clear-custom-app-name

在标准的批量本地化工作流中，切勿包含 --clear-name 或 --clear-custom-app-name。只有当明确意图置为 JSON null 时才使用这两个标志；省略标志则保持该属性原样不变。

工作流：批量本地化 IAP 版本（v2）

asc iap versions localizations list --version-id "VERSION_ID" --paginate --output table
asc iap versions localizations create --version-id "VERSION_ID" --locale "LOCALE" --name "Display Name" --description "Description"
asc iap versions localizations update --localization-id "LOC_ID" --description "Updated description"
asc iap versions localizations list --version-id "VERSION_ID" --paginate --output table

即便 4.4.1 Schema 允许 JSON null，Apple 线上服务同样拒绝 IAP 版本本地化中的空描述与 --clear-description。与订阅逻辑一致，仅提供显示名称的操作可以更新现有的 IAP 本地化项，但在拿到非空描述前，不得创建缺少的语言区。

批量本地化 App 内的所有订阅版本

对于包含多个订阅组和订阅项目的完整应用：

# 1. 查询订阅组列表，并获取每个组唯一的未提交/可编辑版本（mutable version）。
asc subscriptions groups list --app "APP_ID" --paginate --output json
asc subscriptions groups versions list --group-id "GROUP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output json

# 2. 本地化各个订阅组版本。
asc subscriptions groups versions localizations list --version-id "GROUP_VERSION_ID" --paginate --output json
asc subscriptions groups versions localizations create --version-id "GROUP_VERSION_ID" --locale "LOCALE" --name "Group Display Name"

# 3. 查询订阅项目列表，并获取每个订阅项目唯一的未提交/可编辑版本。
asc subscriptions list --group-id "GROUP_ID" --paginate --output json
asc subscriptions versions list --subscription-id "SUB_ID" --state PREPARE_FOR_SUBMISSION --paginate --output json

# 4. 本地化各个订阅版本。
asc subscriptions versions localizations list --version-id "SUBSCRIPTION_VERSION_ID" --paginate --output json
asc subscriptions versions localizations create --version-id "SUBSCRIPTION_VERSION_ID" --locale "LOCALE" --name "Display Name" --description "Description"

对各个版本查询列表同样适用 0/1/多 判定规则：匹配数为 0 时创建版本，匹配数为 1 时直接复用，若返回多个匹配项则暂停并要求明确指定 ID。

Agent 行为规范

• 开展新本地化工作时，必须仅使用版本作用域（version-scoped）的 v2 资源。
• 严禁混淆版本 ID 与产品 ID、订阅 ID 及订阅组 ID。
• 务必先列出已有本地化项，避免重复创建引发错误。
• 遇缺失语言区则创建，已存在但字段值不一致时更新解析出的本地化 ID，字段值完全一致时不做任何操作。
• 若用户仅提供单个显示名称，则在所有语言区统一使用该名称。
• 若用户按语言区提供了翻译名称，则各语言区使用对应的本地化名称。
• 对于订阅和 IAP 版本的本地化，每次创建时均要求提供非空的 --description。如果用户只提供了显示名称，应按解析出的 ID 更新已有本地化项，跳过缺失语言区的创建，并提示用户提供语言区专属描述或一个非空后备描述后再执行创建。
• 更新已有订阅或 IAP 版本本地化项时，除非用户显式提供了新的非空值，否则应省略 --description 参数；绝不可自行推断为空值或执行清除。
• 订阅组版本的本地化项没有描述字段。按正常逻辑创建或更新其名称即可，仅在用户显式提供该值时才附带 --custom-app-name。
• 在验证步骤中使用 --output table，方便用户直观确认。
• 在自动化中间步骤显式使用 --output json；默认输出会根据是否为 TTY 环境自动调整。
• 批量写入完成后，务必再次运行 list 命令检查完整性。
• 对于包含大量订阅的应用，按订阅组顺序逐个处理，确保输出内容清晰易读。
• 若某个语言区的创建或更新调用失败，记录该语言区与错误日志，随后继续处理其余语言区。待整批任务完成后，汇总报告所有失败项，方便用户统一处理。

注意事项

• 订阅显示名称即用户在订阅管理弹框及购买确认界面看到的文本。
• 为已存在的语言区重复创建本地化项会导致失败；如需修改，请先查询列表并更新对应解析出的 ID。
• 不存在批量接口，每个语言区均需发起单独的创建请求。
• 在查询命令中使用 --paginate 参数，确保获取全部已有的本地化项。
• 如果只有应用名称而没有 ID，可调用 asc-id-resolver Skill 进行解析。