Asc Subscription Localization

asc subscription localization

Use this skill to bulk-create or bulk-update display names and, where supported, descriptions for subscriptions, subscription groups, and in-app purchases across all App Store Connect locales. This eliminates the tedious manual process of clicking through each language in App Store Connect to set the same display name.

Preconditions

• Auth configured (asc auth login or ASC_* env vars).
• Know your app ID (ASC_APP_ID or --app).
• Subscription groups and subscriptions already exist.

Choose the API scope first

API 4.4.1 adds discrete versions for IAPs, subscriptions, and subscription groups. A version ID is different from its product, subscription, or group ID.

• Use asc ... versions localizations ... for all new localization work.
• Do not use the product- or group-scoped v1 localization commands. API 4.4.1 deprecates those resources, and the CLI now emits migration warnings for their compatibility commands.
• Never pass a product, subscription, or group ID to a version-scoped command.

Resolve or create versions before localizing them:

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

Branch independently on each list result: zero matches means create, one means reuse that version ID, and more than one means stop and require an explicit version ID. Run each command below only for its zero-match branch:

# 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

None of the three version families has a version delete command. List and reuse the single PREPARE_FOR_SUBMISSION version; create only for zero matches, and stop for an explicit ID when multiple matches exist. Live parent deletion did not cascade IAP or subscription versions, so do not assume parent deletion cleans up versions created for testing.

Supported App Store Locales

These are the locales supported by App Store Connect for subscription and IAP localizations:

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

Import many locales from one file

For bulk writes, map each locale to its fields in one JSON file and import it into the resolved version ID. Import creates missing locales, updates only differing fields, never clears or deletes, and reports per-locale failures.

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 takes the same name and description fields. asc subscriptions groups versions localizations import takes name and customAppName. Give every new subscription or IAP locale a non-empty description; see the create rules below.

Workflow: Bulk-localize a subscription version (v2)

List existing localizations, create only missing locales, then verify:

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

Updates distinguish omitted values, non-empty strings, and JSON null:

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

Do not combine a value flag with its matching --clear-name or --clear-description flag. The 4.4.1 schema permits JSON null, but Apple's live service currently rejects both an empty --description and --clear-description for subscription-version localizations because the description must contain at least one character.

Creating a missing subscription-version localization therefore requires a non-empty description. A display-name-only run may update the name of an existing localization, but must not create a missing locale until the user provides a non-empty locale-specific or shared fallback description.

Workflow: Bulk-localize a subscription group version (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

Clearing metadata is a separate, explicit opt-in operation. After confirming that the user wants to remove an existing custom app name, run:

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

Do not include --clear-name or --clear-custom-app-name in the standard bulk localization workflow. Use either flag only when JSON null is deliberately intended; omitting the flag leaves that attribute unchanged.

Workflow: Bulk-localize an IAP version (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's live service also rejects empty descriptions and --clear-description for IAP-version localizations even though the 4.4.1 schema permits JSON null. As with subscriptions, a display-name-only run may update existing IAP localizations but must not create missing locales until a non-empty description is available.