Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

將「訊息」應用程式本地化

本文件說明如何使用 FCM 本地化欄位 (*_loc_key 和 *_loc_args)，根據 Android 和 iOS 裝置上的使用者語言設定，自動調整通知內容。這樣一來，伺服器就能傳送單一、與語言無關的酬載，將翻譯作業委派給用戶端裝置。

FCM 本地化總覽

如要本地化應用程式，您可以傳送與使用者應用程式中字串資源項目對應的金鑰。裝置的作業系統 (OS) 會處理動態引數的查詢和插入。

FCM 欄位	說明	用戶端動作
`title_loc_key`	用戶端應用程式字串資源中標題字串的索引鍵。	OS 會在應用程式的本地化檔案中，找出對應的字串。
`body_loc_key`	用戶端應用程式字串資源中內文字串的索引鍵。	OS 會在應用程式的本地化檔案中，找出對應的字串。
`title_loc_args`	要替換成 `title_loc_key` 字串的動態字串值陣列。	OS 會將這些引數插入本地化字串的格式指定碼。
`body_loc_args`	要替換成 `body_loc_key` 字串的動態字串值陣列。	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>

如要瞭解詳情，請參閱下列說明文件：

iOS 設定

定義字串資源：在 Localizable.strings 檔案 (通常位於 Base.lproj 資料夾或字串目錄) 中定義基本字串。請使用格式指定碼 (%@、%ld 等) 來指定動態價值。按照慣例，鍵通常會以全大寫字母定義。

預設 (英文 Localizable.strings)：

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

新增翻譯：建立特定語言的 .lproj 資料夾 (或使用字串目錄新增本地化內容)，並翻譯索引鍵。

法文 (fr.lproj/Localizable.strings)：

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

如要瞭解詳情，請參閱下列說明文件：

步驟 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：用戶端處理和顯示

裝置收到通知後，會自動執行下列步驟：

語言檢查：裝置會識別使用者的主要語言代碼 (例如德文、義大利文)。
鍵查詢：OS 會使用 *_loc_key 值 (welcome_title)，在應用程式的資源檔案中，查詢裝置語言代碼對應的翻譯字串。
引數插入：OS 會從 *_loc_args (["Alice"]) 擷取陣列，並將值插入本地化字串，同時遵循語言代碼的格式規則 (標點符號、字詞順序等)。

裝置語言代碼	`title_loc_key`: welcome_title	`title_loc_args`: ["Alice"]	最終標題顯示
英文	`"Welcome, %1$s!"`	Alice	`"Welcome, Alice!"`
法文	`"Bienvenue, %1$s!"`	Alice	`"Bienvenue, Alice!"`
德文	`"Willkommen, %1$s!"`	Alice	`"Willkommen, Alice!"`

這個程序可確保每位使用者都能收到符合其語言偏好設定的訊息，並使用正確的語言結構，同時維持伺服器的標準化酬載。

範例：含有本地化選項的通知訊息

下列傳送要求範例會將通知傳送至 Tech 主題，包括用戶端顯示本地化訊息的本地化選項。以下是使用者裝置上的視覺效果範例：

簡單繪圖，顯示兩部裝置分別顯示英文和西班牙文文字

Node.js

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);
  });

REST

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 的酬載金鑰參考資料。