Asc Localize Metadata

1---2name: asc-localize-metadata3description: Automatically translate and sync App Store metadata (description, keywords, what's new, subtitle) to multiple languages using LLM translation and asc CLI. Use when asked to localize an app's App Store listing, translate app descriptions, or add new languages to App Store Connect.4---5 6# asc localize metadata7 8Use this skill to pull English (or any source locale) App Store metadata, translate it with LLM, and push translations back to App Store Connect — all automated.9 10## Command discovery and output conventions11 12- Always confirm flags with `--help` for the exact `asc` version:13  - `asc localizations --help`14  - `asc localizations download --help`15  - `asc localizations upload --help`16  - `asc apps info edit --help`17- Prefer explicit long flags (`--app`, `--version`, `--version-id`, `--type`, `--app-info`).18- Default output is JSON; use `--output table` only for human verification steps.19- Prefer deterministic ID-based operations. Do not "pick the first row" via `head -1` unless the user explicitly agrees.20 21## Preconditions22- Auth configured (`asc auth login` or `ASC_*` env vars)23- Know your app ID (`asc apps list` to find it)24- At least one locale (typically en-US) already has metadata in App Store Connect25 26## Supported Locales27 28App Store Connect locales for version and app-info localizations:29```30ar-SA, ca, cs, da, de-DE, el, en-AU, en-CA, en-GB, en-US,31es-ES, es-MX, fi, fr-CA, fr-FR, he, hi, hr, hu, id, it,32ja, ko, ms, nl-NL, no, pl, pt-BR, pt-PT, ro, ru, sk,33sv, th, tr, uk, vi, zh-Hans, zh-Hant34```35 36## Two Types of Metadata37 38### Version Localizations (per-release)39Fields: `description`, `keywords`, `whatsNew`, `supportUrl`, `marketingUrl`, `promotionalText`40 41### App Info Localizations (app-level, persistent)42Fields: `name`, `subtitle`, `privacyPolicyUrl`, `privacyChoicesUrl`, `privacyPolicyText`43 44## Workflow45 46### Step 1: Resolve IDs47 48```bash49# Find app ID50asc apps list --output table51 52# Find latest version ID53asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table54# or for editable version:55asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table56 57# Find app info ID (for app-level fields like name/subtitle)58asc apps info list --app "APP_ID" --output table59```60 61Notes:62- Version-localization fields (description, keywords, whatsNew, etc.) are per-version.63- App-info fields (name, subtitle, privacy URLs/text) are app-level and use `--type app-info`.64- If you only have names (app name, version string) and need IDs deterministically, use `asc-id-resolver`.65 66### Step 2: Download source locale67 68```bash69# Download version localizations to local .strings files70# (description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl, ...)71asc localizations download --version "VERSION_ID" --path "./localizations"72 73# Download app-info localizations to local .strings files74# (name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText, ...)75asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"76```77 78This creates files like `./localizations/en-US.strings` and `./app-info-localizations/en-US.strings`. If download is unavailable, read fields individually:79 80```bash81# List version localizations to see existing locales and their content82asc localizations list --version "VERSION_ID" --output table83```84 85### Step 3: Translate with LLM86 87For each target locale, translate the source text. Follow these rules:88 89#### Translation Guidelines90- **Tone & Register**: Always use formal, polite language. Use formal "you" forms where the language distinguishes them (Russian: «вы», German: «Sie», French: «vous», Spanish: «usted», Dutch: «u», Italian: «Lei», Portuguese: «você» formal, etc.). App Store descriptions are professional marketing copy — never use casual or informal register.91- **description**: Translate naturally, adapt tone to local market. Keep formatting (line breaks, bullet points, emoji). Stay within 4000 chars.92- **keywords**: Do NOT literally translate. Research what users in that locale would search for. Comma-separated, max 100 chars total. No duplicates, no app name (Apple adds it automatically).93- **whatsNew**: Translate release notes. Keep it concise. Max 4000 chars.94- **promotionalText**: Translate marketing hook. Max 170 chars. This can be updated without a new version.95- **subtitle**: Translate or adapt tagline. Max 30 chars — this is very tight, may need creative adaptation.96- **name**: Usually keep the original app name. Only translate if the user explicitly asks. Max 30 chars.97 98#### LLM Translation Prompt Template99 100For each target locale, use this approach:101 102```103Translate the following App Store metadata from {source_locale} to {target_locale}.104 105Rules:106- description: Natural, fluent translation. Preserve formatting (line breaks, bullets, emoji). Max 4000 chars.107- keywords: Do NOT literally translate. Choose keywords native speakers would search for in the App Store. Comma-separated, max 100 chars total. Do not include the app name.108- whatsNew: Translate release notes naturally. Max 4000 chars.109- promotionalText: Translate marketing tagline. Max 170 chars.110- subtitle: Adapt tagline creatively to fit 30 chars max.111- name: Keep the original app name unless explicitly requested to translate it. Max 30 chars.112- Use formal, polite language and formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted, Dutch: u, etc.). App Store copy is professional marketing — never use informal register.113- Respect cultural context. A playful tone in English may need adjustment for formal markets (e.g., ja, de-DE).114 115Source ({source_locale}):116description: """117{description}118"""119 120keywords: {keywords}121 122whatsNew: """123{whatsNew}124"""125 126promotionalText: {promotionalText}127 128name: {name}129 130subtitle: {subtitle}131```132 133### Step 4: Upload translations134 135#### Option A: Via .strings files (bulk)136 137Create a `.strings` file per locale in the appropriate directory.138 139Version localization example:140 141```142// nl-NL.strings143"description" = "Je app-beschrijving hier";144"keywords" = "wiskunde,kinderen,tafels,leren";145"whatsNew" = "Bugfixes en verbeteringen";146"promotionalText" = "Leer de tafels van vermenigvuldiging!";147```148 149Then upload version localizations:150```bash151asc localizations upload --version "VERSION_ID" --path "./localizations"152```153 154App-info localization example:155 156```157// nl-NL.strings158"subtitle" = "Leer tafels spelenderwijs";159```160 161Then upload app-info localizations:162```bash163asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"164```165 166#### Option B: Via individual commands (fine control)167 168```bash169# Version localization fields (fine control).170# Prefer passing the explicit version ID for determinism.171asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "nl-NL" \172  --description "Je beschrijving..." \173  --keywords "wiskunde,kinderen,tafels" \174  --whats-new "Bugfixes en verbeteringen"175```176 177For app-level fields:178```bash179# Subtitle/name (app-info localization) is managed via app-info localizations.180# Use the app-info localization .strings + upload flow (there is no `asc app-infos localizations ...` command).181#182# 1) Edit: ./app-info-localizations/nl-NL.strings183# "subtitle" = "Leer tafels spelenderwijs";184#185# 2) Upload:186asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"187```188 189### Step 5: Verify190 191```bash192# Check all locales are present193asc localizations list --version "VERSION_ID" --output table194 195# Check app info localizations196asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table197```198 199## Character Limits (enforce before upload!)200 201| Field | Limit |202|-------|-------|203| Name | 30 |204| Subtitle | 30 |205| Keywords | 100 (comma-separated) |206| Description | 4000 |207| What's New | 4000 |208| Promotional Text | 170 |209 210**Always validate** translated text fits within limits before uploading. Truncated text looks unprofessional. If translation exceeds the limit, shorten it — do not truncate mid-sentence.211 212## Full Example: Add nl-NL and ru to Roxy Math213 214```bash215# 1) Resolve IDs deterministically (do not auto-pick the "first" row)216# If you only have names, use asc-id-resolver skill.217asc apps list --output table218APP_ID="APP_ID_HERE"219 220asc versions list --app "$APP_ID" --state PREPARE_FOR_SUBMISSION --output table221VERSION_ID="VERSION_ID_HERE"222 223asc apps info list --app "$APP_ID" --output table224APP_INFO_ID="APP_INFO_ID_HERE"225 226# 2) Download English source (or your chosen source locale)227asc localizations download --version "$VERSION_ID" --path "./localizations"228asc localizations download --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"229 230# 3) Read en-US.strings, translate to nl-NL and ru (LLM step)231 232# 4) Write nl-NL.strings and ru.strings to:233#    - ./localizations/ (version localization fields)234#    - ./app-info-localizations/ (subtitle/name/privacy fields)235 236# 5) Upload all237asc localizations upload --version "$VERSION_ID" --path "./localizations"238asc localizations upload --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"239 240# 6) Verify241asc localizations list --version "$VERSION_ID" --output table242asc localizations list --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --output table243```244 245## Agent Behavior246 2471. **Always start by reading the source locale** — never translate from memory or assumptions.2482. **Check existing localizations first** — don't overwrite existing translations unless the user asks to update them.2493. **Version vs app-info is different** — version fields live under `--version "VERSION_ID"`; subtitle/name/privacy live under `--app ... --type app-info`.2504. **Prefer deterministic IDs** — do not select IDs via `head -1` unless explicitly requested; use `--output table` for selection or `asc-id-resolver`.2515. **Validate character limits** before uploading. Count characters for each field. If over limit, re-translate shorter.2526. **Keywords are special** — do not literally translate. Research locale-appropriate search terms. Think like a user searching the App Store in that language.2537. **Show the user translations before uploading** — present a summary table of all fields × locales for approval. Do not push without confirmation.2548. **Process one locale at a time** if translating many languages — easier to review and catch errors.2559. **If upload fails** for a locale, log the error, continue with other locales, report all failures at the end.25610. **For updates to existing localizations** — download current, show diff of what will change, get approval, then upload.257 258## Notes259- Version localizations are tied to a specific version. Create the version first if it doesn't exist.260- `promotionalText` can be updated anytime without a new version submission.261- `whatsNew` is only relevant for updates, not the first version.262- Use `asc-id-resolver` skill if you only have app/version names instead of IDs.263- Use `asc-metadata-sync` skill for non-translation metadata operations.264- For subscription/IAP display name localization, use `asc-subscription-localization` skill instead.