用 LLM 翻译并同步 App Store…

当需要把 App Store 上架信息本地化到多种语言，或向 App Store Connect 添加新语言时，用 asc CLI 拉取源语言元数据、LLM 翻译后再上传。

适用场景

解决思路

1. 先用 `--help` 确认当前 `asc` 版本支持的参数：`asc localizations --help`、`asc localizations download --help`、`asc localizations upload --help`、`asc apps info edit --help`。
2. 优先使用显式长参数（`--app`、`--version`、`--version-id`、`--type`、`--app-info`）。
3. 输出默认是 TTY 感知的：交互终端输出表格，CI 或非交互环境输出 JSON；格式重要时显式指定 `--output`。
4. 优先使用确定性的基于 ID 的操作，除非用户明确同意，不要用 `head -1` 去“选第一行”。
5. 前置条件：已配置认证（`asc auth login` 或 `ASC_*` 环境变量）；知道 app ID（用 `asc apps list` 查找）；至少有一个 locale（通常是 en-US）在 App Store Connect 中已有元数据。
6. 支持的 locale 列表：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。
7. 区分两类元数据：Version Localizations（按版本，字段：description、keywords、whatsNew、supportUrl、marketingUrl、promotionalText）与 App Info Localizations（应用级持久，字段：name、subtitle、privacyPolicyUrl、privacyChoicesUrl、privacyPolicyText）。
8. Step 1 解析 ID：用 `asc apps list --output table` 找 app ID；用 `asc versions list --app "APP_ID" --state READY_FOR_DISTRIBUTION --output table` 或 `--state PREPARE_FOR_SUBMISSION` 找最新版本 ID；用 `asc apps info list --app "APP_ID" --output table` 找 app info ID。
9. 注意：version-localization 字段是按版本的；app-info 字段（name、subtitle、隐私 URL/文本）是应用级的，使用 `--type app-info`。
10. 如果只有名称（app 名、版本字符串）而需要确定性地拿到 ID，使用 `asc-id-resolver`。
11. Step 2 下载源 locale：`asc localizations download --version "VERSION_ID" --path "./localizations"` 下载版本本地化到本地 .strings 文件。
12. `asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"` 下载 app-info 本地化到本地 .strings 文件。
13. 这会生成如 `./localizations/en-US.strings` 和 `./app-info-localizations/en-US.strings` 的文件；若无法下载，用 `asc localizations list --version "VERSION_ID" --output table` 逐个读取字段。
14. Step 3 用 LLM 翻译每个目标 locale，遵循翻译规则：语气与语域始终使用正式、礼貌的语言，在区分正式/非正式“你”的语言中使用正式形式（俄语 «вы»、德语 «Sie»、法语 «vous»、西语 «usted»、荷兰语 «u»、意大利语 «Lei»、葡语正式 «você» 等）；App Store 描述是专业营销文案，绝不使用随意或非正式语域。
15. description：自然翻译，按当地市场调整语气，保留格式（换行、项目符号、emoji），不超过 4000 字符。
16. keywords：不要直译，研究该 locale 用户会搜索的词；逗号分隔，总计最多 100 字符；不重复，不含 app 名（Apple 会自动添加）。
17. whatsNew：翻译发布说明，保持简洁，最多 4000 字符。
18. promotionalText：翻译营销钩子，最多 170 字符，可在不发布新版本的情况下更新。
19. subtitle：翻译或改写标语，最多 30 字符——非常紧张，可能需要创意改编。
20. name：通常保留原始 app 名，仅在用户明确要求时翻译，最多 30 字符。
21. 使用 LLM 翻译提示模板：对每个目标 locale，把源 locale 的 description、keywords、whatsNew、promotionalText、name、subtitle 填入模板，并附带上述规则（含正式语域要求、尊重文化语境，例如 ja、de-DE 等正式市场可能需要调整英文的俏皮语气）。
22. Step 4 上传翻译，方式 A（通过 .strings 文件批量）：为每个 locale 在对应目录创建 .strings 文件，例如 `// nl-NL.strings` 中写 `"description" = "...";`、`"keywords" = "...";`、`"whatsNew" = "...";`、`"promotionalText" = "...";`。
23. 然后上传版本本地化：`asc localizations upload --version "VERSION_ID" --path "./localizations"`。
24. app-info 本地化示例：`// nl-NL.strings` 中写 `"subtitle" = "...";`，然后 `asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"`。
25. 方式 B（单条命令精细控制）：`asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "nl-NL" --description "..." --keywords "..." --whats-new "..."`，优先传显式 version ID 以保证确定性。
26. app 级字段（subtitle/name）通过 app-info 本地化 .strings + 上传流程管理，没有 app-infos localizations 命令。
27. Step 5 验证：`asc localizations list --version "VERSION_ID" --output table` 检查所有 locale 是否齐全；`asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table` 检查 app info 本地化。
28. 字符限制（上传前必须强制检查）：Name 30、Subtitle 30、Keywords 100（逗号分隔）、Description 4000、What's New 4000、Promotional Text 170；始终验证译文在限制内，超限就缩短，不要从句子中间截断。
29. 完整流程示例（为 Roxy Math 添加 nl-NL 和 ru）：解析 ID（`asc apps list --output table`、`asc versions list --app "$APP_ID" --state PREPARE_FOR_SUBMISSION --output table`、`asc apps info list --app "$APP_ID" --output table`）；下载英文源；读取 en-US.strings 并翻译为 nl-NL 和 ru；把 nl-NL.strings 和 ru.strings 写入 `./localizations/` 和 `./app-info-localizations/`；上传；验证。
30. Agent 行为：始终先读取源 locale，绝不凭记忆或假设翻译。
31. 先检查已有本地化，除非用户要求更新，不要覆盖已有翻译。
32. 区分 version 与 app-info：version 字段在 `--version "VERSION_ID"` 下；subtitle/name/隐私在 `--app ... --type app-info` 下。
33. 优先使用确定性 ID，除非明确要求，不要用 `head -1` 选择 ID；用 `--output table` 选择或 `asc-id-resolver`。
34. 上传前验证字符限制，逐字段计数字符；超限则重新翻译得更短。
35. keywords 特殊：不要直译，研究适合该 locale 的搜索词，像用该语言在 App Store 搜索的用户一样思考。
36. 上传前向用户展示译文，用字段 × locale 的汇总表请求批准，未经确认不要推送。
37. 翻译多种语言时一次处理一个 locale，便于审查和发现错误。
38. 若某 locale 上传失败，记录错误，继续其他 locale，最后统一报告所有失败。
39. 更新已有本地化时：先下载当前内容，展示将要变更的 diff，获得批准后再上传。
40. 注意：version localizations 绑定到特定版本，若版本不存在需先创建；promotionalText 可随时更新而无需新版本提交；whatsNew 仅对更新有意义，不适用于首个版本；只有 app/version 名称而无 ID 时用 `asc-id-resolver`；非翻译类元数据操作用 `asc-metadata-sync`；订阅/IAP 显示名称本地化用 `asc-subscription-localization`。

适用边界 · 注意事项

• 未配置 asc 认证（`asc auth login` 或 `ASC_*` 环境变量）时无法使用。
• App Store Connect 中没有任何 locale 已有元数据时，没有可翻译的源内容。
• 需要处理订阅/IAP 显示名称本地化时应改用 `asc-subscription-localization`；非翻译类元数据操作应改用 `asc-metadata-sync`。