gplay-subscription-localization

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

このスキルを使うと、Google Play がサポートするすべてのロケールについて、サブスクリプションの表示名、説明、特典を一括作成または一括更新できます。Play Console で言語ごとに編集する手間のかかる作業をなくせます。

前提条件

• 認証が設定されていること（gplay auth login または GPLAY_SERVICE_ACCOUNT 環境変数）。
• パッケージ名がわかっていること（--package または GPLAY_PACKAGE）。
• サブスクリプション商品がすでに作成されていること（最初に gplay subscriptions create を使用してください）。
• サービスアカウントに「アプリの編集と管理」権限があること。

Google Play がサポートするロケール

Google Play のサブスクリプション掲載情報でサポートされているロケールは次のとおりです。

af, am, ar, hy-AM, az-AZ, eu-ES, be, bn-BD, bg, my-MM, ca,
zh-HK, zh-CN, zh-TW, hr, cs-CZ, da-DK, nl-NL, en-AU, en-CA,
en-GB, en-IN, en-SG, en-US, en-ZA, et, fil, fi-FI, fr-CA,
fr-FR, gl-ES, ka-GE, de-DE, el-GR, gu, he-IL, hi-IN, hu-HU,
is-IS, id, it-IT, ja-JP, kn-IN, kk, km-KH, ko-KR, ky-KG,
lo-LA, lv, lt, mk-MK, ms, ms-MY, ml-IN, mr-IN, mn-MN, ne-NP,
no-NO, fa, pl-PL, pt-BR, pt-PT, pa, ro, rm, ru-RU, sr, si-LK,
sk, sl, es-419, es-ES, es-US, sw, sv-SE, ta-IN, te-IN, th,
tr-TR, uk, ur, vi, zu

アプリがすでにサポートしているロケールを確認します。

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
gplay listings list --package com.example.app --edit $EDIT_ID --output table

Google Play のサブスクリプション構造

Google Play のサブスクリプションは階層構造になっています。

• サブスクリプション：商品そのもの（例：「プレミアム」）
  • 掲載情報：ロケールごとの表示名、説明、特典
  • 基本プラン：料金プラン（例：「月額」「年額」）
  • 特典：基本プランのプロモーション価格（無料試用、初回価格）

掲載情報はサブスクリプションのレベルで設定され、その配下にあるすべての基本プランに適用されます。

ワークフロー：サブスクリプションを一括ローカライズする

1. 既存のサブスクリプションを一覧表示する

gplay subscriptions list --package com.example.app --paginate --output table

2. 現在のサブスクリプションの詳細を取得する

gplay subscriptions get \
  --package com.example.app \
  --product-id premium_monthly \
  --output json --pretty

レスポンスには、ロケールをキーとする listings オブジェクトが含まれます。

{
  "productId": "premium_monthly",
  "listings": {
    "en-US": {
      "title": "Premium Monthly",
      "benefits": ["Unlimited access", "No ads"],
      "description": "Get premium access to all features"
    }
  }
}

3. 複数ロケールの掲載情報 JSON を準備する

対象となるすべてのロケールの掲載情報を含む JSON ファイルを作成します。

subscription-listings.json：

{
  "listings": {
    "en-US": {
      "title": "Premium Monthly",
      "benefits": ["Unlimited access", "No ads", "Priority support"],
      "description": "Get premium access to all features every month."
    },
    "de-DE": {
      "title": "Premium Monatlich",
      "benefits": ["Unbegrenzter Zugang", "Keine Werbung", "Prioritäts-Support"],
      "description": "Erhalten Sie jeden Monat Premium-Zugang zu allen Funktionen."
    },
    "fr-FR": {
      "title": "Premium Mensuel",
      "benefits": ["Accès illimité", "Sans publicité", "Support prioritaire"],
      "description": "Accédez à toutes les fonctionnalités premium chaque mois."
    },
    "es-ES": {
      "title": "Premium Mensual",
      "benefits": ["Acceso ilimitado", "Sin anuncios", "Soporte prioritario"],
      "description": "Obtén acceso premium a todas las funciones cada mes."
    },
    "ja-JP": {
      "title": "プレミアム月額",
      "benefits": ["無制限アクセス", "広告なし", "優先サポート"],
      "description": "毎月すべての機能にプレミアムアクセスできます。"
    },
    "ko-KR": {
      "title": "프리미엄 월간",
      "benefits": ["무제한 액세스", "광고 없음", "우선 지원"],
      "description": "매달 모든 기능에 프리미엄 액세스를 받으세요."
    },
    "pt-BR": {
      "title": "Premium Mensal",
      "benefits": ["Acesso ilimitado", "Sem anúncios", "Suporte prioritário"],
      "description": "Tenha acesso premium a todos os recursos todos os meses."
    },
    "zh-CN": {
      "title": "高级月度订阅",
      "benefits": ["无限访问", "无广告", "优先支持"],
      "description": "每月获得所有功能的高级访问权限。"
    }
  }
}

