asc-localize-metadata

asc localize metadata

使用此 Skill 提取英文（或任意源语言）的 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）。
• 默认输出格式为 JSON；仅在人工核验步骤中使用 --output table。
• 推荐使用确定性的 ID 进行操作。除非用户明确要求，否则切勿直接通过 head -1 硬取第一行数据。

前置条件

• 已配置身份认证（运行 asc auth login 或设置 ASC_* 环境变量）
• 已明确应用 ID（App ID，可通过 asc apps list 查看）
• App Store Connect 中至少有一个语言版本（通常为 en-US）已填入元数据

支持的语言区域 (Locales)

用于版本与 App 信息本地化的 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

两类元数据

版本本地化信息 (Version Localizations，随版本更新)

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

App 信息本地化 (App Info Localizations，应用层级，持久生效)

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

工作流程

步骤 1：解析并确定 ID

# 查询 App ID
asc apps list --output table

# 查询最新版本 ID
asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table
# 或查询可编辑状态的版本：
asc versions list --app "APP_ID" --state PREPARE_FOR_SUBMISSION --output table

# 查询 App Info ID（用于应用层级字段，如应用名称/副标题）
asc apps info list --app "APP_ID" --output table

说明：

• 版本本地化字段（description、keywords、whatsNew 等）是跟具体版本绑定的。
• App 信息字段（name、subtitle、隐私政策链接/文本）属于应用层级，需配合 --type app-info 使用。
• 如果手头只有名称（如应用名、版本号字符串）且需要精准解析 ID，请使用 asc-id-resolver Skill。

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

# 将版本本地化字段下载到本地 .strings 文件中
# (description, keywords, whatsNew, promotionalText, supportUrl, marketingUrl 等)
asc localizations download --version "VERSION_ID" --path "./localizations"

# 将 App 信息本地化字段下载到本地 .strings 文件中
# (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 的文件。若无法直接下载文件，也可单独读取各字段：

# 查看版本本地化列表，确认现有语言及其内容
asc localizations list --version "VERSION_ID" --output table

步骤 3：使用 LLM 进行翻译

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

翻译指南

• 语气与语调：务必使用正式、礼貌的措辞。对于区分尊称的语言（如俄语 «вы»、德语 «Sie»、法语 «vous»、西班牙语 «usted»、荷兰语 «u»、意大利语 «Lei»、葡萄牙语 «você» 等），必须使用尊称。App Store 应用描述属于专业的营销文案，绝不可使用随意或口语化的表达。
• description（应用描述）：翻译需自然流畅，契合本地市场语境。保留原始排版格式（换行、列表符号、Emoji 等）。字数严格限制在 4000 字符以内。
• keywords（关键词）：切勿直译！需研究目标语言用户在 App Store 里的实际搜索习惯。用逗号分隔，总长不超过 100 字符。不要包含重复词，也不要写应用名称（苹果系统会自动包含应用名）。
• whatsNew（更新说明）：自然翻译更新日志，保持精炼。不超过 4000 字符。
• promotionalText（宣传文本）：翻译营销标语/宣传卖点。不超过 170 字符。该字段可在无需发布新版本的情况下随时更新。
• subtitle（副标题）：翻译或适配一句话介绍。不超过 30 字符 — 空间非常有限，可能需要进行意译或创意适配。
• name（应用名称）：通常保留原始应用名。仅在用户明确要求时才进行翻译。不超过 30 字符。

LLM 翻译 Prompt 模板

对每个目标语言区域，推荐使用以下 Prompt 结构：

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"

App 信息本地化示例：

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

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

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

方式 B：通过独立命令精准控制

# 版本本地化字段（精细化控制）。
# 建议显式传入 version ID 以确保确定性。
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"

对于应用层级字段：

# 副标题/应用名（App 信息本地化）通过 app-info 本地化功能管理。
# 请使用 App 信息本地化的 .strings + 上传流程；asc 没有单独的 app-infos localizations 命令。
#
# 1) 编辑：./app-info-localizations/nl-NL.strings
# "subtitle" = "Leer tafels spelenderwijs";
#
# 2) 上传：
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"

步骤 5：核验确认

# 确认所有目标语言均已添加
asc localizations list --version "VERSION_ID" --output table

# 核验 App 信息本地化列表
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table

字符数限制（上传前必须严格校验！）

字段名称	限制长度
Name（应用名称）	30 字符
Subtitle（副标题）	30 字符
Keywords（关键词）	100 字符（英文逗号分隔）
Description（应用描述）	4000 字符
What's New（更新说明）	4000 字符
Promotional Text（宣传文本）	170 字符

在上传之前，务必确认翻译后的文本未超出上述字符限制。文本若被截断会显得非常不专业。如果翻译超长，请进行删减或精简润色 — 切勿在句中硬生生截断。

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

# 1) 确定性解析 ID（避免自动选取“第一行”数据）
# 若只有应用/版本名称，请使用 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) 下载英文源数据（或你指定的源语言版本）
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) 读取 en-US.strings，将其翻译为 nl-NL 与 ru（LLM 步骤）

# 4) 将 nl-NL.strings 和 ru.strings 分别写入到：
#    - ./localizations/ (版本本地化字段)
#    - ./app-info-localizations/ (副标题/应用名/隐私政策字段)

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

# 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

Agent 行为规范

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. 更新已有本地化内容时 — 先下载当前内容，显示修改的 Diff 变化，获得用户确认后再进行上传。

注意事项

• 版本本地化信息是与特定版本绑定的。如果版本尚不存在，需先创建该版本。
• promotionalText 宣传文本可随时更新，无需提交新版本。
• whatsNew 更新说明仅适用于版本更新，首发版本无需填写。
• 若手头只有应用/版本名称而无 ID，请配合使用 asc-id-resolver Skill。
• 对于非翻译类的元数据同步操作，请使用 asc-metadata-sync Skill。
• 若需对订阅/应用内购 (IAP) 显示名称进行本地化，请使用 asc-subscription-localization Skill。