Локализация сообщений

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

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

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

Шаг 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>

Для получения более подробной информации используйте следующую документацию:

• Строковые ресурсы — разработчики Android

• Локализуйте свое приложение — Разработчики Android

Настройка 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 %@.";

Для получения более подробной информации используйте следующую документацию:

• Локализация — документация для разработчиков Apple

• Строковые ресурсы — документация для разработчиков Apple

Шаг 2: Создание полезной нагрузки сообщения FCM

При отправке уведомления с использованием API FCM HTTP v1 ваш сервер создает единую полезную нагрузку, которая использует ключи ресурсов ( *_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: Обработка и отображение клиентской информации

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

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

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

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

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