Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Metadata Management

Manage app metadata and localizations across multiple languages
Manage your app’s metadata, descriptions, keywords, and localizations efficiently using the CLI.

​
Overview

App metadata includes:
  • App Info: Name, subtitle, privacy policy, category (persistent across versions)
  • Version Localizations: Description, keywords, what’s new, release notes (version-specific)
  • Screenshots and Previews: Visual assets for the App Store
  • Search Keywords: Terms to improve discoverability
The CLI separates version-specific metadata from app-level metadata, allowing you to manage each independently.

​
App-Level Metadata (App Info)

App Info contains metadata that persists across all versions:

​
View App Info Localizations

asc localizations list --app "YOUR_APP_ID" --type app-info
Filter by locale: 
asc localizations list --app "YOUR_APP_ID" --type app-info --locale "en-US,es-ES"

​
Update App Info Localization

asc app-setup info set \
  --app "YOUR_APP_ID" \
  --locale "en-US" \
  --name "My Awesome App" \
  --subtitle "The best app for productivity" \
  --privacy-policy-url "https://example.com/privacy"

​
Create Another Language Localization

Seed the target locale explicitly with app-level metadata: 
asc app-setup info set \
  --app "YOUR_APP_ID" \
  --locale "fr-FR" \
  --name "Mon Application Géniale" \
  --subtitle "La meilleure app pour la productivité"
Then update locale-specific fields: 
asc app-setup info set \
  --app "YOUR_APP_ID" \
  --locale "fr-FR" \
  --privacy-policy-url "https://example.com/fr/privacy"

​
Version-Specific Metadata

Version localizations contain metadata specific to each app version:

​
View Version Localizations

asc localizations list --version "VERSION_ID"
Filter by specific locales: 
asc localizations list --version "VERSION_ID" --locale "en-US,ja"

​
Update Version Localization

asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --description "Comprehensive app description with key features and benefits" \
  --keywords "productivity,tools,utility,workflow" \
  --whats-new "New features in this version:\n- Feature 1\n- Feature 2\n- Bug fixes"

​
Update Marketing URL and Support URL

asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --marketing-url "https://example.com/myapp" \
  --support-url "https://support.example.com"

​
Update Promotional Text

asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --promotional-text "Limited time offer: Get 50% off premium features!"

​
Working with Localization Files

For bulk operations, use .strings file format:

​
Download Localizations

1

Download version localizations

Download all version localizations to a directory:
asc localizations download \
  --version "VERSION_ID" \
  --path "./localizations" \
  --paginate
This creates files like:
localizations/
├── en-US.strings
├── es-ES.strings
├── fr-FR.strings
└── ja.strings
2

Download specific locales

Download only certain locales:
asc localizations download \
  --version "VERSION_ID" \
  --locale "en-US,es-ES" \
  --path "./localizations"
3

Download app info localizations

Download app-level metadata:
asc localizations download \
  --app "YOUR_APP_ID" \
  --type app-info \
  --path "./app-info-localizations" \
  --paginate

​
Edit .strings Files

The .strings files use standard format: 
/* App Store Description */
"description" = "Your comprehensive app description here...";

/* Search Keywords (comma-separated) */
"keywords" = "productivity,tools,utility";

/* What's New */
"whatsNew" = "New in this version:\n- Feature 1\n- Feature 2";

/* Marketing URL */
"marketingUrl" = "https://example.com/myapp";

/* Support URL */
"supportUrl" = "https://support.example.com";

/* Promotional Text */
"promotionalText" = "Limited time promotion!";

​
Upload Localizations

1

Test with dry-run

Validate files without uploading:
asc localizations upload \
  --version "VERSION_ID" \
  --path "./localizations" \
  --dry-run
2

Upload version localizations

Upload all edited localizations:
asc localizations upload \
  --version "VERSION_ID" \
  --path "./localizations"
3

Upload specific locales

Upload only certain locales:
asc localizations upload \
  --version "VERSION_ID" \
  --locale "en-US,es-ES" \
  --path "./localizations"
4

Upload app info localizations

Upload app-level metadata:
asc localizations upload \
  --app "YOUR_APP_ID" \
  --type app-info \
  --path "./app-info-localizations"

​
Search Keywords Management

Optimize App Store search with keywords:

​
List Current Keywords

asc localizations search-keywords list --localization-id "LOCALIZATION_ID"

​
Update Keywords

asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --keywords "productivity,calendar,tasks,todo,organizer,planner,schedule"
Keywords are limited to 100 characters total (including commas). Focus on relevant, high-traffic search terms.

​
Preview and Screenshot Sets

​
List Preview Sets

asc localizations preview-sets list --localization-id "LOCALIZATION_ID"

​
Get Preview Set Details

asc localizations preview-sets view --id "PREVIEW_SET_ID"

​
List Screenshot Sets

asc localizations screenshot-sets list --localization-id "LOCALIZATION_ID"

​
Get Screenshot Set Details

asc localizations screenshot-sets view --id "SCREENSHOT_SET_ID"
For uploading screenshots, see the Screenshots Guide.

