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

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

Download specific locales

Download only certain locales:

asc localizations download \
  --version "VERSION_ID" \
  --locale "en-US,es-ES" \
  --path "./localizations"

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

Test with dry-run

Validate files without uploading:

asc localizations upload \
  --version "VERSION_ID" \
  --path "./localizations" \
  --dry-run

Upload version localizations

Upload all edited localizations:

asc localizations upload \
  --version "VERSION_ID" \
  --path "./localizations"

Upload specific locales

Upload only certain locales:

asc localizations upload \
  --version "VERSION_ID" \
  --locale "en-US,es-ES" \
  --path "./localizations"

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

Create app info localization

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

Create version localization

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

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

Download before editing: Always download current localizations before making changes
Use dry-run: Test uploads with --dry-run to catch errors before applying changes
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
Optimize keywords: Research popular search terms and use all 100 characters effectively
Keep what’s new concise: Focus on 3-5 key updates that matter to users
Maintain consistency: Keep terminology and tone consistent across all locales
Use professional translation: For important markets, use professional translation services
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"

App Store Submission - Submit apps with validated metadata
Screenshots - Manage visual assets
App Info API - Detailed API reference

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

Metadata management

Metadata Management

Overview

App-Level Metadata (App Info)

View App Info Localizations

Update App Info Localization

Create Another Language Localization

Version-Specific Metadata

View Version Localizations

Update Version Localization

Update Marketing URL and Support URL

Update Promotional Text

Working with Localization Files

Download Localizations

Edit .strings Files

Upload Localizations

Search Keywords Management

List Current Keywords

Update Keywords

Preview and Screenshot Sets

List Preview Sets

Get Preview Set Details

List Screenshot Sets

Get Screenshot Set Details

Complete Localization Workflow

Multi-Language Support

Supported Locales

Add a New Language

Bulk Language Setup

Best Practices

Troubleshooting

”Localization not found”

“Invalid keywords format”

“Failed to upload .strings file”

“Submission preflight failed: missing fields”

​Metadata Management

​Overview

​App-Level Metadata (App Info)

​View App Info Localizations

​Update App Info Localization

​Create Another Language Localization

​Version-Specific Metadata

​View Version Localizations

​Update Version Localization

​Update Marketing URL and Support URL

​Update Promotional Text

​Working with Localization Files

​Download Localizations

​Edit .strings Files

​Upload Localizations

​Search Keywords Management

​List Current Keywords

​Update Keywords

​Preview and Screenshot Sets

​List Preview Sets

​Get Preview Set Details

​List Screenshot Sets

​Get Screenshot Set Details

​Complete Localization Workflow

​Multi-Language Support

​Supported Locales

​Add a New Language

​Bulk Language Setup

​Best Practices

​Troubleshooting

​”Localization not found”

​“Invalid keywords format”

​“Failed to upload .strings file”

​“Submission preflight failed: missing fields”

​Related Commands

Metadata Management

Overview

App-Level Metadata (App Info)

View App Info Localizations

Update App Info Localization

Create Another Language Localization

Version-Specific Metadata

View Version Localizations

Update Version Localization

Update Marketing URL and Support URL

Update Promotional Text

Working with Localization Files

Download Localizations

Edit .strings Files

Upload Localizations

Search Keywords Management

List Current Keywords

Update Keywords

Preview and Screenshot Sets

List Preview Sets

Get Preview Set Details

List Screenshot Sets

Get Screenshot Set Details

Complete Localization Workflow

Multi-Language Support

Supported Locales

Add a New Language

Bulk Language Setup

Best Practices

Troubleshooting

”Localization not found”

“Invalid keywords format”

“Failed to upload .strings file”

“Submission preflight failed: missing fields”

Related Commands