Back to Details

asc-localize-metadata

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

asc localize metadata

asc 元数据本地化

Use this skill to pull English (or any source locale) App Store metadata, translate it with LLM, and push translations back to App Store Connect — all automated.
使用该技能可拉取英文（或任意源语言区域）的App Store元数据，通过LLM进行翻译，并自动将翻译结果推送回App Store Connect，全程自动化完成。

Command discovery and output conventions

命令查询与输出规范

  • Always confirm flags with 
    --help
    for the exact 
    asc
    version: 
    • asc localizations --help
    • asc localizations download --help
    • asc localizations upload --help
    • asc app-info set --help
  • Prefer explicit long flags (
    --app
    , 
    --version
    , 
    --version-id
    , 
    --type
    , 
    --app-info
    ).
  • Default output is JSON; use 
    --output table
    only for human verification steps.
  • Prefer deterministic ID-based operations. Do not "pick the first row" via 
    head -1
    unless the user explicitly agrees.
  • 始终通过
    --help
    确认对应asc版本的参数： 
    • asc localizations --help
    • asc localizations download --help
    • asc localizations upload --help
    • asc app-info set --help
  • 优先使用明确的长参数（
    --app
    、
    --version
    、
    --version-id
    、
    --type
    、
    --app-info
    ）。
  • 默认输出格式为JSON；仅在人工验证步骤使用
    --output table
    。
  • 优先使用确定性的基于ID的操作。除非用户明确同意，否则不要通过
    head -1
    来“选取第一行”。

Preconditions

前置条件

  • Auth configured (
    asc auth login
    or 
    ASC_*
    env vars)
  • Know your app ID (
    asc apps list
    to find it)
  • At least one locale (typically en-US) already has metadata in App Store Connect
  • 已配置认证（
    asc auth login
    或
    ASC_*
    环境变量）
  • 知晓应用ID（可通过
    asc apps list
    查询）
  • App Store Connect中已存在至少一个语言区域的元数据（通常为en-US）

Supported Locales

支持的语言区域

App Store Connect locales for version and app-info localizations:
ar-SA, ca, cs, da, de-DE, el, en-AU, en-CA, en-GB, en-US,
es-ES, es-MX, fi, fr-CA, fr-FR, he, hi, hr, hu, id, it,
ja, ko, ms, nl-NL, no, pl, pt-BR, pt-PT, ro, ru, sk,
sv, th, tr, uk, vi, zh-Hans, zh-Hant
App Store Connect中支持版本和应用信息本地化的语言区域：
ar-SA, ca, cs, da, de-DE, el, en-AU, en-CA, en-GB, en-US,
es-ES, es-MX, fi, fr-CA, fr-FR, he, hi, hr, hu, id, it,
ja, ko, ms, nl-NL, no, pl, pt-BR, pt-PT, ro, ru, sk,
sv, th, tr, uk, vi, zh-Hans, zh-Hant

Two Types of Metadata

两类元数据

Version Localizations (per-release)

版本本地化（按版本区分）

Fields: 
description
, 
keywords
, 
whatsNew
, 
supportUrl
, 
marketingUrl
, 
promotionalText
字段：
description
、
keywords
、
whatsNew
、
supportUrl
、
marketingUrl
、
promotionalText

App Info Localizations (app-level, persistent)

应用信息本地化（应用级，持久生效）

Fields: 
name
, 
subtitle
, 
privacyPolicyUrl
, 
privacyChoicesUrl
, 
privacyPolicyText
字段：
name
、
subtitle
、
privacyPolicyUrl
、
privacyChoicesUrl
、
privacyPolicyText

Workflow

工作流程

Step 1: Resolve IDs

步骤1：获取ID

bash
undefined
bash
undefined

Find app ID

查询应用ID

asc apps list --output table
asc apps list --output table

Find latest version ID

查询最新版本ID

asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table
asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table

or for editable version:

或查询可编辑版本：

asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table
asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table

Find app info ID (for app-level fields like name/subtitle)

查询应用信息ID（用于名称/副标题等应用级字段）

asc app-infos list --app "APP_ID" --output table

Notes:
- Version-localization fields (description, keywords, whatsNew, etc.) are per-version.
- App-info fields (name, subtitle, privacy URLs/text) are app-level and use `--type app-info`.
- If you only have names (app name, version string) and need IDs deterministically, use `asc-id-resolver`.
asc app-infos list --app "APP_ID" --output table

注意：
- 版本本地化字段（描述、关键词、更新日志等）按版本区分。
- 应用信息字段（名称、副标题、隐私政策链接/文本）为应用级，需使用`--type app-info`参数。
- 若仅知晓名称（应用名称、版本字符串）且需确定性获取ID，可使用`asc-id-resolver`。

