Localiser les messages

Cette documentation décrit l'utilisation des champs de localisation FCM (*_loc_key et *_loc_args) pour envoyer des notifications qui s'adaptent automatiquement aux paramètres de langue d'un utilisateur sur Android et iOS. Cela permet à votre serveur d'envoyer une seule charge utile indépendante de la langue, en déléguant la traduction à l'appareil client.

FCM Présentation de la localisation

Pour localiser votre application, vous pouvez envoyer une clé correspondant à une entrée de ressource de chaîne dans l'application de l'utilisateur. Le système d'exploitation (OS) de l'appareil gère la recherche et l'insertion des arguments dynamiques.

Étape 1 : Définissez des ressources de chaînes localisées dans vos applications

Pour commencer à localiser FCM, il est important de vous assurer que vous disposez des traductions nécessaires dans vos projets Android et iOS.

Configuration d'Android

Définissez les ressources de chaîne : saisissez les chaînes de votre langue par défaut dans res/values/strings.xml. Utilisez des spécificateurs de format (%1$s, %2$d, etc.) pour toutes les valeurs dynamiques que vous prévoyez de transmettre dans *_loc_args.

Par défaut (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>

Ajouter des traductions : créez des répertoires spécifiques à une langue à l'aide des codes de langue ISO (par exemple, values-fr pour le français, values-es pour l'espagnol) et traduisez les clés.

Français (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>

Pour en savoir plus, consultez la documentation suivante :

• Ressources de chaîne – Développeurs Android

• Localiser votre application – Développeurs Android

Configuration d'iOS

Définissez les ressources de chaîne : définissez vos chaînes de base dans le fichier Localizable.strings (généralement dans le dossier Base.lproj ou dans un catalogue de chaînes). Utilisez des spécificateurs de format (%@, %ld, etc.) pour les valeurs dynamiques. Par convention, les clés sont souvent définies en majuscules.

Par défaut (anglais Localizable.strings) :

"WELCOME_TITLE" = "Welcome, %@!";
"NEW_MESSAGE_BODY" = "You have %ld new message(s) from %@.";

Ajouter des traductions : créez des dossiers .lproj spécifiques à une langue (ou ajoutez des localisations à l'aide d'un catalogue de chaînes) et traduisez les clés.

Français (fr.lproj/Localizable.strings) :

"WELCOME_TITLE" = "Bienvenue, %@!";
"NEW_MESSAGE_BODY" = "Vous avez %ld nouveau(x) message(s) de %@.";

Pour en savoir plus, consultez la documentation suivante :

• Localisation : documentation pour les développeurs Apple

• Ressources de chaîne – Documentation Apple Developer

Étape 2 : Construisez la charge utile du message FCM

Lorsque vous envoyez la notification à l'aide de l'API HTTP v1 FCM, votre serveur construit une charge utile unique qui utilise les clés de ressources (*_loc_key) et les données dynamiques (*_loc_args) sous forme de tableau de chaînes.

Exemple de charge utile HTTP v1 FCM

Les clés de localisation sont placées dans les blocs de remplacement spécifiques à la plate-forme (android.notification et 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"]
          }
        }
      }
    }
  }
}

Points clés à prendre en compte pour les arguments de charge utile

• L'ordre est important : les chaînes de *_loc_args doivent être dans l'ordre exact requis par les espaces réservés du fichier de ressources de chaîne (par exemple, %1$s, %2$s).

• Chaînes uniquement : tous les éléments du tableau *_loc_args doivent être des chaînes, même s'ils représentent des nombres (comme "3" dans l'exemple). Le formateur de chaîne de l'OS client gère la conversion de type finale en fonction du spécificateur de format (%ld ou %1$d).

Étape 3 : Traitement et affichage côté client

Lorsque l'appareil reçoit la notification, les étapes suivantes se produisent automatiquement :

1. Vérification de la langue : l'appareil identifie la langue principale de l'utilisateur (par exemple, allemand, italien).

2. Recherche de clé : l'OS utilise la valeur *_loc_key (welcome_title) pour rechercher la chaîne traduite correspondante dans les fichiers de ressources de l'application pour les paramètres régionaux de l'appareil.

3. Insertion d'arguments : l'OS prend le tableau de *_loc_args (["Alice"]) et insère les valeurs dans la chaîne localisée, en respectant les règles de mise en forme de la langue (ponctuation, ordre des mots, etc.).

Ce processus permet de s'assurer que chaque utilisateur reçoit un message adapté à ses préférences linguistiques, en utilisant la structure linguistique appropriée, tout en conservant une charge utile standardisée depuis votre serveur.

Exemple : message de notification avec options de localisation

L'exemple de requête d'envoi suivant envoie une notification au sujet Tech, y compris des options de localisation pour que le client affiche des messages localisés. Voici un exemple de l'effet visuel sur l'appareil d'un utilisateur :

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"]
          }
        }
      }
    }
  }
}'

Pour en savoir plus, consultez AndroidNotification et ApnsConfig dans la documentation de référence HTTP/1.1 pour obtenir des informations détaillées sur les clés disponibles dans les blocs spécifiques à la plate-forme dans le corps du message. Pour connaître les clés compatibles avec APNS, consultez la documentation de référence sur les clés de charge utile d'Apple.