asc-subscription-localization

asc 订阅本地化 (asc subscription localization)

使用此 Skill 可以跨 App Store Connect 支持的所有语言区域，批量创建或更新订阅、订阅组以及应用内购买项目（IAP）的显示名称与描述（在支持的情况下）。这能让你摆脱在 App Store Connect 后台中逐个语言点击配置相同显示名称的繁琐手动流程。

前置条件

• 已配置身份认证（运行 asc auth login 或设置 ASC_* 环境变量）。
• 明确你的 App ID（设置 ASC_APP_ID 环境变量或传入 --app 参数）。
• 对应的订阅组和订阅项目已在后台创建完成。

优先选择正确的 API 作用域

API 4.4.1 为 IAP、订阅和订阅组引入了独立的版本（Version）资源。版本 ID（Version ID）与产品 ID、订阅 ID 或订阅组 ID 是不同的。

• 所有新的本地化工作均须使用 asc ... versions localizations ... 命令。
• 切勿使用基于产品或订阅组作用域的 v1 本地化命令。API 4.4.1 已废弃这些资源，CLI 也会针对这些兼容命令发出迁移警告。
• 绝不能将产品 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；匹配到多条记录时则停止操作，要求用户显式指定版本 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 状态的单个版本即可；仅在无匹配时创建新版本，多匹配时暂停并索要明确 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 行为规范

• 开展新的本地化工作时，仅使用基于版本作用域的 v2 资源。
• 严禁混淆版本 ID（Version ID）与产品 ID、订阅 ID 及订阅组 ID。
• 必须先列出已有的本地化项，避免因重复创建而报错。
• 对缺失的语言区域执行创建，对已存在但内容不一致的本地化 ID 执行更新，内容一致时则跳过。
• 用户仅提供单个显示名称时，在所有语言区域使用统一名称。
• 用户按语言区域提供多语言译名时，分别设置对应的语言名称。
• 对于订阅和 IAP 版本的本地化创建，要求每次必须提供非空的 --description。若用户只提供了显示名称，应根据解析出的 ID 更新已有本地化，跳过缺失区域的创建，并向用户索取对应语言的描述或统一的非空兜底描述。
• 更新已有的订阅或 IAP 版本本地化时，除非用户提供了全新的非空值，否则省略 --description 参数；绝不能自行推断空值或进行清除。
• 订阅组版本本地化没有描述（description）字段。正常创建或更新其名称即可，仅在用户显式提供时才传入 --custom-app-name。
• 在校验步骤中使用 --output table 格式，以便用户能够直观核验。
• 自动化中间步骤显式使用 --output json；默认输出会根据 TTY 动态适应。
• 批量写入完成后，务必重新运行 list 命令确认数据完整性。
• 对于包含较多订阅的应用，按订阅组依次顺序处理，保持输出清晰易读。
• 若某个语言区域的创建或更新失败，先记录该语言区域及错误信息，然后继续处理剩余语言。待整批任务完成后，汇总报告所有失败项，以便用户统一处理。

注意事项

• 订阅显示名称即用户在订阅管理弹窗和购买确认界面中看到的文本。
• 为已存在的语言区域重复创建本地化会导致失败；请先列表查询，需要修改时更新对应的 ID。
• Apple 未提供批量接口，每个语言区域都需要单独调用一次创建命令。
• 在查询列表中使用 --paginate 参数，确保获取全部已有的本地化数据。
• 如果手中只有 App 名称而没有 ID，可调用 asc-id-resolver Skill 进行解析。