Step 2: Download source locale

步骤2：下载源语言区域元数据

bash
undefined
bash
undefined

Download version localizations to local .strings files

将版本本地化内容下载到本地.strings文件

(description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl, ...)

（包含描述、关键词、更新日志、推广文本、支持链接、营销链接等）

asc localizations download --version "VERSION_ID" --path "./localizations"
asc localizations download --version "VERSION_ID" --path "./localizations"

Download app-info localizations to local .strings files

将应用信息本地化内容下载到本地.strings文件

(name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText, ...)

（包含名称、副标题、隐私政策链接、隐私选项链接、隐私政策文本等）

asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"

This creates files like `./localizations/en-US.strings` and `./app-info-localizations/en-US.strings`. If download is unavailable, read fields individually:

```bash
asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"

此操作会生成类似`./localizations/en-US.strings`和`./app-info-localizations/en-US.strings`的文件。若无法下载，可单独读取字段：

```bash

List version localizations to see existing locales and their content

列出版本本地化内容，查看已有的语言区域及其内容

asc localizations list --version "VERSION_ID" --output table
undefined
asc localizations list --version "VERSION_ID" --output table
undefined

Step 3: Translate with LLM

步骤3：通过LLM翻译

For each target locale, translate the source text. Follow these rules:
针对每个目标语言区域翻译源文本，需遵循以下规则：

Translation Guidelines

翻译指南

  • description: Translate naturally, adapt tone to local market. Keep formatting (line breaks, bullet points, emoji). Stay within 4000 chars.
  • keywords: Do NOT literally translate. Research what users in that locale would search for. Comma-separated, max 100 chars total. No duplicates, no app name (Apple adds it automatically).
  • whatsNew: Translate release notes. Keep it concise. Max 4000 chars.
  • promotionalText: Translate marketing hook. Max 170 chars. This can be updated without a new version.
  • subtitle: Translate or adapt tagline. Max 30 chars — this is very tight, may need creative adaptation.
  • name: Usually keep the original app name. Only translate if the user explicitly asks. Max 30 chars.
  • description：自然翻译，适配目标市场语气。保留格式（换行、项目符号、表情符号）。字符数不超过4000。
  • keywords：请勿直译。调研目标语言区域用户的搜索习惯，使用逗号分隔，总字符数不超过100。请勿包含应用名称（Apple会自动添加）。
  • whatsNew：翻译更新日志，保持简洁。字符数不超过4000。
  • promotionalText：翻译推广标语。字符数不超过170。该字段无需提交新版本即可更新。
  • subtitle：创造性改编标语，确保字符数不超过30。
  • name：通常保留原应用名称，仅在用户明确要求时翻译。字符数不超过30。

LLM Translation Prompt Template

LLM翻译提示词模板

For each target locale, use this approach:
Translate the following App Store metadata from {source_locale} to {target_locale}.

Rules:
- description: Natural, fluent translation. Preserve formatting (line breaks, bullets, emoji). Max 4000 chars.
- keywords: Do NOT literally translate. Choose keywords native speakers would search for in the App Store. Comma-separated, max 100 chars total. Do not include the app name.
- whatsNew: Translate release notes naturally. Max 4000 chars.
- promotionalText: Translate marketing tagline. Max 170 chars.
- subtitle: Adapt tagline creatively to fit 30 chars max.
- name: Keep the original app name unless explicitly requested to translate it. Max 30 chars.
- Respect cultural context. A playful tone in English may need adjustment for formal markets (e.g., ja, de-DE).

Source ({source_locale}):
description: """
{description}
"""

keywords: {keywords}

whatsNew: """
{whatsNew}
"""

promotionalText: {promotionalText}

name: {name}

subtitle: {subtitle}
针对每个目标语言区域，使用以下模板：
将以下App Store元数据从{source_locale}翻译为{target_locale}。

规则：
- description：自然流畅翻译，保留格式（换行、项目符号、表情符号），字符数不超过4000。
- keywords：请勿直译，选择目标语言区域用户在App Store中会使用的搜索关键词，逗号分隔，总字符数不超过100，请勿包含应用名称。
- whatsNew：自然翻译更新日志，字符数不超过4000。
- promotionalText：翻译推广标语，字符数不超过170。
- subtitle：创造性改编标语，确保字符数不超过30。
- name：除非明确要求翻译，否则保留原应用名称，字符数不超过30。
- 尊重文化背景：英文中的轻松语气在部分市场（如日语、德语）可能需要调整为正式语气。

源语言({source_locale})：
description: """
{description}
"""

keywords: {keywords}

whatsNew: """
{whatsNew}
"""

