メッセージをローカライズする

このドキュメントでは、FCM ローカライズ フィールド（*_loc_key と *_loc_args）を使用して、Android と iOS でユーザーの言語設定に自動的に適応する通知を配信する方法について説明します。これにより、サーバーは、言語に依存しない単一のペイロードを送信し、クライアント デバイスに翻訳を任せることができます。

FCM ローカライズの概要

アプリをローカライズするには、ユーザーのアプリ内の文字列リソース エントリに対応するキーを送信します。デバイスのオペレーティング システム（OS）は、動的引数の検索と挿入を処理します。

ステップ 1: アプリでローカライズされた文字列リソースを定義する

FCM のローカライズを開始するには、Android プロジェクトと iOS プロジェクトで必要な翻訳が利用可能であることを確認することが重要です。

Android の設定

文字列リソースを定義する: res/values/strings.xml にデフォルト言語の文字列を入力します。*_loc_args で渡す予定がある動的な値には、形式指定子（%1$s、%2$d など）を使用します。

デフォルト（res/values/strings.xml）:

<resources>
    <string name="welcome_title">Welcome, %1$s!</string>
    <string name="new_message_body">You have %1$d new message(s) from %2$s.</string>
</resources>

翻訳を追加する: ISO 言語コード（例: フランス語の場合 values-fr、スペイン語の場合 values-es）を使用して言語固有のディレクトリを作成し、キーを翻訳します。

フランス語（res/values-fr/strings.xml）:

<resources>
    <string name="welcome_title">Bienvenue, %1$s!</string>
    <string name="new_message_body">Vous avez %1$d nouveau(x) message(s) de %2$s.</string>
</resources>

詳細については、以下のドキュメントをご覧ください。

• 文字列リソース - Android デベロッパー

• アプリをローカライズする - Android デベロッパー

iOS の設定

文字列リソースを定義する: Localizable.strings ファイル（通常は Base.lproj フォルダまたは String Catalog 内）で基本文字列を定義します。動的な値には形式指定子（%@、%ld など）を使用します。多くの場合、キーは慣例としてすべて大文字で定義されます。

デフォルト（英語 Localizable.strings）:

"WELCOME_TITLE" = "Welcome, %@!";
"NEW_MESSAGE_BODY" = "You have %ld new message(s) from %@.";

翻訳を追加する: 言語固有の .lproj フォルダを作成し（または String Catalog を使用してローカライズを追加し）、キーを翻訳します。

フランス語（fr.lproj/Localizable.strings）:

"WELCOME_TITLE" = "Bienvenue, %@!";
"NEW_MESSAGE_BODY" = "Vous avez %ld nouveau(x) message(s) de %@.";

詳細については、以下のドキュメントをご覧ください。

• ローカライズ - Apple デベロッパー向けドキュメント

• 文字列リソース - Apple デベロッパー向けドキュメント

ステップ 2: FCM メッセージ ペイロードを構築する

FCM HTTP v1 API を使用して通知を送信する場合、サーバーはリソースキー（*_loc_key）と動的データ（*_loc_args）を文字列の配列として使用する単一のペイロードを構築します。

FCM HTTP v1 ペイロードの例

ローカライズ キーは、プラットフォーム固有のオーバーライド ブロック（android.notification と apns.payload.aps.alert）内に配置されます。

{
  "message": {
    "token": "DEVICE_REGISTRATION_TOKEN",

    "android": {
      "notification": {
        // Android keys match strings.xml resource names
        "title_loc_key": "welcome_title",
        "title_loc_args": ["Alice"],
        "body_loc_key": "new_message_body",
        "body_loc_args": ["3", "Bob"]
      }
    },

    "apns": {
      "payload": {
        "aps": {
          "alert": {
            // iOS uses 'title-loc-key' and 'loc-key' (for the body)
            "title-loc-key": "WELCOME_TITLE",
            "title-loc-args": ["Alice"],
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["3", "Bob"]
          }
        }
      }
    }
  }
}

ペイロード引数に関して考慮すべきポイント

• 順序が重要: *_loc_args 内の文字列の順序は、文字列リソース ファイル内のプレースホルダで求められる順序と一致させる必要があります（例: %1$s、%2$s）。

• 文字列のみ: *_loc_args 配列内のすべての要素は、数値（例の "3" など）を表す場合でも、文字列にする必要があります。クライアント OS の文字列フォーマッタは、形式指定子（%ld または %1$d）に基づいて最終的な型変換を処理します。

ステップ 3: クライアントの処理と表示

デバイスが通知を受信すると、次の手順が自動的に行われます。

1. 言語チェック: デバイスはユーザーのメインの言語を特定します（例:ドイツ語、イタリア語）。

2. キーの検索: OS は *_loc_key 値（welcome_title）を使用して、アプリのリソース ファイルでデバイスの言語に対応する翻訳された文字列を検索します。

3. 引数の挿入: OS は *_loc_args（["Alice"]）から配列を取得し、言語の書式設定ルール（句読点、単語の順序など）に従って、その値をローカライズされた文字列に挿入します。

このプロセスを使用すると、すべてのユーザーはサーバーから取得した標準化されたペイロードを維持しながら、言語設定に合わせたメッセージを正しい言語構造で受け取ることができます。

例: ローカライズ オプションを使用した通知メッセージ

次の送信リクエストの例は、クライアントがローカライズされたメッセージを表示できるように、ローカライズ オプションを含む通知を Tech トピックに送信します。ユーザーのデバイスでの視覚効果の例を次に示します。

var topicName = 'industry-tech';

var message = {
  android: {
    ttl: 3600000,
    notification: {
      bodyLocKey: 'STOCK_NOTIFICATION_BODY',
      bodyLocArgs: ['FooCorp', '11.80', '835.67', '1.43']
    }
  },
  apns: {
    payload: {
      aps: {
        alert: {
          locKey: 'STOCK_NOTIFICATION_BODY',
          locArgs: ['FooCorp', '11.80', '835.67', '1.43']
        }
      }
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message": {
    "topic":"Tech",
    "android": {
      "ttl":"3600s",
      "notification": {
        "body_loc_key": "STOCK_NOTIFICATION_BODY",
        "body_loc_args": ["FooCorp", "11.80", "835.67", "1.43"]
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "alert": {
            "loc-key": "STOCK_NOTIFICATION_BODY",
            "loc-args": ["FooCorp", "11.80", "835.67", "1.43"]
          }
        }
      }
    }
  }
}'

メッセージ本文のプラットフォーム固有のブロックで使用できるキーの詳細については、HTTP v1 のリファレンス ドキュメントの AndroidNotification と ApnsConfig をご覧ください。APNS でサポートされているキーについては、Apple の Payload Key Reference をご覧ください。