4. すべての掲載情報でサブスクリプションを更新する

gplay subscriptions update \
  --package com.example.app \
  --product-id premium_monthly \
  --json @subscription-listings.json \
  --update-mask listings

--update-mask listings を指定すると、掲載情報フィールドのみが変更され、基本プランやその他の設定は変更されません。

5. 確認する

gplay subscriptions get \
  --package com.example.app \
  --product-id premium_monthly \
  --output json --pretty

すべてのロケールが listings オブジェクトに含まれていることを確認します。

ワークフロー：エクスポート、翻訳、インポート

1. 現在のサブスクリプションデータをエクスポートする

gplay subscriptions get \
  --package com.example.app \
  --product-id premium_monthly \
  --output json --pretty > subscription-export.json

2. 翻訳対象の掲載情報を抽出する

jq を使って掲載情報を抽出します。

jq '.listings' subscription-export.json > listings-to-translate.json

3. 翻訳に出す

listings-to-translate.json を翻訳サービスまたはチームに送ります。構造は、ロケールごとのシンプルなキーと値のペアです。

4. 翻訳済みの掲載情報をマージする

翻訳を受け取ったら、更新用 JSON を作成します。

jq -n --slurpfile translations translated-listings.json \
  '{ listings: $translations[0] }' > subscription-update.json

5. 翻訳済みの掲載情報をインポートする

gplay subscriptions update \
  --package com.example.app \
  --product-id premium_monthly \
  --json @subscription-update.json \
  --update-mask listings

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

#!/bin/bash
# bulk-localize-subscriptions.sh

PACKAGE="com.example.app"
LISTINGS_FILE="subscription-listings.json"

# Get all subscription product IDs
PRODUCT_IDS=$(gplay subscriptions list \
  --package "$PACKAGE" \
  --paginate | jq -r '.[].productId')

for PRODUCT_ID in $PRODUCT_IDS; do
  echo "Updating listings for: $PRODUCT_ID"

  gplay subscriptions update \
    --package "$PACKAGE" \
    --product-id "$PRODUCT_ID" \
    --json "@$LISTINGS_FILE" \
    --update-mask listings

  echo "Done: $PRODUCT_ID"
done

echo "All subscriptions updated."

表示名が異なるサブスクリプションには、商品ごとの JSON ファイルを使用します。

for PRODUCT_ID in $PRODUCT_IDS; do
  LISTINGS_FILE="listings/${PRODUCT_ID}.json"
  if [ -f "$LISTINGS_FILE" ]; then
    gplay subscriptions update \
      --package "$PACKAGE" \
      --product-id "$PRODUCT_ID" \
      --json "@$LISTINGS_FILE" \
      --update-mask listings
  else
    echo "Warning: No listings file for $PRODUCT_ID, skipping."
  fi
done

ワークフロー：基本プランと特典を含めてサブスクリプションをローカライズする

新しいサブスクリプションを作成するときに、ローカライズ済みの掲載情報と基本プランを一度の呼び出しで設定するには、次のようにします。

gplay subscriptions create \
  --package com.example.app \
  --product-id premium_yearly \
  --json @full-subscription.json

full-subscription.json：

{
  "productId": "premium_yearly",
  "listings": {
    "en-US": {
      "title": "Premium Yearly",
      "benefits": ["Unlimited access", "No ads", "2 months free"],
      "description": "Save with annual premium access."
    },
    "de-DE": {
      "title": "Premium Jährlich",
      "benefits": ["Unbegrenzter Zugang", "Keine Werbung", "2 Monate gratis"],
      "description": "Sparen Sie mit jährlichem Premium-Zugang."
    },
    "fr-FR": {
      "title": "Premium Annuel",
      "benefits": ["Accès illimité", "Sans publicité", "2 mois offerts"],
      "description": "Économisez avec l'accès premium annuel."
    },
    "ja-JP": {
      "title": "プレミアム年間",
      "benefits": ["無制限アクセス", "広告なし", "2ヶ月無料"],
      "description": "年間プレミアムアクセスでお得に。"
    }
  },
  "basePlans": [
    {
      "basePlanId": "yearly",
      "state": "ACTIVE",
      "autoRenewingBasePlanType": {
        "billingPeriodDuration": "P1Y",
        "gracePeriodDuration": "P7D",
        "resubscribeState": "RESUBSCRIBE_STATE_ACTIVE",
        "prorationMode": "CHARGE_ON_NEXT_BILLING_DATE"
      },
      "regionalConfigs": [
        {
          "regionCode": "US",
          "price": {
            "currencyCode": "USD",
            "units": "49",
            "nanos": 990000000
          }
        }
      ]
    }
  ]
}