promotionalText: {promotionalText}

name: {name}

subtitle: {subtitle}

Step 4: Upload translations

步骤4：上传翻译结果

Option A: Via .strings files (bulk)

选项A：通过.strings文件（批量上传）

Create a 
.strings
file per locale in the appropriate directory.
Version localization example:
// nl-NL.strings
"description" = "Je app-beschrijving hier";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "Bugfixes en verbeteringen";
"promotionalText" = "Leer de tafels van vermenigvuldiging!";
Then upload version localizations:
bash
asc localizations upload --version "VERSION_ID" --path "./localizations"
App-info localization example:
// nl-NL.strings
"subtitle" = "Leer tafels spelenderwijs";
Then upload app-info localizations:
bash
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
在对应目录下为每个语言区域创建.strings文件。
版本本地化示例：
// nl-NL.strings
"description" = "Je app-beschrijving hier";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "Bugfixes en verbeteringen";
"promotionalText" = "Leer de tafels van vermenigvuldiging!";
然后上传版本本地化内容：
bash
asc localizations upload --version "VERSION_ID" --path "./localizations"
应用信息本地化示例：
// nl-NL.strings
"subtitle" = "Leer tafels spelenderwijs";
然后上传应用信息本地化内容：
bash
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"

Option B: Via individual commands (fine control)

选项B：通过单个命令（精细控制）

bash
undefined
bash
undefined

Version localization fields (fine control).

版本本地化字段（精细控制）

Prefer passing the explicit version ID for determinism.

优先传入明确的版本ID以确保确定性

asc app-info set --app "APP_ID" --version-id "VERSION_ID" --locale "nl-NL"
--description "Je beschrijving..."
--keywords "wiskunde,kinderen,tafels"
--whats-new "Bugfixes en verbeteringen"

For app-level fields:
```bash
asc app-info set --app "APP_ID" --version-id "VERSION_ID" --locale "nl-NL"
--description "Je beschrijving..."
--keywords "wiskunde,kinderen,tafels"
--whats-new "Bugfixes en verbeteringen"

针对应用级字段：
```bash

Subtitle/name (app-info localization) is managed via app-info localizations.

副标题/名称（应用信息本地化）通过应用信息本地化流程管理。

Use the app-info localization .strings + upload flow (there is no 
asc app-infos localizations ...
command).

使用应用信息本地化.strings文件 + 上传流程（没有
asc app-infos localizations ...
命令）。

1) Edit: ./app-info-localizations/nl-NL.strings

1) 编辑：./app-info-localizations/nl-NL.strings

"subtitle" = "Leer tafels spelenderwijs";

"subtitle" = "Leer tafels spelenderwijs";

2) Upload:

2) 上传：

asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
undefined
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
undefined

Step 5: Verify

步骤5：验证

bash
undefined
bash
undefined

Check all locales are present

检查所有语言区域是否已上传

asc localizations list --version "VERSION_ID" --output table
asc localizations list --version "VERSION_ID" --output table

Check app info localizations

检查应用信息本地化内容

asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
undefined
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
undefined

Character Limits (enforce before upload!)

字符限制（上传前务必遵守！）

FieldLimit
Name30
Subtitle30
Keywords100 (comma-separated)
Description4000
What's New4000
Promotional Text170
Always validate translated text fits within limits before uploading. Truncated text looks unprofessional. If translation exceeds the limit, shorten it — do not truncate mid-sentence.
字段字符限制
应用名称30
副标题30
关键词100（逗号分隔）
描述4000
更新日志4000
推广文本170
上传前务必验证翻译内容是否符合字符限制。截断的文本会显得不专业。若翻译内容超出限制，需重新翻译为更简短的版本，请勿在句中截断。

Full Example: Add nl-NL and ru to Roxy Math

完整示例：为Roxy Math添加nl-NL和ru语言区域

bash
undefined
bash
undefined

1) Resolve IDs deterministically (do not auto-pick the "first" row)

1) 确定性获取ID（请勿自动选取“第一行”）

If you only have names, use asc-id-resolver skill.

若仅知晓名称，使用asc-id-resolver技能。

asc apps list --output table APP_ID="APP_ID_HERE"
asc versions list --app "$APP_ID" --state PREPARE_FOR_SUBMISSION --output table VERSION_ID="VERSION_ID_HERE"
asc app-infos list --app "$APP_ID" --output table APP_INFO_ID="APP_INFO_ID_HERE"
asc apps list --output table APP_ID="APP_ID_HERE"
asc versions list --app "$APP_ID" --state PREPARE_FOR_SUBMISSION --output table VERSION_ID="VERSION_ID_HERE"
asc app-infos list --app "$APP_ID" --output table APP_INFO_ID="APP_INFO_ID_HERE"

