asc localize metadata
使用此技能來拉取英文(或任何來源語言)的 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查詢) - 至少有一個語言(通常是 en-US)已在 App Store Connect 中設定中繼資料
支援的語言
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" = "你的應用程式描述(荷蘭文)";
"keywords" = "wiskunde,kinderen,tafels,leren";
"whatsNew" = "錯誤修正與改進";
"promotionalText" = "學習乘法表!";
然後上傳版本本地化:
asc localizations upload --version "VERSION_ID" --path "./localizations"
應用程式資訊本地化範例:
// nl-NL.strings
"subtitle" = "邊玩邊學乘法表";
然後上傳應用程式資訊本地化:
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 "你的描述(荷蘭文)..." \
--keywords "wiskunde,kinderen,tafels" \
--whats-new "錯誤修正與改進"
對於應用程式層級的欄位:
# 副標題/名稱(應用程式資訊本地化)透過應用程式資訊本地化管理。
# 使用應用程式資訊本地化的 .strings 檔案加上上傳流程(沒有 `asc app-infos localizations ...` 指令)。
#
# 1) 編輯:./app-info-localizations/nl-NL.strings
# "subtitle" = "邊玩邊學乘法表";
#
# 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技能。