asc-subscription-localization

asc 訂閱項目在地化 (asc subscription localization)

使用此 Skill 可跨所有 App Store Connect 語系，批次建立或批次更新訂閱項目、訂閱群組以及 App 內購買（IAP）的顯示名稱與描述（若支援）。如此一來，便無需在 App Store Connect 介面中逐一切換各個語言手動設定相同的顯示名稱，免去繁瑣的操作流程。

前提條件

• 已配置身份驗證（asc auth login 或 ASC_* 環境變數）。
• 已知 App ID（ASC_APP_ID 或 --app）。
• 訂閱群組與訂閱項目已存在。

首先選擇 API 作用域（Scope）

API 4.4.1 為 IAP、訂閱項目與訂閱群組新增了獨立的版本（versions）。版本 ID（version ID）與產品 ID、訂閱 ID 或群組 ID 不同。

• 所有新的在地化作業請統一使用 asc ... versions localizations ...。
• 請勿使用以產品或群組為作用域的 v1 在地化指令。API 4.4.1 已棄用（deprecate）這些資源，CLI 目前也會針對相容性指令顯示遷移警告。
• 切勿將產品、訂閱或群組 ID 傳入以版本為作用域的指令中。

在進行在地化前，請先解析或建立版本：

asc iap versions list --iap-id "IAP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output table
asc subscriptions versions list --subscription-id "SUB_ID" --state PREPARE_FOR_SUBMISSION --paginate --output table
asc subscriptions groups versions list --group-id "GROUP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output table

請針對每個列表查詢結果獨立分支處理：若無匹配結果（0 個）表示需要新建；若有 1 個匹配結果表示直接重用該版本 ID；若多於 1 個則停止並要求指定明確的版本 ID。僅在「無匹配結果（0 個）」的分支下執行下列對應指令：

# 僅在 IAP 版本列表返回 0 個匹配結果時執行：
asc iap versions create --iap-id "IAP_ID" --output json
# 僅在訂閱項目版本列表返回 0 個匹配結果時執行：
asc subscriptions versions create --subscription-id "SUB_ID" --output json
# 僅在訂閱群組版本列表返回 0 個匹配結果時執行：
asc subscriptions groups versions create --group-id "GROUP_ID" --output json

這三類版本家族均未提供刪除版本的指令。請列出並重用唯一的 PREPARE_FOR_SUBMISSION 版本；僅在無匹配結果時才建立，若存在多個匹配結果則暫停並要求指定明確的 ID。刪除母項並不會連帶串接刪除（cascade）IAP 或訂閱版本，因此請勿假設刪除母項會自動清理測試時建立的版本。

支援的 App Store 語系（Locales）

以下為 App Store Connect 支援訂閱與 IAP 在地化的語系列表：

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

工作流程：批次在地化訂閱項目版本 (v2)

先列出既有的在地化資料，僅建立缺少的語系，最後進行驗證：

asc subscriptions versions localizations list --version-id "VERSION_ID" --paginate --output table
asc subscriptions versions localizations create --version-id "VERSION_ID" --locale "LOCALE" --name "Display Name" --description "Description"
asc subscriptions versions localizations list --version-id "VERSION_ID" --paginate --output table

更新指令會區分「省略參數」、「非空字串」與 JSON 的 null：

asc subscriptions versions localizations update --id "LOC_ID" --name "New Name" --description "Updated description"

請勿同時傳入數值旗標與其對應的 --clear-name 或 --clear-description 旗標。雖然 4.4.1 schema 允許 JSON null，但 Apple 線上服務目前拒絕訂閱版本在地化使用空白的 --description 或 --clear-description，因為描述內容必須至少包含一個字元。

因此，建立缺少的訂閱版本在地化資料時，必須提供非空的描述內容。如果僅提供顯示名稱，可以更新既有在地化紀錄的名稱，但在使用者提供非空的特定語系描述或共用預設（fallback）描述之前，切勿建立缺少的語系。

工作流程：批次在地化訂閱群組版本 (v2)

asc subscriptions groups versions localizations list --version-id "VERSION_ID" --paginate --output table
asc subscriptions groups versions localizations create --version-id "VERSION_ID" --locale "LOCALE" --name "Group Display Name" --custom-app-name "My App"
asc subscriptions groups versions localizations update --id "LOC_ID" --name "Updated Group Display Name" --custom-app-name "My App"
asc subscriptions groups versions localizations list --version-id "VERSION_ID" --paginate --output table

清除元資料（metadata）屬於獨立且需明確啟用的操作。在確認使用者確實想要移除既有的自訂 App 名稱後，執行：

asc subscriptions groups versions localizations update --id "LOC_ID" --clear-custom-app-name