2) Download English source (or your chosen source locale)

2) 下载英文源数据（或所选源语言区域）

asc localizations download --version "$VERSION_ID" --path "./localizations" asc localizations download --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"
asc localizations download --version "$VERSION_ID" --path "./localizations" asc localizations download --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"

3) Read en-US.strings, translate to nl-NL and ru (LLM step)

3) 读取en-US.strings，通过LLM翻译为nl-NL和ru语言

4) Write nl-NL.strings and ru.strings to:

4) 将nl-NL.strings和ru.strings写入以下目录：

- ./localizations/ (version localization fields)

- ./localizations/（版本本地化字段）

- ./app-info-localizations/ (subtitle/name/privacy fields)

- ./app-info-localizations/（副标题/名称/隐私政策字段）

5) Upload all

5) 上传所有翻译内容

asc localizations upload --version "$VERSION_ID" --path "./localizations" asc localizations upload --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"
asc localizations upload --version "$VERSION_ID" --path "./localizations" asc localizations upload --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --path "./app-info-localizations"

6) Verify

6) 验证

asc localizations list --version "$VERSION_ID" --output table asc localizations list --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --output table
undefined
asc localizations list --version "$VERSION_ID" --output table asc localizations list --app "$APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
undefined

Agent Behavior

Agent 行为规范

  1. Always start by reading the source locale — never translate from memory or assumptions.
  2. Check existing localizations first — don't overwrite existing translations unless the user asks to update them.
  3. Version vs app-info is different — version fields live under 
    --version "VERSION_ID"
    ; subtitle/name/privacy live under 
    --app ... --type app-info
    .
  4. Prefer deterministic IDs — do not select IDs via 
    head -1
    unless explicitly requested; use 
    --output table
    for selection or 
    asc-id-resolver
    .
  5. Validate character limits before uploading. Count characters for each field. If over limit, re-translate shorter.
  6. Keywords are special — do not literally translate. Research locale-appropriate search terms. Think like a user searching the App Store in that language.
  7. Show the user translations before uploading — present a summary table of all fields × locales for approval. Do not push without confirmation.
  8. Process one locale at a time if translating many languages — easier to review and catch errors.
  9. If upload fails for a locale, log the error, continue with other locales, report all failures at the end.
  10. For updates to existing localizations — download current, show diff of what will change, get approval, then upload.
  1. 始终先读取源语言区域内容 — 切勿凭记忆或假设进行翻译。
  2. 先检查已有本地化内容 — 除非用户要求更新，否则请勿覆盖现有翻译。
  3. 版本本地化与应用信息本地化不同 — 版本字段使用
    --version "VERSION_ID"
    参数；副标题/名称/隐私政策字段使用
    --app ... --type app-info
    参数。
  4. 优先使用确定性ID — 除非明确要求，否则请勿通过
    head -1
    选择ID；使用
    --output table
    手动选择或使用
    asc-id-resolver
    。
  5. 验证字符限制 — 上传前统计每个字段的字符数。若超出限制，重新翻译为更简短的内容。
  6. 关键词需特殊处理 — 请勿直译，调研目标语言区域的合适搜索词，站在该语言区域用户的角度思考App Store搜索习惯。
  7. 上传前向用户展示翻译内容 — 提供所有字段×语言区域的汇总表格供用户确认。未经确认请勿推送。
  8. 若翻译多种语言，一次处理一个语言区域 — 便于审核和发现错误。
  9. 若某语言区域上传失败 — 记录错误，继续处理其他语言区域，最后汇总所有失败情况。
  10. 若更新现有本地化内容 — 下载当前内容，展示即将变更的差异，获取用户确认后再上传。

Notes

注意事项

  • Version localizations are tied to a specific version. Create the version first if it doesn't exist.
  • promotionalText
    can be updated anytime without a new version submission.
  • whatsNew
    is only relevant for updates, not the first version.
  • Use 
    asc-id-resolver
    skill if you only have app/version names instead of IDs.
  • Use 
    asc-metadata-sync
    skill for non-translation metadata operations.
  • For subscription/IAP display name localization, use 
    asc-subscription-localization
    skill instead.
  • 版本本地化内容与特定版本绑定。若版本不存在，需先创建版本。
  • promotionalText
    可随时更新，无需提交新版本。
  • whatsNew
    仅对更新版本有效，首个版本无需填写。
  • 若仅知晓应用/版本名称而非ID，使用
    asc-id-resolver
    技能。
  • 非翻译类元数据操作使用
    asc-metadata-sync
    技能。
  • 订阅/IAP显示名称本地化请使用
    asc-subscription-localization
    技能。