此页面由 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"）。客户端操作系统的字符串格式化程序会根据格式说明符（%ld 或 %1$d）处理最终的类型转换。

第 3 步：客户端处理和显示

当设备收到通知时，系统会自动执行以下步骤：

语言检查：设备会识别用户的主要语言区域设置（例如，德语、意大利语）。
键查找：操作系统使用 *_loc_key 值 (welcome_title) 在应用的资源文件中查找设备语言区域设置对应的已翻译字符串。
实参插入：操作系统从 *_loc_args (["Alice"]) 中获取数组，并根据相应语言区域的格式设置规则（标点符号、字词顺序等）将值插入到本地化字符串中。

设备语言区域	`title_loc_key`：welcome_title	`title_loc_args`：["Alice"]	最终标题显示
英语	`"Welcome, %1$s!"`	小艾	`"Welcome, Alice!"`
法语	`"Bienvenue, %1$s!"`	小艾	`"Bienvenue, Alice!"`
德语	`"Willkommen, %1$s!"`	小艾	`"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 的载荷键参考。