Как локализовать сообщения

В этой документации описывается, как использовать поля локализации FCM (*_loc_key и *_loc_args), чтобы уведомления автоматически адаптировались к языковым настройкам пользователя на устройствах Android и iOS. Это позволяет вашему серверу отправлять единую, не зависящую от языка полезную нагрузку, делегируя перевод клиентскому устройству.

Обзор локализации FCM

Чтобы локализовать приложение, вы можете отправить ключ, соответствующий строковому ресурсу в приложении пользователя. Поиск и вставка динамических аргументов выполняется операционной системой устройства.

Поле 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. Используйте спецификаторы формата (%1$s, %2$d и т. д.) для любых динамических значений, которые вы планируете передавать в *_loc_args.

По умолчанию (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) в виде массива строк.

Пример полезной нагрузки HTTP v1 для FCM

Ключи локализации размещаются в блоках переопределения для конкретных платформ (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. Обработка и показ на стороне клиента

Когда устройство получает уведомление, автоматически выполняются следующие действия:

  1. Проверка языка. Устройство определяет основной язык пользователя (например, немецкий или итальянский).

  2. Поиск ключа. ОС использует значение *_loc_key (welcome_title), чтобы найти соответствующую переведенную строку в файлах ресурсов приложения для региональных настроек устройства.

  3. Вставка аргументов. ОС берет массив из *_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"]
          }
        }
      }
    }
  }
}'

Чтобы узнать больше, ознакомьтесь с разделами AndroidNotification и ApnsConfig в справочной документации по HTTP v1. Там вы найдете подробную информацию о ключах, доступных в блоках для конкретных платформ в теле сообщения. Список ключей, поддерживаемых APNS, можно найти в справочнике по ключам полезной нагрузки от Apple.