asc-subscription-localization

asc サブスクリプションのローカライズ

このスキルを使用すると、App Store Connect のすべてのロケールにわたって、サブスクリプション、サブスクリプショングループ、アプリ内課金の表示名と、対応している場合は説明を一括作成または一括更新できます。App Store Connect で言語ごとにクリックして同じ表示名を設定する、手間のかかる作業を省けます。

前提条件

• 認証が設定されていること（asc auth login または ASC_* 環境変数）。
• アプリ ID がわかっていること（ASC_APP_ID または --app）。
• サブスクリプショングループとサブスクリプションがすでに存在していること。

まず API のスコープを選択する

API 4.4.1 では、IAP、サブスクリプション、サブスクリプショングループに個別のバージョンが追加されます。バージョン ID は、製品 ID、サブスクリプション ID、グループ ID とは異なります。

• 新しいローカライズ作業には、すべて asc ... versions localizations ... を使用してください。
• 製品またはグループのスコープを持つ v1 ローカライズコマンドは使用しないでください。API 4.4.1 ではこれらのリソースが非推奨となり、CLI は互換性コマンドに対して移行に関する警告を出力するようになりました。
• バージョンのスコープを持つコマンドに、製品 ID、サブスクリプション ID、グループ 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 を再利用し、2 件以上の場合は処理を停止して明示的なバージョン ID の指定を求めます。以下の各コマンドは、一致が 0 件だった場合にのみ実行してください。

# If and only if the IAP version list returned zero matches:
asc iap versions create --iap-id "IAP_ID" --output json
# If and only if the subscription version list returned zero matches:
asc subscriptions versions create --subscription-id "SUB_ID" --output json
# If and only if the group version list returned zero matches:
asc subscriptions groups versions create --group-id "GROUP_ID" --output json

3 種類のバージョンのいずれにも、バージョンを削除するコマンドはありません。PREPARE_FOR_SUBMISSION のバージョンをリストし、1 件だけなら再利用してください。一致が 0 件の場合にのみ作成し、一致が複数の場合は明示的な ID が指定されるまで処理を停止してください。公開済みの親項目を削除しても、IAP やサブスクリプションのバージョンは連動して削除されません。そのため、テスト用に作成したバージョンが親項目の削除によってクリーンアップされると想定しないでください。

App Store でサポートされているロケール

以下は、サブスクリプションと IAP のローカライズで 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

1 つのファイルから複数のロケールをインポートする

一括書き込みでは、1 つの JSON ファイルで各ロケールとそのフィールドを対応付け、解決済みのバージョン ID にインポートします。インポートでは不足しているロケールを作成し、値が異なるフィールドのみを更新します。値のクリアや削除は行わず、ロケールごとの失敗を報告します。

asc subscriptions versions localizations import --version-id "VERSION_ID" --file "./localizations.json" --dry-run
asc subscriptions versions localizations import --version-id "VERSION_ID" --file "./localizations.json" --confirm

asc iap versions localizations import では、同じ name フィールドと description フィールドを使用します。asc subscriptions groups versions localizations import では、name と customAppName を使用します。新しく作成するサブスクリプションまたは IAP のロケールには、空でない description を指定してください。作成時のルールについては以下を参照してください。

ワークフロー：サブスクリプションのバージョンを一括ローカライズする（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 のスキーマでは JSON の null が許可されていますが、Apple のライブサービスは現在、説明に 1 文字以上が必要なため、サブスクリプションバージョンのローカライズに対する空の --description と --clear-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

メタデータのクリアは、明示的にオプトインして行う別の操作です。既存のカスタムアプリ名を削除することをユーザーに確認してから、次を実行します。

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

Apple の稼働中のサービスは、4.4.1 のスキーマで JSON の null が許可されていても、IAP バージョンのローカライズでは空の説明文と --clear-description も拒否します。サブスクリプションの場合と同様に、表示名のみを指定して実行すると既存の IAP ローカライズは更新できますが、空でない説明文を用意するまでは、存在しないロケールを作成してはいけません。

アプリ内のすべてのサブスクリプションバージョンを一括ローカライズする

複数のサブスクリプショングループとサブスクリプションがあるアプリ全体を対象にする場合：

# 1. List groups and resolve each group's unique 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. Localize each group version.
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. List subscriptions and resolve each subscription's unique mutable version.
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. Localize each subscription version.
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 が指定されていれば処理を中止します。

エージェントの動作

• 新しいローカライズ作業には、バージョンにスコープされた v2 リソースのみを使用します。
• バージョン ID と、プロダクト、サブスクリプション、グループの各 ID は分けて管理します。
• 重複作成エラーを避けるため、必ず最初に既存のローカライズを一覧表示します。
• 存在しないロケールは作成し、既存の値が異なる場合は解決済みのローカライズ ID を更新し、既存の値がすでに一致している場合は何もしません。
• ユーザーが表示名を 1 つ指定した場合は、すべてのロケールでその名前を使用します（どのロケールでも同じ名前）。
• ユーザーがロケールごとに翻訳済みの名前を指定した場合は、それぞれのロケールに対応する名前を使用します。
• サブスクリプションバージョンと IAP バージョンのローカライズを作成する場合は、すべての作成時に空でない --description が必要です。ユーザーが表示名のみを指定した場合は、解決済みの ID を使用して既存のローカライズを更新し、存在しないロケールの作成はスキップします。作成前に、ロケールごとの説明文、または空でない共通の代替説明文をユーザーに確認します。
• 既存のサブスクリプションバージョンまたは IAP バージョンのローカライズを更新する際は、ユーザーが空でない新しい値を指定していない限り、--description を省略します。空の値を推測したり、説明文を消去したりしてはいけません。
• サブスクリプショングループバージョンのローカライズには説明文フィールドがありません。ユーザーがその値を指定した場合に限り --custom-app-name を使用し、それ以外は名前を通常どおり作成または更新します。
• 検証手順には --output table を使用し、ユーザーが目で確認できるようにします。
• 中間の自動化手順では、明示的に --output json を指定します。出力の既定値は TTY を考慮します。
• 一括書き込みの後は、必ず一覧表示コマンドを実行して、すべて反映されたことを確認します。
• サブスクリプションが多いアプリでは、出力を読みやすく保つため、グループごとに順番に処理します。
• ロケールの作成または更新に失敗した場合は、ロケールとエラーを記録してから、残りのロケールの処理を続けます。一括処理の完了後、ユーザーが対処できるよう、すべての失敗をまとめて報告します。

注意事項

• サブスクリプションの表示名は、サブスクリプション管理シートや購入ダイアログに表示される名前です。
• すでに存在するロケールのローカライズを作成すると失敗します。最初に一覧表示し、変更が必要な場合は解決済みの ID を更新します。
• Apple には一括ローカライズ用のエンドポイントがありません。... localizations import はファイル全体を検証してから、ロケールごとに書き込みます。
• 既存のローカライズをすべて取得できるよう、一覧表示コマンドでは --paginate を使用します。
• ID ではなくアプリ名しかない場合は、asc-id-resolver スキルを使用します。