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 payload singolo e 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 di risorsa stringa all'interno dell'applicazione dell'utente. Il sistema operativo del dispositivo gestisce la ricerca e l'inserimento degli argomenti dinamici.

Passaggio 1: definisci le risorse stringa localizzate nelle tue app

Per iniziare con la localizzazione di FCM, è importante assicurarsi di disporre delle traduzioni necessarie nei progetti Android e iOS.

Configurazione Android

Definisci le risorse stringa: inserisci le stringhe di lingua predefinite in res/values/strings.xml. Utilizza gli specificatori di formato (%1$s, %2$d e così via) per tutti i valori dinamici che prevedi di trasferire 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:

• Risorse stringa - Android Developers

• Localizzare l'app - Sviluppatori Android

Configurazione 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 specificatori 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:

• Localizzazione - Documentazione per gli sviluppatori Apple

• Risorse stringa - Documentazione per gli sviluppatori Apple

Passaggio 2: crea il payload del messaggio FCM

Quando invia la notifica utilizzando l'API HTTP v1 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 finale del tipo in base allo specificatore di formato (%ld o %1$d).

Passaggio 3: elaborazione e visualizzazione lato client

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

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 di argomenti: il sistema operativo prende l'array da *_loc_args (["Alice"]) e inserisce i valori nella stringa localizzata, rispettando le regole di formattazione della lingua (punteggiatura, ordine delle parole e così via).

Questa procedura assicura che ogni utente riceva un messaggio personalizzato in base alle proprie preferenze della 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 il client per visualizzare i messaggi localizzati. Ecco un esempio dell'effetto visivo sul dispositivo di un utente:

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

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