asc-subscription-localization

asc 訂閱項目本地化

使用此 Skill 可跨所有 App Store Connect 語系批次建立或更新訂閱項目、訂閱群組及應用程式內購買（IAP）的顯示名稱，以及在支援情況下的說明文字。這能免去在 App Store Connect 中手動逐一切換各個語言以設定相同顯示名稱的繁瑣流程。

前置條件

• Auth 已完成設定（執行 asc auth login 或設定 ASC_* 環境變數）。
• 已知曉 App ID（ASC_APP_ID 或 --app）。
• 訂閱群組與訂閱項目已建立完畢。

先選擇 API 作用域

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

• 所有新的本地化工作請一律使用 asc ... versions localizations ... 命令。
• 請勿使用以產品（product-scoped）或群組（group-scoped）為作用域的 v1 本地化命令。API 4.4.1 已廢棄這些資源，CLI 目前針對相容命令會發出遷移警告。
• 切勿將產品 ID、訂閱 ID 或群組 ID 傳給限定版本的命令（version-scoped command）。

在進行本地化之前，先解析或建立對應的版本：

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 代表直接複用該 version ID；超過 1 個匹配時則必須停止，要求指定明確的 version 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 狀態的唯一版本；僅在 0 匹配時才進行建立，若存在多個匹配則應停止並要求提供明確的 ID。由於在線上環境刪除父層資源時不會級聯刪除（cascade delete）其 IAP 或訂閱項目版本，因此請勿假設刪除父層資源會清空因測試而建立的版本。

支援的 App Store 語系

以下是 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

更新操作能明確區分忽略值（omitted values）、非空字串以及 JSON 的 null：

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

請勿同時傳入數值 Flag 與其對應的 --clear-name 或 --clear-description Flag。雖然 4.4.1 的 Schema 允許 JSON null，但 Apple 線上服務目前針對訂閱項目的版本本地化拒絕空字串 --description 及 --clear-description，因為說明欄位至少需包含一個字元。

因此，在建立缺少的訂閱項目版本本地化時，必須提供非空的說明文字。如果執行任務時僅有顯示名稱，可以更新既有本地化設定的名稱；但在使用者提供特定語系或共用的非空預設說明（fallback description）之前，切勿建立缺少的語系。

工作流程：批次本地化訂閱群組版本（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）屬於單獨且需明確選擇（opt-in）的操作。在確認使用者確實想要移除既有的自訂 App 名稱後，執行：

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

請勿在標準的批次本地化工作流程中加入 --clear-name 或 --clear-custom-app-name。只有在明確需要設定為 JSON null 時才使用這兩個 Flag；忽略 Flag 則會保持該屬性不變。

工作流程：批次本地化 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 version）。
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 資源（version-scoped v2 resources）。
• 務必將版本 ID 與產品 ID、訂閱 ID 及群組 ID 分開處理。
• 建立前務必先列出既有的本地化設定，以避免重複建立導致錯誤。
• 若語系缺失則建立；若既有數值不同，則更新解析出的本地化 ID；若既有數值已符合，則不執行任何動作。
• 當使用者僅提供單一顯示名稱時，於所有語系皆套用該名稱（全區使用相同名稱）。
• 當使用者針對各語系提供翻譯名稱時，依各語系套用對應名稱。
• 針對訂閱項目與 IAP 版本的本地化，每次建立時皆必須傳入非空的 --description。若使用者僅提供顯示名稱，請依解析出的 ID 更新既有本地化設定、跳過缺少的語系建立，並在建立前要求使用者提供各語系的說明或單一非空的預設說明（fallback description）。
• 更新既有的訂閱項目或 IAP 版本本地化時，除非使用者提供了新的非空數值，否則請忽略 --description；切勿自行推導空值或將其清除。
• 訂閱群組版本的本地化不包含說明欄位。正常建立或更新其名稱即可，僅在使用者有提供時才傳入 --custom-app-name。
• 在驗證步驟中使用 --output table，以便使用者進行視覺確認。
• 在中間自動化步驟中明確指定 --output json；預設輸出會根據 TTY 自動切換。
• 批次寫入後，務必執行列出命令（list）以驗證完整性。
• 針對包含大量訂閱項目的 App，按群組依序處理，以維持輸出的易讀性。
• 若某個語系的建立或更新呼叫失敗，請記錄該語系與錯誤訊息，並繼續處理其餘語系。待批次執行完畢後，再統一回報所有失敗項目，供使用者處理。

注意事項

• 訂閱項目的顯示名稱是使用者在訂閱管理頁面及購買對話框中看到的內容。
• 針對已存在的語系再次建立本地化會導致失敗；若需變更，請先列出項目並更新解析出的 ID。
• 目前沒有批次 API，每個語系都需要發送獨立的建立呼叫。
• 在列出命令中使用 --paginate，以確保回傳所有既有的本地化設定。
• 若手上只有 App 名稱而無 ID，請使用 asc-id-resolver Skill。