onatcipli/app-store-aso-localization

App Store ASO & Localization

Optimize your App Store metadata and localize across 38 languages using ASO best practices and the App Store Connect API.

Metadata Field Reference

| Field | Limit | Indexed | Level | Notes | |-------|-------|---------|-------|-------| | App Name | 30 chars | Yes (highest) | App | Brand + primary keyword | | Subtitle | 30 chars | Yes (medium) | App | USP + secondary keywords | | Keywords | 100 chars | Yes (iOS only) | Version | Comma-separated, no spaces | | Promotional Text | 170 chars | No | Version | Can update without review | | Description | 4,000 chars | No (iOS) | Version | Conversion-focused | | What's New | 4,000 chars | No | Version | Release notes |

Important: iOS App Store does NOT index the description for search. Focus keywords in Title → Subtitle → Keywords field only.

API Access

| Tier | Auth | Endpoints | Use Case | |------|------|-----------|----------| | Public | None | iTunes Search/Lookup | Competitor research | | Private | JWT | App Store Connect API | Manage your metadata |

For authentication setup, see api-endpoints.md.

---

Workflow 1 — Analyze Current Metadata

Audit your app's metadata for optimization opportunities.

Step 1: Fetch Current Localizations

GET /v1/apps/{appId}/appInfos
GET /v1/appInfos/{appInfoId}/appInfoLocalizations
GET /v1/appStoreVersions/{versionId}/appStoreVersionLocalizations

Step 2: Check Character Usage

For each locale, calculate usage percentage:

fields = {
    "name": {"limit": 30, "value": localization.name},
    "subtitle": {"limit": 30, "value": localization.subtitle},
    "keywords": {"limit": 100, "value": localization.keywords},
    "promotionalText": {"limit": 170, "value": localization.promotionalText},
    "description": {"limit": 4000, "value": localization.description}
}

for field, data in fields.items():
    usage = len(data["value"]) / data["limit"] * 100
    if usage < 90:
        flag_underutilized(field, usage)

Step 3: Identify Missing Localizations

Compare active localizations against recommended markets:

Priority markets: en-US, en-GB, de-DE, fr-FR, ja, zh-Hans, zh-Hant,
                  ko, es-ES, es-MX, pt-BR, it, nl, ru, tr, ar

Step 4: Check for ASO Violations

• Duplicate keywords across Title/Subtitle/Keywords
• Stop words in keywords field ("the", "and", "app", "a", "an")
• Spaces after commas in keywords
• Keywords repeated across locales (wasteful)

Step 5: Generate Health Report

## Metadata Health Report — {App Name}

### Overview
- Active localizations: 12/38
- Character utilization: 78% average
- ASO violations: 3 found

### Character Usage by Locale

| Locale | Name | Subtitle | Keywords | Status |
|--------|------|----------|----------|--------|
| en-US  | 28/30 (93%) | 25/30 (83%) | 98/100 (98%) | Good |
| de-DE  | 22/30 (73%) | 18/30 (60%) | 72/100 (72%) | Underutilized |
| ja     | 15/30 (50%) | 12/30 (40%) | 45/100 (45%) | Poor |

### Missing High-Value Localizations
- zh-Hans (China) — 2nd largest App Store
- ko (Korea) — High spending market
- pt-BR (Brazil) — Growing market

### ASO Violations Found
1. ❌ Keyword "photo" appears in both Title and Keywords (en-US)
2. ❌ Stop word "app" in keywords field (en-GB)
3. ❌ Space after comma in keywords (de-DE)

### Recommendations
1. Add Chinese (Simplified) localization — potential +15% downloads
2. Expand German keywords to use full 100 characters
3. Remove duplicate keywords to add more unique terms

---

Workflow 2 — Keyword Research & Optimization

Research and optimize keywords for maximum discoverability.

Step 1: Seed Keyword Collection

Gather initial keywords from:

1. Your metadata — Current title, subtitle, keywords
2. Competitor metadata — Via iTunes Lookup API
3. Review mining — Common words in user reviews
4. Category analysis — Top apps in your category

GET https://itunes.apple.com/lookup?id={competitor_id}&country={cc}

