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

В этой документации описывается использование полей локализации 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 и т. д.) для динамических значений. Ключи часто определяются заглавными буквами для соблюдения соглашений.

По умолчанию (English 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 по ключам полезной нагрузки .