version: "1.0.0" name: aso-localization description: Use to pick new App Store markets, research keywords natively per country, or exploit cross-locale keyword indexing with the aso CLI, the single most under-used ASO lever for most apps. Trigger on "localize my app", "target new markets", "international ASO", "which locales should I fill", "translate my keywords", or "how does cross-locale indexing work". Uses aso storefronts and the per-country -c flag for native market research plus aso lint --fastlane to validate every locale at once, and warns against ever just translating one locale's keywords into another instead of researching them fresh.

ASO Localization

Fill more of a storefront's indexing capacity than the primary locale alone gives you: the single most under-used ASO lever for most apps.

Preflight: see the aso router skill.

Iron law

Research each locale natively: never translate. A translated keyword is a guess about what a market searches; a keyword pulled from aso suggest/aso keywords with -c <that country> is measured. "Überwachungskamera" outperforms a literal translation of "security camera" in DE because it's what Germans actually type, not what English maps to.

Step 1: Pick markets

aso storefronts

Lists supported country codes. Country codes to -c must be uppercase.

Beyond the obvious "which countries do I want revenue from," also fill secondary locales your current storefront already indexes: no new market entry required, just more of the same storefront's keyword space. A US-facing app, for example, gets credit not only for en-US but for the other locales the US store indexes alongside it (regional English variants, and non-English locales with meaningful US-resident search volume, e.g. es-MX, pt-BR, zh-Hans/Hant, ja). Exactly which locales a given storefront indexes can shift over time; confirm current App Store Connect locale options for the target storefront rather than assuming a fixed list.

Step 2: Research per country, not per translation

For every locale you're filling, run the same research flow as aso-keyword-research but with -c set to that country:

aso suggest "<seed>" --limit 50 -c DE
aso keywords "<candidate1>" "<candidate2>" ... --app <appId> -c DE
aso search "<candidate>" --limit 20 -c DE

Seeds for non-English locales should themselves come from native speakers, translation as a starting point only, or aso suggest's own autocomplete-derived ideas for that storefront: always confirm with real popularity/difficulty numbers from that country before trusting a term.

For English secondary locales indexed alongside your primary (e.g. en-GB, en-AU, en-CA under a US storefront), don't just re-run your en-US shortlist: look for regional spelling/vocabulary differences ("colour"/"color", "torch"/"flashlight") and overflow keywords that didn't fit your primary locale's 100-char budget. These count as genuinely different tokens even though the language is the same.

Step 3: Dedup across locales in the same storefront

Within one storefront, the same word repeated across two of its indexed locales earns nothing extra: Apple already has it indexed once. Build a quick coverage table before finalizing:

| Term         | en-US | en-GB | es-MX | Locales |
|--------------|-------|-------|-------|---------|
| camera       | Yes   | -     | -     | 1       |
| cctv         | -     | Yes   | -     | 1       |
| cámara       | -     | -     | Yes   | 1       |

Across different storefronts (US vs GB as separate stores), duplication is fine: they don't share an index.

Step 4: Assemble and validate every locale at once

Draft title/subtitle/keywords per locale following aso-metadata's per-field rules (natural title, benefit subtitle, packed keywords field, no cross-field repeats). CJK and Arabic locales fit fewer keyword-field tokens than en-US for the same 100-byte limit (see aso for why); check aso lint's byte count for that locale rather than counting characters. Then validate the whole fastlane metadata tree in one pass:

aso lint --fastlane <metadata dir>

This runs the same checks as single-locale aso lint (lengths, duplicate words, spacing, stop words, plurals, wasted characters, competitor-brand risk) across every locale folder (name.txt, subtitle.txt, keywords.txt) at once. Fix every flagged locale before presenting the set.

Step 5: Apply and log

aso doesn't upload. Ship via fastlane deliver from the metadata/<locale>/ tree, or manual paste per locale in App Store Connect: with the user's explicit approval of every locale's final text. Log each locale's change:

aso log add --app <appId> --locale es-MX --field keywords --old "<old>" --new "<new>" --note "initial es-MX fill"

Repeat per changed field per locale so aso-tracking can later attribute rank movement to the right locale and field.

Seasonal keyword calendar

Seasonal pushes (holiday, back-to-school, a sale) need lead time and a plan to revert, they're not a permanent rewrite:

• Creative (screenshots, icon variants, preview video): plan 4-6 weeks lead time to design and get through App Review.
• Localization QA on any seasonal text change: 2-3 weeks lead time to check translations read naturally and lint clean across every locale.
• Promotional text is the safest seasonal lever: not indexed, editable anytime with no new build, so put the timely message there first (see aso-metadata).
• Keywords field seasonal swaps: touch only 2-4 of the weakest evergreen terms, not a wholesale rewrite. Log the swap (aso log add), then revert after the peak unless the swapped terms are measurably outperforming what they replaced.

Output

Coverage table (which locales are filled, bytes used, unique-vs-primary term count), the per-locale draft metadata, the aso lint --fastlane result, and next steps (which unfilled locales are highest priority, based on their storefront's likely reach).

Red flags

• Copy-pasting one locale's keywords into another within the same storefront.
• Trusting a machine translation without checking its popularity via aso keywords -c <country>.
• Filling title/subtitle for a locale but leaving its keywords field empty (or vice versa).
• Assuming a fixed locale-to-storefront index list without checking current App Store Connect options for that storefront.