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

# Localizations

# Localization Commands

> Manage App Store localization metadata

## Overview

Localization commands manage App Store metadata for different languages and regions, including descriptions, keywords, screenshots, and previews.

## Commands

### `asc localizations list`

List localization metadata for an app or version.

<ParamField path="--version" type="string">
  App Store version ID (required for version localizations)
</ParamField>

<ParamField path="--app" type="string">
  App Store Connect app ID (or `ASC_APP_ID` env, required for app-info localizations)
</ParamField>

<ParamField path="--app-info" type="string">
  App Info ID (optional override)
</ParamField>

<ParamField path="--type" type="string" default="version">
  Localization type: `version` (default) or `app-info`
</ParamField>

<ParamField path="--locale" type="string">
  Filter by locale(s), comma-separated (e.g., en-US,ja)
</ParamField>

<ParamField path="--limit" type="integer">
  Maximum results per page (1-200)
</ParamField>

<ParamField path="--next" type="string">
  Fetch next page using a links.next URL
</ParamField>

<ParamField path="--paginate" type="boolean" default="false">
  Automatically fetch all pages (aggregate results)
</ParamField>

**Examples:**

```bash theme={null} theme={null}
asc localizations list --version "VERSION_ID"
asc localizations list --app "APP_ID" --type app-info
asc localizations list --version "VERSION_ID" --locale "en-US,ja"
asc localizations list --version "VERSION_ID" --paginate
```

**Response:**

```json theme={null} theme={null}
{
  "data": [
    {
      "id": "LOCALIZATION_ID",
      "type": "appStoreVersionLocalizations",
      "attributes": {
        "locale": "en-US",
        "description": "My app description",
        "keywords": "productivity, tools",
        "supportUrl": "https://example.com/support",
        "marketingUrl": "https://example.com",
        "promotionalText": "Try our new features!",
        "whatsNew": "Bug fixes and improvements"
      }
    }
  ]
}
```

***

### `asc localizations download`

Download localizations to .strings files.

<ParamField path="--version" type="string">
  App Store version ID (required for version localizations)
</ParamField>

<ParamField path="--app" type="string">
  App Store Connect app ID (required for app-info localizations)
</ParamField>

<ParamField path="--app-info" type="string">
  App Info ID (optional override)
</ParamField>

<ParamField path="--type" type="string" default="version">
  Localization type: `version` (default) or `app-info`
</ParamField>

<ParamField path="--locale" type="string">
  Filter by locale(s), comma-separated
</ParamField>

<ParamField path="--path" type="string" default="localizations">
  Output path (directory or .strings file)
</ParamField>

<ParamField path="--paginate" type="boolean" default="false">
  Automatically fetch all pages
</ParamField>

**Examples:**

```bash theme={null} theme={null}
asc localizations download --version "VERSION_ID" --path "./localizations"
asc localizations download --app "APP_ID" --type app-info --path "./localizations"
asc localizations download --version "VERSION_ID" --locale "en-US" --path "en-US.strings"
asc localizations download --version "VERSION_ID" --paginate --path "./localizations"
```

**Response:**

```json theme={null} theme={null}
{
  "type": "version",
  "versionId": "VERSION_ID",
  "outputPath": "./localizations",
  "files": [
    "./localizations/en-US.strings",
    "./localizations/ja.strings"
  ]
}
```

***

### `asc localizations upload`

Upload localizations from .strings files.

<ParamField path="--version" type="string">
  App Store version ID (required for version localizations)
</ParamField>

<ParamField path="--app" type="string">
  App Store Connect app ID (required for app-info localizations)
</ParamField>

<ParamField path="--app-info" type="string">
  App Info ID (optional override)
</ParamField>

<ParamField path="--type" type="string" default="version">
  Localization type: `version` (default) or `app-info`
</ParamField>

<ParamField path="--locale" type="string">
  Filter by locale(s), comma-separated
</ParamField>

<ParamField path="--path" type="string" required>
  Input path (directory or .strings file)
</ParamField>

<ParamField path="--dry-run" type="boolean" default="false">
  Validate file without uploading
</ParamField>

**Examples:**

```bash theme={null} theme={null}
asc localizations upload --version "VERSION_ID" --path "./localizations"
asc localizations upload --app "APP_ID" --type app-info --path "./localizations"
asc localizations upload --version "VERSION_ID" --locale "en-US" --path "en-US.strings"
asc localizations upload --version "VERSION_ID" --path "./localizations" --dry-run
```

**Response:**

```json theme={null} theme={null}
{
  "type": "version",
  "versionId": "VERSION_ID",
  "dryRun": false,
  "results": [
    {
      "locale": "en-US",
      "status": "updated",
      "fieldsUpdated": ["description", "whatsNew"]
    },
    {
      "locale": "ja",
      "status": "created"
    }
  ]
}
```

***

### `asc localizations supported-locales`

List the shared App Store localization catalog for a version and show which
locales are already configured.

<ParamField path="--version" type="string" required>
  App Store version ID to inspect against the shared CLI locale catalog
</ParamField>

Use this command when you need the canonical locale codes accepted by ASC for a
version workflow, such as `ar-SA`, `de-DE`, `zh-Hans`, and `zh-Hant`.

