本頁面由 Cloud Translation API 翻譯而成。

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

這份文件說明如何使用FCM本地化欄位*_loc_key和*_loc_args，傳送可自動配合 Android 和 iOS 裝置語言設定調整的通知。這樣一來，伺服器就能傳送單一的語言無關酬載，將翻譯工作委派給用戶端裝置。

FCM 本地化總覽

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

FCM 欄位	說明	用戶端動作
`title_loc_key`	用戶端應用程式字串資源中標題字串的鍵。	作業系統會在應用程式的本地化檔案中尋找對應的字串。
`body_loc_key`	用戶端應用程式字串資源中，主體字串的鍵。	作業系統會在應用程式的本地化檔案中尋找對應的字串。
`title_loc_args`	要代入 `title_loc_key` 字串的動態字串值陣列。	作業系統會將這些引數插入本地化字串的格式指定符。
`body_loc_args`	要代入 `body_loc_key` 字串的動態字串值陣列。	作業系統會將這些引數插入本地化字串的格式指定符。

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

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

語言檢查：裝置會找出使用者的主要語言代碼 (例如德文、義大利文)。
鍵值查詢：作業系統會使用 *_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 的「酬載金鑰參考資料」。