asc-subscription-localization

asc 订阅本地化

使用此技能，可在所有 App Store Connect 语言环境中批量创建或更新订阅、订阅群组和 App 内购买项目的显示名称，以及受支持的描述。这样就不必在 App Store Connect 中逐个点击每种语言来设置相同的显示名称。

前提条件

• 已配置身份验证（asc auth login 或 ASC_* 环境变量）。
• 知道你的 App ID（ASC_APP_ID 或 --app）。
• 订阅群组和订阅已存在。

先选择 API 范围

API 4.4.1 为 App 内购买项目、订阅和订阅群组新增了独立版本。版本 ID 与其产品、订阅或群组 ID 不同。

• 所有新的本地化工作都使用 asc ... versions localizations ...。
• 不要使用产品或群组范围的 v1 本地化命令。API 4.4.1 弃用了这些资源，CLI 现在会针对其兼容性命令发出迁移警告。
• 绝不要将产品、订阅或群组 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

分别根据每个列表结果进行处理：没有匹配项时创建；有一个匹配项时复用该版本 ID；有多个匹配项时停止并要求提供明确的版本 ID。仅在对应结果为零匹配时运行以下命令：

# If and only if the IAP version list returned zero matches:
asc iap versions create --iap-id "IAP_ID" --output json
# If and only if the subscription version list returned zero matches:
asc subscriptions versions create --subscription-id "SUB_ID" --output json
# If and only if the group version list returned zero matches:
asc subscriptions groups versions create --group-id "GROUP_ID" --output json

这三类版本都没有删除命令。列出并复用唯一的 PREPARE_FOR_SUBMISSION 版本；只有零匹配时才创建，存在多个匹配项时则停止并要求提供明确的 ID。删除线上父级对象不会级联删除 App 内购买项目或订阅版本，因此不要以为删除父级对象就会清理测试时创建的版本。

支持的 App Store 语言环境

以下是 App Store Connect 支持的订阅和 App 内购买项目本地化语言环境：

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。导入会创建缺失的语言环境，只更新有差异的字段，不会清空或删除任何内容，并会报告各语言环境的失败情况。

asc subscriptions versions localizations import --version-id "VERSION_ID" --file "./localizations.json" --dry-run
asc subscriptions versions localizations import --version-id "VERSION_ID" --file "./localizations.json" --confirm

asc iap versions localizations import 使用相同的 name 和 description 字段。asc subscriptions groups versions localizations import 使用 name 和 customAppName。为每种新建的订阅或 App 内购买项目语言环境提供非空的 description；请参阅下方的创建规则。

工作流：批量本地化订阅版本（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 架构允许 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

清除元数据是单独的明确选择操作。在确认用户希望移除现有的自定义 App 名称后，运行：

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

Apple 的线上服务也会拒绝 IAP 版本本地化中的空描述和 --clear-description，尽管 4.4.1 架构允许 JSON null。与订阅一样，仅提供显示名称的运行可以更新现有 IAP 本地化，但在有非空描述之前，不得创建缺失的语言地区。

批量本地化应用中的所有订阅版本

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

# 1. List groups and resolve each group's unique 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. Localize each group version.
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. List subscriptions and resolve each subscription's unique mutable version.
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. Localize each subscription version.
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"

对每个版本列表应用相同的零个／一个／多个匹配项规则：零个匹配项时创建版本，一个匹配项时复用该版本，多个匹配项时停止并要求提供明确的 ID。

Agent 行为

• 新的本地化工作只能使用版本范围内的 v2 资源。
• 将版本 ID 与产品、订阅和组 ID 分开处理。
• 始终先列出现有本地化内容，以避免重复创建错误。
• 创建缺失的语言地区；如果现有值不同，则更新已解析的本地化 ID；如果现有值已匹配，则不执行任何操作。
• 用户只提供一个显示名称时，将其用于所有语言地区（每个地区使用相同名称）。
• 用户按语言地区提供翻译后的名称时，每个地区使用对应的名称。
• 对于订阅和 IAP 版本本地化，每次创建都必须提供非空的 --description。如果用户只提供显示名称，则通过已解析的 ID 更新现有本地化，跳过缺失语言地区的创建，并在创建前要求用户提供各语言地区的描述，或提供一个非空的备用描述。
• 更新现有订阅或 IAP 版本本地化时，除非用户提供了新的非空值，否则省略 --description；绝不推断空值或清除描述。
• 订阅组版本本地化没有描述字段。正常创建或更新名称；仅当用户提供了该值时才使用 --custom-app-name。
• 验证步骤使用 --output table，方便用户直观确认。
• 中间自动化步骤明确使用 --output json；输出默认值会根据 TTY 自动调整。
• 批量写入后，始终运行 list 命令验证是否完整。
• 对于订阅数量较多的应用，按组顺序处理，以保持输出易于阅读。
• 如果某个语言地区的创建或更新调用失败，记录该地区和错误，然后继续处理其余语言地区。批次完成后，将所有失败汇总报告，以便用户处理。

备注

• 订阅显示名称是用户在订阅管理页和购买对话框中看到的名称。
• 为已存在的语言地区创建本地化内容会失败；先列出内容，并在需要更改时更新已解析的 ID。
• Apple 没有批量本地化端点；... localizations import 会验证整个文件，然后逐个语言地区写入。
• 在 list 命令中使用 --paginate，确保返回所有现有本地化内容。
• 如果只有应用名称而没有 ID，请使用 asc-id-resolver 技能。