**Examples:**

```bash theme={null} theme={null}
asc localizations supported-locales --version "VERSION_ID"
asc localizations supported-locales --version "VERSION_ID" --output json --pretty
```

***

### `asc localizations create`

Create a new version localization.

<ParamField path="--version" type="string" required>
  App Store version ID to create the localization under
</ParamField>

<ParamField path="--locale" type="string" required>
  Canonical App Store Connect locale code to create
</ParamField>

Use canonical App Store Connect locale identifiers for `--locale`. Common
accepted forms include `en-US`, `es-MX`, `de-DE`, `ja`, `ar-SA`, `zh-Hans`, and
`zh-Hant`.

Run `asc localizations supported-locales --version "VERSION_ID"` to inspect the
shared CLI locale catalog for that version before creating a new locale.

Common failures:

* Use `ar-SA` instead of `ar`
* Use `de-DE` instead of `de`
* Use `zh-Hans` / `zh-Hant` instead of `zh-Hans-CN` / `zh-Hant-TW`

**Examples:**

```bash theme={null} theme={null}
asc localizations create --version "VERSION_ID" --locale "ja"
asc localizations create --version "VERSION_ID" --locale "ar-SA" --description "Arabic app" --keywords "arabic,productivity"
asc localizations create --version "VERSION_ID" --locale "zh-Hans" --description "Simplified Chinese app" --keywords "simplified,chinese"
```

***

### `asc localizations update`

Update localization metadata.

<ParamField path="--version" type="string">
  App Store version ID for version localizations
</ParamField>

<ParamField path="--app" type="string">
  App Store Connect app ID (or `ASC_APP_ID`) for app-info localizations
</ParamField>

<ParamField path="--app-info" type="string">
  App Info ID (optional override for app-info localizations)
</ParamField>

<ParamField path="--type" type="string" default="version">
  Localization type: `version` (default) or `app-info`
</ParamField>

<ParamField path="--locale" type="string" required>
  Exact App Store Connect locale value to update
</ParamField>

Use the exact App Store Connect locale already present on the app or version
when you pass `--locale`. If update fails with a locale mismatch, run
`asc localizations list` and reuse the `locale` value returned by ASC.

For version workflows, run `asc localizations supported-locales --version
"VERSION_ID"` to inspect the shared CLI catalog, and `asc localizations list --version "VERSION_ID"` to see locales already configured on the version.

For app-info workflows, use `asc localizations list --app "APP_ID" --type
app-info` to inspect the configured locale values before updating.

Common accepted forms include `en-US`, `de-DE`, `ja`, `ar-SA`, `zh-Hans`, and
`zh-Hant`.

Common failures:

* `ar` is usually stored as `ar-SA`
* `de` is usually stored as `de-DE`
* `zh-Hans-CN` / `zh-Hant-TW` are usually stored as `zh-Hans` / `zh-Hant`

**Examples:**

```bash theme={null} theme={null}
asc localizations update --version "VERSION_ID" --locale "en-US" --description "New description"
asc localizations update --version "VERSION_ID" --locale "en-US" --keywords "new,keywords"
asc localizations update --app "APP_ID" --type app-info --locale "ar-SA" --subtitle "Arabic subtitle"
```

***

## Common Usage Patterns

### Download all localizations for a version

```bash theme={null} theme={null}
asc localizations download --version "VERSION_ID" --paginate --path "./localizations"
```

### Update a specific locale

```bash theme={null} theme={null}
asc localizations upload --version "VERSION_ID" --locale "en-US" --path "en-US.strings"
```

### List all localizations for an app

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

### Dry-run upload to validate

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

## .strings File Format

The .strings file format is a simple key-value format:

```
"description" = "My app description";
"keywords" = "productivity, tools, utilities";
"supportUrl" = "https://example.com/support";
"marketingUrl" = "https://example.com";
"promotionalText" = "Try our new features!";
"whatsNew" = "Bug fixes and performance improvements";
```

## Supported Locales

For the authoritative CLI catalog on a specific version, run
`asc localizations supported-locales --version "VERSION_ID"`.

Use canonical App Store Connect locale identifiers when possible. For example,
prefer `ar-SA` over `ar`, and `zh-Hans` / `zh-Hant` over regional variants like
`zh-Hans-CN` / `zh-Hant-TW`.

Common locales include:

* `en-US` - English (United States)
* `en-GB` - English (United Kingdom)
* `ja` - Japanese
* `de-DE` - German (Germany)
* `fr-FR` - French (France)
* `es-ES` - Spanish (Spain)
* `es-MX` - Spanish (Mexico)
* `ar-SA` - Arabic
* `zh-Hans` - Chinese (Simplified)
* `zh-Hant` - Chinese (Traditional)
* `ko` - Korean
* `pt-BR` - Portuguese (Brazil)

## Localization Types

### Version Localizations

Metadata specific to an app version:

* What's New text
* Description (if not using app-info)
* Keywords (if not using app-info)
* Support URL (if not using app-info)
* Marketing URL
* Promotional text
* Screenshots
* App previews

### App Info Localizations

Metadata shared across all versions:

* App description
* Keywords
* Support URL
* Privacy policy URL
* Subtitle