> ## 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

# 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

```bash theme={null} theme={null}
asc localizations list --app "YOUR_APP_ID" --type app-info
```

Filter by locale:

```bash theme={null} theme={null}
asc localizations list --app "YOUR_APP_ID" --type app-info --locale "en-US,es-ES"
```

### Update App Info Localization

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
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

```bash theme={null} theme={null}
asc localizations list --version "VERSION_ID"
```

Filter by specific locales:

```bash theme={null} theme={null}
asc localizations list --version "VERSION_ID" --locale "en-US,ja"
```

### Update Version Localization

```bash theme={null} theme={null}
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

```bash theme={null} theme={null}
asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --marketing-url "https://example.com/myapp" \
  --support-url "https://support.example.com"
```

### Update Promotional Text

```bash theme={null} theme={null}
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

<Steps>
  <Step title="Download version localizations">
    Download all version localizations to a directory:

    ```bash theme={null} theme={null}
    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
    ```
  </Step>

  <Step title="Download specific locales">
    Download only certain locales:

    ```bash theme={null} theme={null}
    asc localizations download \
      --version "VERSION_ID" \
      --locale "en-US,es-ES" \
      --path "./localizations"
    ```
  </Step>

  <Step title="Download app info localizations">
    Download app-level metadata:

    ```bash theme={null} theme={null}
    asc localizations download \
      --app "YOUR_APP_ID" \
      --type app-info \
      --path "./app-info-localizations" \
      --paginate
    ```
  </Step>
</Steps>

### Edit .strings Files

The `.strings` files use standard format:

```strings theme={null} theme={null}
/* 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

<Steps>
  <Step title="Test with dry-run">
    Validate files without uploading:

    ```bash theme={null} theme={null}
    asc localizations upload \
      --version "VERSION_ID" \
      --path "./localizations" \
      --dry-run
    ```
  </Step>

  <Step title="Upload version localizations">
    Upload all edited localizations:

    ```bash theme={null} theme={null}
    asc localizations upload \
      --version "VERSION_ID" \
      --path "./localizations"
    ```
  </Step>

  <Step title="Upload specific locales">
    Upload only certain locales:

    ```bash theme={null} theme={null}
    asc localizations upload \
      --version "VERSION_ID" \
      --locale "en-US,es-ES" \
      --path "./localizations"
    ```
  </Step>

  <Step title="Upload app info localizations">
    Upload app-level metadata:

    ```bash theme={null} theme={null}
    asc localizations upload \
      --app "YOUR_APP_ID" \
      --type app-info \
      --path "./app-info-localizations"
    ```
  </Step>
</Steps>

## Search Keywords Management

Optimize App Store search with keywords:

### List Current Keywords

```bash theme={null} theme={null}
asc localizations search-keywords list --localization-id "LOCALIZATION_ID"
```

### Update Keywords

```bash theme={null} theme={null}
asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --keywords "productivity,calendar,tasks,todo,organizer,planner,schedule"
```

<Note>
  Keywords are limited to 100 characters total (including commas). Focus on relevant, high-traffic search terms.
</Note>

## Preview and Screenshot Sets

### List Preview Sets

```bash theme={null} theme={null}
asc localizations preview-sets list --localization-id "LOCALIZATION_ID"
```

### Get Preview Set Details

```bash theme={null} theme={null}
asc localizations preview-sets view --id "PREVIEW_SET_ID"
```

### List Screenshot Sets

```bash theme={null} theme={null}
asc localizations screenshot-sets list --localization-id "LOCALIZATION_ID"
```

### Get Screenshot Set Details

```bash theme={null} theme={null}
asc localizations screenshot-sets view --id "SCREENSHOT_SET_ID"
```

For uploading screenshots, see the [Screenshots Guide](/guides/screenshots).

## Complete Localization Workflow

Here's a complete workflow for managing localizations:

```bash theme={null} theme={null}
#!/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

<Steps>
  <Step title="Create app info localization">
    ```bash theme={null} theme={null}
    asc app-setup info set \
      --app "YOUR_APP_ID" \
      --locale "ja" \
      --name "アプリ名" \
      --subtitle "日本語のサブタイトル"
    ```
  </Step>

  <Step title="Create version localization">
    ```bash theme={null} theme={null}
    asc localizations create \
      --version "VERSION_ID" \
      --locale "ja" \
      --description "日本語の説明" \
      --keywords "生産性,ツール" \
      --whats-new "新機能"
    ```
  </Step>

  <Step title="Upload screenshots for the locale">
    See the [Screenshots Guide](/guides/screenshots) for uploading locale-specific screenshots.
  </Step>
</Steps>

### Bulk Language Setup

Set up multiple languages at once:

```bash theme={null} theme={null}
#!/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:

```bash theme={null} theme={null}
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:

```bash theme={null} theme={null}
# 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:

```strings theme={null} theme={null}
/* 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:

```bash theme={null} theme={null}
asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --description "Required description" \
  --keywords "required,keywords" \
  --whats-new "Required what's new text"
```

## Related Commands

* [App Store Submission](/guides/app-store-submission) - Submit apps with validated metadata
* [Screenshots](/guides/screenshots) - Manage visual assets
* [App Info API](/commands/app-info) - Detailed API reference