asc-localize-metadata

asc 本地化元数据

使用此技能从 App Store Connect 拉取英文（或任意源语言）App Store 元数据，借助 LLM 翻译，并将译文推送回 App Store Connect——全程自动完成。

命令发现与输出约定

• 始终使用 --help 确认当前 asc 版本的准确标志：
  • asc localizations --help
  • asc localizations download --help
  • asc localizations upload --help
  • asc apps info edit --help
• 优先使用明确的长标志（--app、--version、--version-id、--type、--app-info）。
• 输出默认会根据 TTY 环境调整：交互式终端使用表格，CI 或其他非交互环境使用 JSON。格式有要求时，请显式指定 --output。
• 优先使用确定性 ID 执行操作。除非用户明确同意，否则不要用 head -1“选取第一行”。

前提条件

• 已配置身份验证（asc auth login 或 ASC_* 环境变量）
• 知道应用 ID（使用 asc apps list 查找）
• App Store Connect 中至少有一个语言区域（通常是 en-US）已有元数据

支持的语言区域

App Store Connect 支持的版本和应用信息本地化语言区域：

ar-SA, bn-BD, ca, cs, da, de-DE, el, en-AU, en-CA, en-GB,
en-US, es-ES, es-MX, fi, fr-CA, fr-FR, gu-IN, he, hi, hr,
hu, id, it, ja, kn-IN, ko, ml-IN, mr-IN, ms, nl-NL, no,
or-IN, pa-IN, pl, pt-BR, pt-PT, ro, ru, sk, sl-SI, sv,
ta-IN, te-IN, th, tr, uk, ur-PK, vi, zh-Hans, zh-Hant

两种元数据类型

版本本地化（按版本发布）

字段：description、keywords、whatsNew、supportUrl、marketingUrl、promotionalText

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

字段：name、subtitle、privacyPolicyUrl、privacyChoicesUrl、privacyPolicyText

工作流

第 1 步：解析 ID

# Find app ID
asc apps list --output table

# Find latest version ID
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

# Find app info ID (for app-level fields like name/subtitle)
asc apps info list --app "APP_ID" --output table

说明：

• 版本本地化字段（description、keywords、whatsNew 等）按版本设置。
• 应用信息字段（name、subtitle、隐私政策 URL/文本）为应用级字段，并使用 --type app-info。
• 如果只有名称（应用名称、版本字符串）并需要确定性地获取 ID，请使用 asc-id-resolver。

第 2 步：下载源语言内容

# Download version localizations to local .strings files
# (description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl, ...)
asc localizations download --version "VERSION_ID" --path "./localizations"

# Download app-info localizations to local .strings files
# (name, subtitle, privacyPolicyUrl, privacyChoicesUrl, privacyPolicyText, ...)
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 的文件。如果无法下载，请逐个读取字段：

# List version localizations to see existing locales and their content
asc localizations list --version "VERSION_ID" --output table

第 3 步：使用 LLM 翻译

针对每个目标语言区域，翻译源文本。请遵循以下规则：

翻译指南

• 语气与语体：始终使用正式、礼貌的语言。在语言区分正式和非正式“您”时，请使用正式形式（俄语：「вы」、德语：「Sie」、法语：「vous」、西班牙语：「usted」、荷兰语：「u」、意大利语：「Lei」、葡萄牙语：正式的「você」等）。App Store 描述属于专业营销文案，切勿使用随意或非正式语体。
• description：自然翻译，并根据当地市场调整语气。保留格式（换行、项目符号、表情符号）。长度不得超过 4000 个字符。
• keywords：不要直译。调研该语言区域的用户会搜索哪些词。使用逗号分隔，总长度最多 100 个字符。不得重复，也不得包含应用名称（Apple 会自动添加）。
• whatsNew：翻译版本说明。保持简洁。长度不得超过 4000 个字符。
• promotionalText：翻译营销宣传语。长度最多 170 个字符。此字段无需发布新版本即可更新。
• subtitle：翻译或调整宣传短语。长度最多 30 个字符，限制很严格，可能需要灵活改写。
• name：通常保留原应用名称。仅在用户明确要求时才翻译。长度最多 30 个字符。

LLM 翻译提示词模板

针对每个目标语言区域，使用以下方法：

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.
- Use formal, polite language and formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted, Dutch: u, etc.). App Store copy is professional marketing — never use informal register.
- 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}

第 4 步：上传译文

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

在相应目录中为每个语言区域创建一个 .strings 文件。

版本本地化示例：

// nl-NL.strings
"description" = "Je app-beschrijving hier";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "Bugfixes en verbeteringen";
"promotionalText" = "Leer de tafels van vermenigvuldiging!";

然后上传版本本地化内容：

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

应用信息本地化示例：

// nl-NL.strings
"subtitle" = "Leer tafels spelenderwijs";

然后上传应用信息本地化内容：

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

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

# Version localization fields (fine control).
# Prefer passing the explicit version ID for determinism.
asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "nl-NL" \
  --description "Je beschrijving..." \
  --keywords "wiskunde,kinderen,tafels" \
  --whats-new "Bugfixes en verbeteringen"

应用级字段：

# Subtitle/name (app-info localization) is managed via app-info localizations.
# Use the app-info localization .strings + upload flow; there is no app-infos localizations command.
#
# 1) Edit: ./app-info-localizations/nl-NL.strings
# "subtitle" = "Leer tafels spelenderwijs";
#
# 2) Upload:
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"

第 5 步：验证

# Check all locales are present
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

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

字段	限制
名称	30
副标题	30
关键词	100（逗号分隔）
描述	4000
更新内容	4000
推广文本	170

务必在上传前验证译文是否符合限制。文本被截断会显得不专业。如果译文超出限制，请缩短内容，不要在句子中间截断。

完整示例：为 Roxy Math 添加 nl-NL 和 ru

# 1) Resolve IDs deterministically (do not auto-pick the "first" row)
# If you only have names, use asc-id-resolver skill.
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 apps info list --app "$APP_ID" --output table
APP_INFO_ID="APP_INFO_ID_HERE"

# 2) Download English source (or your chosen source locale)
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)

# 4) Write nl-NL.strings and ru.strings to:
#    - ./localizations/ (version localization fields)
#    - ./app-info-localizations/ (subtitle/name/privacy fields)

# 5) Upload all
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
asc localizations list --version "$VERSION_ID" --output table
asc localizations list --app "$APP_ID" --type app-info --app-info "$APP_INFO_ID" --output table

Agent 行为

1. 始终先阅读源语言内容——不要凭记忆或猜测翻译。
2. 先检查现有本地化内容——除非用户要求更新，否则不要覆盖现有译文。
3. 版本与 app-info 不同——版本字段位于 --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. 更新现有本地化内容时——先下载当前内容，展示变更差异并获得批准，然后再上传。

备注

• 版本本地化内容与特定版本关联。如果版本不存在，请先创建版本。
• promotionalText 可随时更新，无需提交新版本。
• whatsNew 仅适用于更新，不适用于首个版本。
• 如果只有 App 或版本名称而没有 ID，请使用 asc-id-resolver 技能。
• 对于非翻译类元数据操作，请使用 asc-metadata-sync 技能。
• 对于订阅/IAP 显示名称本地化，请改用 asc-subscription-localization 技能。