ワークフロー：特典タグをローカライズする

特典では、アプリ内での表示に使えるローカライズ済みの offerTags がサポートされています。

gplay offers update \
  --package com.example.app \
  --product-id premium_monthly \
  --base-plan-id monthly \
  --offer-id free_trial_7d \
  --json @offer-update.json

offer-update.json：

{
  "offerTags": [
    {"tag": "free-trial"},
    {"tag": "7-days"}
  ]
}

注：Google Play API では、特典タグはロケールに依存しません。アプリ内でのフィルタリングに使用する、デベロッパーが定義する識別子です。特典タグのユーザー向けテキストは Play Console ではなく、アプリのコードでローカライズしてください。

ロケールコードを検証する

アプリにストア掲載情報がすでに登録されているロケールを確認します。

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
gplay listings list --package com.example.app --edit $EDIT_ID --output table

ストア掲載情報があるすべてのロケールが一覧表示されます。サブスクリプションの掲載情報も、少なくとも同じロケールを網羅する必要があります。

特定の掲載情報がサポートするロケールの全一覧を確認するには、次のようにします。

gplay listings list --package com.example.app --edit $EDIT_ID \
  | jq -r '.[].language'

JSON テンプレート：最小構成の複数ロケール対応サブスクリプション

このテンプレートをコピーしてカスタマイズすると、すばやくローカライズできます。

{
  "listings": {
    "en-US": { "title": "TITLE_EN", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_EN" },
    "de-DE": { "title": "TITLE_DE", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_DE" },
    "fr-FR": { "title": "TITLE_FR", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_FR" },
    "es-ES": { "title": "TITLE_ES", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_ES" },
    "it-IT": { "title": "TITLE_IT", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_IT" },
    "ja-JP": { "title": "TITLE_JA", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_JA" },
    "ko-KR": { "title": "TITLE_KO", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_KO" },
    "pt-BR": { "title": "TITLE_PT_BR", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_PT_BR" },
    "ru-RU": { "title": "TITLE_RU", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_RU" },
    "zh-CN": { "title": "TITLE_ZH_CN", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_ZH_CN" },
    "zh-TW": { "title": "TITLE_ZH_TW", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_ZH_TW" },
    "ar": { "title": "TITLE_AR", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_AR" },
    "hi-IN": { "title": "TITLE_HI", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_HI" },
    "tr-TR": { "title": "TITLE_TR", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_TR" },
    "pl-PL": { "title": "TITLE_PL", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_PL" },
    "nl-NL": { "title": "TITLE_NL", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_NL" },
    "sv-SE": { "title": "TITLE_SV", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_SV" },
    "th": { "title": "TITLE_TH", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_TH" },
    "vi": { "title": "TITLE_VI", "benefits": ["BENEFIT_1", "BENEFIT_2"], "description": "DESC_VI" }
  }
}

エージェントの動作

• 変更を行う前に、既存のサブスクリプションと現在の各掲載内容を必ず一覧表示します。
• ローカライズされたメタデータのみを更新する場合は、ベースプランや価格を上書きしないように --update-mask listings を使用します。
• ユーザーが表示名を1つ指定した場合は、すべてのロケールで同じ名前を使用します。
• ユーザーがロケールごとの翻訳名を指定した場合は、それぞれのロケールに対応する名前を使用します。
• 特典または説明が指定されている場合は、それらを含めます。指定されていない場合は、JSON から省略します。
• 確認手順では --output table を使用し、ユーザーが目視で確認できるようにします。
• 中間の自動化手順では、デフォルトの JSON 出力を使用します。
• 一括更新後は、完全性を確認するために必ずサブスクリプションを取得します。
• 更新に失敗した場合は、プロダクト ID とエラーを記録して、残りのサブスクリプションの処理を続けます。すべての失敗は最後にまとめて報告します。
• コマンドを実行する前に、必ず --help で正確なフラグを確認します。

注意事項

• サブスクリプションの掲載内容は、サブスクリプションごとにアトミックに更新されます。1回の update 呼び出しで、すべてのロケールが一度に設定されます。
• App Store Connect とは異なり、Google Play ではロケールごとに個別の作成呼び出しを行う必要はありません。掲載内容は単一の JSON フィールドです。
• --update-mask フラグは重要です。このフラグを指定しないと、更新呼び出しによってベースプランや価格が上書きされる可能性があります。
• タイトルの最大文字数は55文字です。特典は最大4項目、説明は最大80文字です。
• すべてのサブスクリプションを取得するため、一覧表示コマンドでは --paginate を使用します。
• JSON 出力を人が読みやすい形式で確認する場合は、--pretty を使用します。
• 対象のコマンドで使用できるフラグを確認するには、必ず --help を使用します。