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 linguistiques 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 d'arguments dynamiques.
| Champ FCM | Description | Action du client |
|---|---|---|
title_loc_key |
Clé de la chaîne de titre dans les ressources de chaîne de l'application cliente. | L'OS trouve la chaîne correspondante dans les fichiers localisés de l'application. |
body_loc_key |
Clé de la chaîne du corps dans les ressources de chaîne de l'application cliente. | L'OS trouve la chaîne correspondante dans les fichiers localisés de l'application. |
title_loc_args |
Tableau de valeurs de chaîne dynamiques à remplacer dans la chaîne title_loc_key. |
L'OS insère ces arguments dans les spécificateurs de format de la chaîne localisée. |
body_loc_args |
Tableau de valeurs de chaîne dynamiques à remplacer dans la chaîne body_loc_key. |
L'OS insère ces arguments dans les spécificateurs de format de la chaîne localisée. |
Étape 1 : Définissez des ressources de chaîne 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éfinir des ressources de chaîne : saisissez vos chaînes de 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 :
Configuration iOS
Définir des 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 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 :
Étape 2 : Créez la charge utile du message FCM
Lorsque vous envoyez la notification à l'aide de l'API HTTP v1 FCM, votre serveur crée une charge utile unique qui utilise les clés de ressource (*_loc_key) et les données dynamiques (*_loc_args) sous la forme d'un 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_argsdoivent être dans l'ordre exact requis par les espaces réservés dans le fichier de ressources de chaîne (par exemple,%1$s,%2$s).Chaînes uniquement : tous les éléments du tableau
*_loc_argsdoivent ê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 (%ldou%1$d).
Étape 3 : Traitement et affichage par le client
Lorsque l'appareil reçoit la notification, les étapes suivantes se déroulent automatiquement :
Vérification de la langue : l'appareil identifie les paramètres régionaux principaux de l'utilisateur (par exemple, allemand, italien).
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.Insertion d'arguments : l'OS récupère 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 des paramètres régionaux (ponctuation, ordre des mots, etc.).
| Paramètres régionaux de l'appareil | title_loc_key: welcome_title |
title_loc_args : ["Alice"] |
Affichage du titre final |
|---|---|---|---|
| Anglais | "Welcome, %1$s!" |
Alice | "Welcome, Alice!" |
| Français | "Bienvenue, %1$s!" |
Alice | "Bienvenue, Alice!" |
| Allemand | "Willkommen, %1$s!" |
Alice | "Willkommen, Alice!" |
Ce processus garantit 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 provenant de 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 permettant au client d'afficher des messages localisés.
Voici un exemple d'effet visuel sur l'appareil d'un utilisateur :
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"]
}
}
}
}
}
}'
Pour en savoir plus, consultez AndroidNotification et ApnsConfig dans la documentation de référence sur HTTP v1 pour obtenir des informations complètes 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.