Step 2: Keyword Analysis

For each keyword, evaluate:

| Metric | Description | Source | |--------|-------------|--------| | Search Volume | How often users search this term | ASO tools / estimation | | Difficulty | Competition level (0-100) | Top 10 app ratings | | Relevance | How well it describes your app | Manual assessment | | Current Rank | Your position for this keyword | Track over time |

Step 3: Keyword Scoring

def score_keyword(volume, difficulty, relevance):
    """
    Higher score = better keyword opportunity
    Volume: 1-100, Difficulty: 1-100, Relevance: 1-10
    """
    opportunity = volume * (1 - difficulty/100)
    score = opportunity * relevance
    return score

Step 4: Generate Optimized Keyword Set

Rules for the 100-character keywords field:

1. No duplicates — Words in Title/Subtitle are already indexed
2. No spaces — Use commas only: keyword1,keyword2,keyword3
3. No stop words — Remove "the", "and", "a", "an", "app"
4. Single words — Break phrases into individual tokens
5. Prioritize — Highest-scoring keywords first

## Optimized Keywords — {App Name} (en-US)

### Title (30 chars)
"PhotoEdit Pro - Picture Editor"
Keywords captured: photoedit, pro, picture, editor

### Subtitle (30 chars)
"Filters, Collage & Retouch"
Keywords captured: filters, collage, retouch

### Keywords Field (100 chars)
"camera,enhance,crop,adjust,brightness,contrast,saturation,blur,sharpen,resize,rotate,frame,effects"
Characters used: 97/100

### Total Unique Keywords: 17

See keyword-strategies.md for advanced techniques.

---

Workflow 3 — Localize Metadata

Translate and adapt metadata for international markets.

Step 1: Select Target Locales

Prioritize by market opportunity:

| Tier | Locales | Rationale | |------|---------|-----------| | Tier 1 | en-US, en-GB, de-DE, ja, zh-Hans | Largest markets | | Tier 2 | fr-FR, ko, es-ES, pt-BR, it | High growth | | Tier 3 | nl, ru, tr, ar, zh-Hant, sv | Market expansion | | Tier 4 | All remaining | Full coverage |

Step 2: Translate Content

For each field, translate while respecting limits:

def translate_field(text, source_lang, target_lang, char_limit):
    """
    Translate text and ensure it fits within character limit.
    """
    translated = ai_translate(text, source_lang, target_lang)

    if len(translated) > char_limit:
        # Shorten while preserving meaning
        translated = ai_shorten(translated, char_limit)

    return translated