​
Complete Localization Workflow

Here’s a complete workflow for managing localizations: 
#!/bin/bash
set -e

# Configuration
export ASC_APP_ID="YOUR_APP_ID"
VERSION="1.0.0"

# 1. Get version ID
VERSION_ID=$(asc versions list \
  --app "$ASC_APP_ID" \
  --output json | \
  jq -r '.data[] | select(.attributes.versionString == "'$VERSION'") | .id' | head -1)

echo "Version ID: $VERSION_ID"

# 2. Download existing localizations
asc localizations download \
  --version "$VERSION_ID" \
  --path "./localizations" \
  --paginate

# 3. Edit files locally
echo "Edit the .strings files in ./localizations/"
read -p "Press enter when ready to upload..."

# 4. Test with dry-run
asc localizations upload \
  --version "$VERSION_ID" \
  --path "./localizations" \
  --dry-run

# 5. Upload changes
echo "Uploading localizations..."
asc localizations upload \
  --version "$VERSION_ID" \
  --path "./localizations"

echo "Localizations updated successfully!"

# 6. Verify changes
asc localizations list --version "$VERSION_ID" --output table

​
Multi-Language Support

​
Supported Locales

Common App Store locales: Use asc localizations supported-locales --version "VERSION_ID" to inspect the shared CLI locale catalog and see which version locales are already configured.
  • en-US - English (US)
  • en-GB - English (UK)
  • es-ES - Spanish (Spain)
  • es-MX - Spanish (Mexico)
  • fr-FR - French
  • de-DE - German
  • it - Italian
  • ja - Japanese
  • ko - Korean
  • pt-BR - Portuguese (Brazil)
  • pt-PT - Portuguese (Portugal)
  • ru - Russian
  • zh-Hans - Chinese (Simplified)
  • zh-Hant - Chinese (Traditional)
  • ar-SA - Arabic
  • nl-NL - Dutch
  • th - Thai
  • vi - Vietnamese

​
Add a New Language

1

Create app info localization

asc app-setup info set \
  --app "YOUR_APP_ID" \
  --locale "ja" \
  --name "アプリ名" \
  --subtitle "日本語のサブタイトル"
2

Create version localization

asc localizations create \
  --version "VERSION_ID" \
  --locale "ja" \
  --description "日本語の説明" \
  --keywords "生産性,ツール" \
  --whats-new "新機能"
3

Upload screenshots for the locale

See the Screenshots Guide for uploading locale-specific screenshots.

​
Bulk Language Setup

Set up multiple languages at once: 
#!/bin/bash

LOCALES=("es-ES" "fr-FR" "de-DE" "ja" "zh-Hans")
VERSION_ID="YOUR_VERSION_ID"
APP_ID="YOUR_APP_ID"

for locale in "${LOCALES[@]}"; do
  echo "Setting up $locale..."
  
  # Seed app info localization for this locale
  asc app-setup info set \
    --app "$APP_ID" \
    --locale "$locale" \
    --name "TODO localized app name" \
    --subtitle "TODO localized app subtitle"
  
  # Note: You'll still need to translate the actual text content
  # This just creates the locale structure
done

echo "All locales created. Update translations in App Store Connect or via CLI."

​
Best Practices

  1. Download before editing: Always download current localizations before making changes
  2. Use dry-run: Test uploads with --dry-run to catch errors before applying changes
  3. Separate app info from version metadata: Update persistent metadata (name, subtitle) via app-setup info set; create new version locales with localizations create, then edit existing version metadata with localizations update
  4. Optimize keywords: Research popular search terms and use all 100 characters effectively
  5. Keep what’s new concise: Focus on 3-5 key updates that matter to users
  6. Maintain consistency: Keep terminology and tone consistent across all locales
  7. Use professional translation: For important markets, use professional translation services
  8. Test in target regions: If possible, have native speakers review localizations

​
Troubleshooting

​
”Localization not found”

Problem: The locale doesn’t exist for the version. Solution: Create the localization first: 
asc localizations create \
  --version "VERSION_ID" \
  --locale "ja" \
  --description "Initial description"

​
“Invalid keywords format”

Problem: Keywords exceed 100 characters or contain invalid characters. Solution: Trim keywords to fit the limit: 
# Good (under 100 chars)
--keywords "productivity,task,calendar,todo,planner"

# Bad (over 100 chars)
--keywords "productivity,task,calendar,todo,planner,organizer,scheduler,reminder,notes,documents,collaboration"

​
“Failed to upload .strings file”

Problem: File format is incorrect or contains parsing errors. Solution: Validate the file format: 
/* Correct format */
"description" = "Value here";

/* Incorrect - missing semicolon */
"description" = "Value here"

/* Incorrect - missing quotes */
description = "Value here";

​
“Submission preflight failed: missing fields”

Problem: Required localization fields are empty when submitting. Solution: Ensure all required fields are populated: 
asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --description "Required description" \
  --keywords "required,keywords" \
  --whats-new "Required what's new text"