Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Localiser les messages

Cette documentation décrit l'utilisation des champs de localisation FCM(*_loc_key et *_loc_args) pour diffuser 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.

Présentation de la localisation FCM

Pour localiser votre application, vous pouvez envoyer une clé qui correspond à 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.	Le système d'exploitation recherche la chaîne correspondante dans les fichiers localisés de l'application.
`body_loc_key`	Clé de la chaîne de corps dans les ressources de chaîne de l'application cliente.	Le système d'exploitation recherche la chaîne correspondante dans les fichiers localisés de l'application.
`title_loc_args`	Tableau de valeurs de chaîne dynamiques à substituer dans la chaîne `title_loc_key`.	Le système d'exploitation 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 à substituer dans la chaîne `body_loc_key`.	Le système d'exploitation 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 à utiliser la localisation 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 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>

Ajoutez des traductions : créez des répertoires spécifiques à la 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 d'iOS

Définissez des ressources de chaîne : définissez vos chaînes de base dans le Localizable.strings fichier (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 %@.";

Ajoutez des traductions : créez des dossiers spécifiques à la langue .lproj (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 FCM HTTP v1, votre serveur crée une seule charge utile qui utilise les clés de ressource (*_loc_key) et les données dynamiques (*_loc_args) sous forme de tableau de chaînes.

Exemple FCM de charge utile HTTP v1

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 à retenir concernant 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 du système d'exploitation client gère la conversion de type finale en fonction du spécificateur de format (%ld ou %1$d).

Étape 3 : Traitement et affichage du client

Lorsque l'appareil reçoit la notification, les étapes suivantes se produisent 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é : le système d'exploitation 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 : le système d'exploitation 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 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 final du titre
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 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 pour que le client affiche des messages localisés. Voici un exemple de l'effet visuel sur l'appareil d'un utilisateur :

Dessin simple de deux appareils affichant du texte en anglais et en espagnol

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 HTTP v1 pour obtenir des informations complètes sur les clés disponibles dans les blocs spécifiques à la plate-forme du corps du message. Pour connaître les clés compatibles avec APNS, consultez la référence des clés de charge utile d'Apple.