請勿在標準的批次在地化流程中包含 --clear-name 或 --clear-custom-app-name。僅在刻意需要傳送 JSON null 時才使用這兩個旗標；若省略旗標，該屬性將保持不變。

工作流程：批次在地化 IAP 版本 (v2)

asc iap versions localizations list --version-id "VERSION_ID" --paginate --output table
asc iap versions localizations create --version-id "VERSION_ID" --locale "LOCALE" --name "Display Name" --description "Description"
asc iap versions localizations update --localization-id "LOC_ID" --description "Updated description"
asc iap versions localizations list --version-id "VERSION_ID" --paginate --output table

即便 4.4.1 schema 允許 JSON null，Apple 線上服務同樣會拒絕 IAP 版本在地化使用空白描述與 --clear-description。與訂閱項目相同，僅提供顯示名稱的執行流程可以更新既有的 IAP 在地化紀錄，但在取得非空描述之前，不得建立缺少的語系。

批次在地化 App 中的所有訂閱版本

針對包含多個訂閱群組與訂閱項目的完整 App：

# 1. 列出所有群組，並解析每個群組唯一的可變更（mutable）版本。
asc subscriptions groups list --app "APP_ID" --paginate --output json
asc subscriptions groups versions list --group-id "GROUP_ID" --state PREPARE_FOR_SUBMISSION --paginate --output json

# 2. 為各個群組版本進行在地化。
asc subscriptions groups versions localizations list --version-id "GROUP_VERSION_ID" --paginate --output json
asc subscriptions groups versions localizations create --version-id "GROUP_VERSION_ID" --locale "LOCALE" --name "Group Display Name"

# 3. 列出所有訂閱項目，並解析每個訂閱項目唯一的可變更版本。
asc subscriptions list --group-id "GROUP_ID" --paginate --output json
asc subscriptions versions list --subscription-id "SUB_ID" --state PREPARE_FOR_SUBMISSION --paginate --output json

# 4. 為各個訂閱項目版本進行在地化。
asc subscriptions versions localizations list --version-id "SUBSCRIPTION_VERSION_ID" --paginate --output json
asc subscriptions versions localizations create --version-id "SUBSCRIPTION_VERSION_ID" --locale "LOCALE" --name "Display Name" --description "Description"

對每個版本列表套用相同的「0 / 1 / 多」規則：匹配結果為 0 時建立新版本；有 1 個匹配時重用該版本；返回多個匹配時則暫停並要求指定明確的 ID。

Agent 行為準則

• 新的在地化作業僅能使用以版本為作用域的 v2 資源。
• 嚴格區分版本 ID 與產品 ID、訂閱 ID 及群組 ID。
• 務必先列出既有的在地化紀錄，避免發生重複建立的錯誤。
• 當語系缺失時予以建立；當既有數值不同時，依據解析出的在地化 ID 進行更新；若既有數值已完全一致則不作任何變更。
• 當使用者僅提供單一顯示名稱時，將其套用到所有語系（全語系使用相同名稱）。
• 當使用者針對各語系提供翻譯名稱時，依據各語系套用對應的名稱。
• 針對訂閱與 IAP 版本的在地化，每次執行新建時皆必須提供非空的 --description。若使用者僅提供顯示名稱，請透過解析出的 ID 更新既有在地化資料、跳過建立缺少的語系，並在建立前要求使用者提供各語系專屬的描述或一個非空的預設（fallback）描述。
• 在更新既有的訂閱或 IAP 版本在地化資料時，除非使用者提供了新的非空數值，否則請省略 --description；切勿自行推導空值或將其清除。
• 訂閱群組版本的在地化不包含描述欄位。請正常建立或更新其名稱，僅在使用者有提供該數值時才加上 --custom-app-name。
• 驗證步驟請使用 --output table，方便使用者直觀確認。
• 中間的自動化步驟請明確指定 --output json；預設輸出會依據 TTY 環境調整。
• 完成批次寫入後，務必執行 list 指令以驗證完整性。
• 若 App 包含大量訂閱項目，請按群組依序處理，以維持輸出的可讀性。
• 若某個語系的建立或更新呼叫失敗，請記錄該語系與錯誤訊息，並繼續處理其餘語系。待整批作業完成後，再統一回報所有失敗項目，以便使用者處理。

注意事項

• 訂閱項目的顯示名稱即為使用者在訂閱管理頁面與購買對話框中所看到的名稱。
• 為已存在的語系建立在地化紀錄將會失敗；需要修改時，請先執行 list 列出紀錄，再針對解析出的 ID 進行更新。
• 官方未提供批次處理的 API；每個語系都需要發起獨立的建立呼叫。
• 在 list 指令加上 --paginate，以確保能取得所有既有的在地化資料。
• 若手邊只有 App 名稱而無 ID，請搭配使用 asc-id-resolver Skill。