Step 3: Localize Keywords (Don't Just Translate!)

Keywords require localization, not just translation:

Example: "photo editor" app

❌ Wrong (direct translation):
- German: "fotobearbeitung" (literal translation)

✅ Right (localized):
- German: "bildbearbeitung,fotos,bilder,bearbeiten,filter"
  (terms Germans actually search for)

Research local search behavior:

1. Check competitor keywords in that locale
2. Use local App Store search suggestions
3. Consider local spelling variations

Step 4: Apply Translations

PATCH /v1/appInfoLocalizations/{localizationId}
{
  "data": {
    "type": "appInfoLocalizations",
    "id": "{localizationId}",
    "attributes": {
      "name": "Localized App Name",
      "subtitle": "Localized Subtitle"
    }
  }
}

PATCH /v1/appStoreVersionLocalizations/{localizationId}
{
  "data": {
    "type": "appStoreVersionLocalizations",
    "id": "{localizationId}",
    "attributes": {
      "keywords": "localized,keywords,here",
      "description": "Localized description...",
      "promotionalText": "Localized promo text"
    }
  }
}

Step 5: Verify Translations

After applying:

1. Check character counts are within limits
2. Verify no encoding issues
3. Confirm keywords don't duplicate title/subtitle
4. Review for cultural appropriateness

---

Workflow 4 — Cross-Localization Strategy

Apple indexes keywords from MULTIPLE locales per storefront. Use this to effectively double your keyword coverage.

Cross-Localization Map

| Storefront | Primary Locale | Secondary Locale(s) | |------------|---------------|---------------------| | USA | en-US | es-MX | | UK | en-GB | en-US | | Canada | en-CA | fr-CA, en-US | | Australia | en-AU | en-US | | Germany | de-DE | en-US | | France | fr-FR | en-US | | Japan | ja | en-US | | Brazil | pt-BR | en-US | | Mexico | es-MX | en-US | | Spain | es-ES | en-US | | China | zh-Hans | en-US | | Taiwan | zh-Hant | en-US |

Strategy Implementation

For the US App Store (indexes en-US + es-MX):

## US Market — Cross-Localization

### en-US Keywords (100 chars)
"photo,editor,camera,filter,retouch,enhance,crop,adjust,collage"

### es-MX Keywords (100 chars) — ALSO indexed in US!
"fotos,editar,imagen,efectos,marcos,belleza,retrato,selfie,blur"

### Result: 18 unique keywords indexed for US users
(vs 9 if only using en-US)

Rules for Cross-Localization

1. No overlap — Don't repeat keywords between paired locales
2. Relevance first — Both sets must be relevant to your app
3. Language appropriate — es-MX keywords work because US has Spanish speakers
4. Monitor performance — Track which locale's keywords perform better

Generate Cross-Localization Plan

## Cross-Localization Plan — {App Name}

### Target: US App Store
Primary: en-US | Secondary: es-MX

| en-US Keywords | es-MX Keywords |
|----------------|----------------|
| photo | fotos |
| editor | editar |
| camera | cámara |
| filter | filtros |
| enhance | mejorar |
| collage | collage ❌ (duplicate, remove) |
| retouch | retocar |
| beauty | belleza |
| portrait | retrato |

**Recommendation:** Replace "collage" in es-MX with unique term like "marcos"

See locale-reference.md for complete cross-indexing map.

---

Workflow 5 — Bulk Update via API

Apply metadata changes programmatically.

Prerequisites

• App Store Connect API key (Admin or App Manager role)
• JWT token generation
• App ID and version ID

Step 1: Get Current Version

GET /v1/apps/{appId}/appStoreVersions?filter[appStoreState]=READY_FOR_SALE,PREPARE_FOR_SUBMISSION

Step 2: List Existing Localizations

GET /v1/appStoreVersions/{versionId}/appStoreVersionLocalizations

Step 3: Create Missing Localizations

POST /v1/appStoreVersionLocalizations
{
  "data": {
    "type": "appStoreVersionLocalizations",
    "attributes": {
      "locale": "de-DE",
      "keywords": "keywords,here",
      "description": "German description...",
      "promotionalText": "German promo",
      "whatsNew": "What's new in German"
    },
    "relationships": {
      "appStoreVersion": {
        "data": {
          "type": "appStoreVersions",
          "id": "{versionId}"
        }
      }
    }
  }
}

Step 4: Update Existing Localizations

PATCH /v1/appStoreVersionLocalizations/{localizationId}
{
  "data": {
    "type": "appStoreVersionLocalizations",
    "id": "{localizationId}",
    "attributes": {
      "keywords": "updated,keywords",
      "description": "Updated description..."
    }
  }
}

Step 5: Update App Info Localizations (Name/Subtitle)

PATCH /v1/appInfoLocalizations/{localizationId}
{
  "data": {
    "type": "appInfoLocalizations",
    "id": "{localizationId}",
    "attributes": {
      "name": "New App Name",
      "subtitle": "New Subtitle"
    }
  }
}

Batch Update Script

async def bulk_update_localizations(app_id, updates):
    """
    updates = {
        "de-DE": {"keywords": "...", "description": "..."},
        "fr-FR": {"keywords": "...", "description": "..."},
    }
    """
    version_id = await get_current_version(app_id)
    localizations = await get_localizations(version_id)

    for locale, changes in updates.items():
        loc_id = find_localization_id(localizations, locale)

        if loc_id:
            await patch_localization(loc_id, changes)
        else:
            await create_localization(version_id, locale, changes)

        # Rate limiting
        await asyncio.sleep(0.5)

    return {"updated": len(updates)}

---

Workflow 6 — Competitor ASO Analysis

Analyze competitor metadata to identify opportunities.

Step 1: Identify Competitors

GET https://itunes.apple.com/search?term={category}&media=software&limit=25

Or specify competitor app IDs directly.

Step 2: Fetch Competitor Metadata

For each competitor, across key locales:

locales = ["us", "gb", "de", "fr", "jp", "br"]

for competitor_id in competitors:
    for locale in locales:
        data = fetch_itunes_lookup(competitor_id, locale)
        store_metadata(competitor_id, locale, data)

Step 3: Extract Keywords

From competitor metadata, extract likely keywords:

def extract_keywords(app_data):
    keywords = set()

    # From title (remove brand name)
    title_words = app_data["trackName"].lower().split()
    keywords.update(title_words)

    # From description (top frequency words)
    desc_words = extract_top_words(app_data["description"], n=20)
    keywords.update(desc_words)

    # Filter stop words
    keywords = filter_stop_words(keywords)

    return keywords

Step 4: Gap Analysis

def find_keyword_gaps(your_keywords, competitor_keywords):
    """Find keywords competitors use that you don't."""
    gaps = competitor_keywords - your_keywords
    return sorted(gaps, key=lambda k: estimate_value(k), reverse=True)

Step 5: Generate Competitive Report

## Competitor ASO Analysis — {Category}

### Competitors Analyzed
1. Competitor A (id: 123456) — 4.8★, 50K ratings
2. Competitor B (id: 789012) — 4.6★, 30K ratings
3. Competitor C (id: 345678) — 4.5★, 25K ratings

### Keyword Coverage Comparison

| Keyword | You | Comp A | Comp B | Comp C | Opportunity |
|---------|-----|--------|--------|--------|-------------|
| photo editor | ✓ | ✓ | ✓ | ✓ | Low (saturated) |
| ai enhance | ✗ | ✓ | ✓ | ✗ | High |
| background remove | ✗ | ✓ | ✓ | ✓ | High |
| collage maker | ✓ | ✗ | ✓ | ✓ | Covered |
| beauty camera | ✗ | ✓ | ✗ | ✓ | Medium |

### Keyword Gaps (High Opportunity)
1. "ai enhance" — Used by 2/3 competitors, you're missing
2. "background remove" — Used by 3/3 competitors
3. "portrait mode" — Growing trend, 2/3 competitors

### Title/Subtitle Patterns
- 3/3 competitors include "Photo" in title
- 2/3 use "Pro" or "Plus" suffix
- All include primary feature in subtitle

### Recommendations
1. Add "ai enhance" to keywords — high competitor usage
2. Consider "background" variations in title/subtitle
3. Test "Pro" suffix for premium positioning

---

Quick Reference — API Endpoints

| Task | Method | Endpoint | |------|--------|----------| | List app infos | GET | /v1/apps/{id}/appInfos | | List app info localizations | GET | /v1/appInfos/{id}/appInfoLocalizations | | Update app info localization | PATCH | /v1/appInfoLocalizations/{id} | | List version localizations | GET | /v1/appStoreVersions/{id}/appStoreVersionLocalizations | | Create version localization | POST | /v1/appStoreVersionLocalizations | | Update version localization | PATCH | /v1/appStoreVersionLocalizations/{id} | | Delete version localization | DELETE | /v1/appStoreVersionLocalizations/{id} | | iTunes lookup | GET | itunes.apple.com/lookup?id={id}&country={cc} | | iTunes search | GET | itunes.apple.com/search?term={q}&media=software |

---

ASO Checklist

Before submitting metadata updates:

• [ ] All character limits respected
• [ ] No duplicate keywords across Title/Subtitle/Keywords
• [ ] No stop words in keywords field
• [ ] Keywords comma-separated without spaces
• [ ] Cross-localization strategy applied
• [ ] High-value markets localized
• [ ] Keywords localized (not just translated)
• [ ] No competitor brand names in keywords
• [ ] Description is conversion-optimized
• [ ] Promotional text ready (can update anytime)

---

Reference Files

| File | Purpose | |------|---------| | aso-best-practices.md | Character limits, rules, optimization tips | | locale-reference.md | All 38 locales with cross-indexing map | | api-endpoints.md | App Store Connect API details | | keyword-strategies.md | Advanced keyword research techniques |