asc 本地化元数据 是做什么的?
使用此技能自动拉取英文(或任何源语言)的 App Store 元数据,通过大语言模型(LLM)翻译,并将译文推送回 App Store Connect,全程自动化。
命令发现与输出约定
- 始终通过
--help确认当前asc版本的标志:asc localizations --helpasc localizations download --helpasc localizations upload --helpasc apps info edit --help
- 优先使用完整的标志名称(
--app、--version、--version-id、--type、--app-info)。 - 默认输出为 JSON;仅在进行人工确认步骤时使用
--output table。 - 优先使用基于 ID 的确定性操作。除非用户明确同意,否则不要通过
head -1选择第一条记录。
前提条件
- 已配置认证(
asc auth login或设置ASC_*环境变量) - 已知您的应用 ID(通过
asc apps list查找) - App Store Connect 中至少有一个语言(通常为 en-US)已包含元数据
支持的语言
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
两种元数据类型
版本本地化(按发布版本)
字段:description、keywords、whatsNew、supportUrl、marketingUrl、promotionalText
应用信息本地化(应用级别,持久保留)
字段:name、subtitle、privacyPolicyUrl、privacyChoicesUrl、privacyPolicyText
工作流程
第 1 步:解析 ID
# 查找应用 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
# 查找应用信息 ID(用于应用级别的字段,如名称、副标题)
asc apps info list --app "APP_ID" --output table
注意事项:
- 版本本地化字段(description、keywords、whatsNew 等)按版本关联。
- 应用信息字段(name、subtitle、隐私 URL/文本)为应用级别,使用
--type app-info。 - 如果您只有名称(应用名、版本字符串)而需要 ID,请使用
asc-id-resolver技能进行确定性解析。
第 2 步:下载源语言
# 下载版本本地化到本地的 .strings 文件
# (description、keywords、whatsNew、promotionalText、supportUrl、marketingUrl 等)
asc localizations download --version "VERSION_ID" --path "./localizations"
# 下载应用信息本地化到本地的 .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:自然翻译,根据当地市场调整语气。保留格式(换行、项目符号、表情符号)。不超过 4000 字符。
- keywords:不要逐字翻译。研究该语言用户在 App Store 中会搜索什么。以逗号分隔,总共最多 100 字符。不要重复,不要包含应用名称(Apple 会自动添加)。
- whatsNew:翻译版本发布说明。保持简洁。最多 4000 字符。
- promotionalText:翻译营销宣传语。最多 170 字符。此字段可在不发布新版本的情况下更新。
- subtitle:翻译或改编副标题。最多 30 字符——这个限制非常严格,可能需要创造性地改编。
- name:通常保留原应用名称。仅在用户明确要求时才翻译。最多 30 字符。
LLM 翻译提示模板
对于每个目标语言,使用以下方法:
将以下 App Store 元数据从 {source_locale} 翻译为 {target_locale}。
规则:
- description:自然流畅的翻译。保留格式(换行、项目符号、表情符号)。最多 4000 字符。
- keywords:不要逐字翻译。选择本地用户会在 App Store 中搜索的关键词。以逗号分隔,总共最多 100 字符。不要包含应用名称。
- whatsNew:自然翻译版本发布说明。最多 4000 字符。
- promotionalText:翻译营销宣传语。最多 170 字符。
- subtitle:创造性地改编以适应最多 30 字符的限制。
- name:除非明确要求翻译,否则保留原应用名称。最多 30 字符。
- 使用正式、礼貌的语言和正式的“您”形式(俄语:вы,德语:Sie,法语:vous,西班牙语:usted,荷兰语:u 等)。App Store 文案是专业的营销内容——切勿使用非正式语域。
- 尊重文化背景。英语中俏皮的语气可能需要在正式市场(如 ja,de-DE)进行调整。
源语言 ({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:通过单个命令(精细控制)
# 版本本地化字段(精细控制)。
# 优先传入明确的版本 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"
对于应用级别字段:
# 副标题/名称(应用信息本地化)通过应用信息本地化管理。
# 使用应用信息本地化的 .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
# 检查应用信息本地化
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 技能。
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
智能体行为指南
- 始终从读取源语言开始——不要凭借记忆或假设进行翻译。
- 先检查现有本地化——除非用户要求更新,否则不要覆盖已有的翻译。
- 版本与应用信息是不同的——版本字段使用
--version "VERSION_ID";副标题/名称/隐私字段使用--app ... --type app-info。 - 优先使用确定性 ID——除非明确要求,否则不要通过
head -1选择 ID;使用--output table进行选择或使用asc-id-resolver。 - 上传前验证字符数限制,检查每个字段的字符数。如果超限,重新翻译得更短。
- 关键词是特殊的——不要逐字翻译。研究适合当地语言的搜索词。像使用该语言在 App Store 中搜索的用户一样思考。
- 在上传前向用户展示翻译内容——要提供一个所有字段 × 语言的摘要表格以供批准。未经确认不要推送。
- 如果翻译多种语言,一次处理一个语言——更容易审查和发现错误。
- 如果某个语言上传失败,记录错误,继续处理其他语言,最后报告所有失败信息。
- 对于更新现有本地化——下载当前内容,显示将要更改的差异,获得批准,然后上传。
注意事项
- 版本本地化与特定版本绑定。如果版本尚不存在,请先创建版本。
promotionalText可以随时更新,无需提交新版本。whatsNew仅适用于更新,不适用于第一个版本。- 如果您只有应用/版本名称而没有 ID,请使用
asc-id-resolver技能。 - 对于非翻译的元数据操作,请使用
asc-metadata-sync技能。 - 对于订阅/IAP 显示名称本地化,请改用
asc-subscription-localization技能。