Localizza i messaggi

Questa documentazione descrive l'utilizzo dei campi di localizzazione FCM (*_loc_key e *_loc_args) per inviare notifiche che si adattano automaticamente alle impostazioni della lingua di un utente su Android e iOS. In questo modo, il server può inviare un singolo payload indipendente dalla lingua, delegando la traduzione al dispositivo client.

FCM Panoramica della localizzazione

Per localizzare la tua app, puoi inviare una chiave che corrisponde a una voce della risorsa stringa all'interno dell'applicazione dell'utente. Il sistema operativo del dispositivo gestisce la ricerca e l'inserimento di argomenti dinamici.

Campo FCM Descrizione Azione del client
title_loc_key La chiave per la stringa del titolo nelle risorse stringa dell'app client. Il sistema operativo trova la stringa corrispondente nei file localizzati dell'app.
body_loc_key La chiave per la stringa del corpo nelle risorse stringa dell'app client. Il sistema operativo trova la stringa corrispondente nei file localizzati dell'app.
title_loc_args Un array di valori di stringa dinamici da sostituire nella stringa title_loc_key. Il sistema operativo inserisce questi argomenti negli identificatori di formato della stringa localizzata.
body_loc_args Un array di valori di stringa dinamici da sostituire nella stringa body_loc_key. Il sistema operativo inserisce questi argomenti negli identificatori di formato della stringa localizzata.

Passaggio 1: definisci le risorse stringa localizzate nelle tue app

Per iniziare con la localizzazione di FCM, è importante assicurarsi di avere le traduzioni necessarie disponibili nei progetti Android e iOS.

Configurazione Android

Definisci le risorse stringa: inserisci le stringhe della lingua predefinita in res/values/strings.xml. Utilizza gli identificatori di formato (%1$s, %2$d e così via) per tutti i valori dinamici che prevedi di passare in *_loc_args.

Valore predefinito (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>

Aggiungi traduzioni: crea directory specifiche per lingua utilizzando i codici lingua ISO (ad es. values-fr per il francese, values-es per lo spagnolo) e traduci le chiavi.

Francese (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>

Per saperne di più, consulta la seguente documentazione:

Configurazione di iOS

Definisci le risorse stringa: definisci le stringhe di base nel file Localizable.strings (in genere nella cartella Base.lproj o in un catalogo di stringhe). Utilizza gli identificatori di formato (%@, %ld e così via) per i valori dinamici. Per convenzione, le chiavi sono spesso definite in lettere maiuscole.

Predefinita (inglese Localizable.strings):

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

Aggiungi traduzioni: crea cartelle .lproj specifiche per la lingua (o aggiungi localizzazioni utilizzando un catalogo di stringhe) e traduci le chiavi.

Francese (fr.lproj/Localizable.strings):

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

Per saperne di più, consulta la seguente documentazione:

Passaggio 2: crea il payload del messaggio FCM

Quando invia la notifica utilizzando l'API HTTP v1 FCM, il tuo server crea un singolo payload che utilizza le chiavi delle risorse (*_loc_key) e i dati dinamici (*_loc_args) come array di stringhe.

Esempio di payload HTTP v1 di FCM

Le chiavi di localizzazione sono inserite all'interno dei blocchi di override specifici della piattaforma (android.notification e 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"]
          }
        }
      }
    }
  }
}

Considerazioni principali per gli argomenti del payload

  • L'ordine è importante: le stringhe in *_loc_args devono essere nell'ordine esatto richiesto dai segnaposto nel file di risorse stringa (ad es. %1$s, %2$s).

  • Solo stringhe: tutti gli elementi dell'array *_loc_args devono essere stringhe, anche se rappresentano numeri (come "3" nell'esempio). Il formattatore di stringhe del sistema operativo client gestisce la conversione del tipo finale in base all'identificatore di formato (%ld o %1$d).

Passaggio 3: elaborazione e visualizzazione del client

Quando il dispositivo riceve la notifica, i seguenti passaggi vengono eseguiti automaticamente:

  1. Controllo della lingua: il dispositivo identifica le impostazioni internazionali principali dell'utente (ad es. tedesco, italiano).

  2. Ricerca della chiave: il sistema operativo utilizza il valore *_loc_key (welcome_title) per cercare la stringa tradotta corrispondente nei file di risorse dell'app per le impostazioni internazionali del dispositivo.

  3. Inserimento degli argomenti: il sistema operativo prende l'array da *_loc_args (["Alice"]) e inserisce i valori nella stringa localizzata, rispettando le regole di formattazione delle impostazioni internazionali (punteggiatura, ordine delle parole e così via).

Impostazioni internazionali del dispositivo title_loc_key: welcome_title title_loc_args: ["Alice"] Visualizzazione del titolo finale
Inglese "Welcome, %1$s!" Alice "Welcome, Alice!"
Francese "Bienvenue, %1$s!" Alice "Bienvenue, Alice!"
Tedesco "Willkommen, %1$s!" Alice "Willkommen, Alice!"

Questo processo garantisce che ogni utente riceva un messaggio personalizzato in base alle sue preferenze sulla lingua, utilizzando la struttura linguistica corretta, il tutto mantenendo un payload standardizzato dal tuo server.

Esempio: messaggio di notifica con opzioni di localizzazione

La seguente richiesta di invio di esempio invia una notifica all'argomento Tech, incluse le opzioni di localizzazione per consentire al client di visualizzare i messaggi localizzati. Ecco un esempio dell'effetto visivo sul dispositivo di un utente:

Disegno semplice di due dispositivi che mostrano testo in inglese e spagnolo

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

Per saperne di più, consulta AndroidNotification e ApnsConfig nella documentazione di riferimento di HTTP v1 per i dettagli completi sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio. Per le chiavi supportate da APNS, consulta il riferimento alle chiavi del payload di Apple.