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.

Panoramica della localizzazioneFCM

Per localizzare la tua app, puoi inviare una chiave che corrisponde a una voce di risorsa stringa all'interno dell'applicazione dell'utente. Il sistema operativo (OS) del dispositivo gestisce la ricerca e l'inserimento degli 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 a utilizzare la localizzazione 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.

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 la 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 ulteriori informazioni, consulta la seguente documentazione:

Configurazione iOS

Definisci le risorse stringa: definisci le stringhe di base nel Localizable.strings file (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 vengono spesso definite in maiuscolo.

Predefinito (inglese Localizable.strings):

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

Aggiungi traduzioni: crea cartelle specifiche per la lingua .lproj (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 ulteriori informazioni, consulta la seguente documentazione:

Passaggio 2: crea il payload del messaggio FCM

Quando invia la notifica utilizzando l'API HTTP v1 di FCM, il 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 FCM

Le chiavi di localizzazione vengono 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 chiave 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, vengono eseguiti automaticamente i seguenti passaggi:

Controllo della lingua: il dispositivo identifica le impostazioni internazionali principali dell'utente (ad es. tedesco, italiano).
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.
Inserimento dell'argomento: 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 linguistiche, utilizzando la struttura linguistica corretta, mantenendo al contempo un payload standardizzato dal 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 il client per visualizzare i messaggi localizzati. Ecco un esempio dell'effetto visivo sul dispositivo di un utente:

Semplice disegno 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 informazioni dettagliate sulle chiavi disponibili nei blocchi specifici della piattaforma nel corpo del messaggio, consulta AndroidNotification e ApnsConfig nella documentazione di riferimento di HTTP v1 . Per le chiavi supportate da APNS, consulta il riferimento alle chiavi del payload di Apple.