Nachrichten lokalisieren

In dieser Dokumentation wird die Verwendung von FCM Lokalisierungsfeldern (*_loc_key und *_loc_args) beschrieben, um Benachrichtigungen zu senden, die automatisch an die Spracheinstellungen eines Nutzers auf Android- und iOS-Geräten angepasst werden. So kann Ihr Server eine einzelne, sprachunabhängige Nutzlast senden und die Übersetzung dem Clientgerät überlassen.

FCMÜbersicht zur Lokalisierung

Wenn Sie Ihre App lokalisieren möchten, können Sie einen Schlüssel senden, der einem String-Ressourceneintrag in der Anwendung des Nutzers entspricht. Das Betriebssystem des Geräts übernimmt die Suche und das Einfügen dynamischer Argumente.

Schritt 1: Lokalisierte Stringressourcen in Ihren Apps definieren

Wenn Sie mit der FCM Lokalisierung beginnen möchten, müssen Sie sicherstellen, dass die erforderlichen Übersetzungen in Ihren Android- und iOS-Projekten verfügbar sind.

Android-Einrichtung

Stringressourcen definieren: Geben Sie Ihre Standard-Strings in res/values/strings.xml ein. Verwenden Sie Formatspezifizierer (%1$s, %2$d usw.) für alle dynamischen Werte, die Sie in *_loc_args übergeben möchten.

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

Übersetzungen hinzufügen: Erstellen Sie sprachspezifische Verzeichnisse mit den ISO-Sprachcodes (z.B. values-fr für Französisch, values-es für Spanisch) und übersetzen Sie die Schlüssel.

Französisch (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>

Weitere Informationen finden Sie in der folgenden Dokumentation:

• Stringressourcen – Android-Entwickler

• App lokalisieren – Android-Entwickler

iOS-Einrichtung

Stringressourcen definieren: Definieren Sie Ihre Basis-Strings in der Localizable.strings Datei (in der Regel im Ordner Base.lproj oder in einem String-Katalog). Verwenden Sie Formatspezifizierer (%@, %ld usw.) für dynamische Werte. Schlüssel werden aus Konventionsgründen oft in Großbuchstaben definiert.

Standard (Englisch Localizable.strings):

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

Übersetzungen hinzufügen: Erstellen Sie sprachspezifische .lproj Ordner (oder fügen Sie Lokalisierungen mit einem String-Katalog hinzu) und übersetzen Sie die Schlüssel.

Französisch (fr.lproj/Localizable.strings):

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

Weitere Informationen finden Sie in der folgenden Dokumentation:

• Lokalisierung – Apple-Entwicklerdokumentation

• Stringressourcen – Apple-Entwicklerdokumentation

Schritt 2: FCM Nachrichtennutzlast erstellen

Wenn Sie die Benachrichtigung mit der FCM HTTP v1 API senden, erstellt Ihr Server eine einzelne Nutzlast, die die Ressourcenschlüssel (*_loc_key) und die dynamischen Daten (*_loc_args) als Array von Strings verwendet.

Beispiel für eine FCM HTTP v1-Nutzlast

Die Lokalisierungsschlüssel werden in den plattformspezifischen Überschreibungsblöcken (android.notification und apns.payload.aps.alert) platziert.

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

Wichtige Hinweise zu Nutzlastargumenten

• Reihenfolge ist wichtig: Die Strings in *_loc_args müssen genau in der Reihenfolge vorliegen, die für die Platzhalter in der String-Ressourcendatei erforderlich ist (z.B. %1$s, %2$s).

• Nur Strings: Alle Elemente im Array *_loc_args müssen Strings sein, auch wenn sie Zahlen darstellen (wie "3" im Beispiel). Der String-Formatierer des Clientbetriebssystems übernimmt die endgültige Typkonvertierung basierend auf dem Formatspezifizierer (%ld oder %1$d).

Schritt 3: Clientverarbeitung und -anzeige

Wenn das Gerät die Benachrichtigung empfängt, werden die folgenden Schritte automatisch ausgeführt:

1. Sprachprüfung: Das Gerät ermittelt das primäre Gebietsschema des Nutzers (z.B. Deutsch, Italienisch).

2. Schlüsselsuche: Das Betriebssystem verwendet den Wert *_loc_key (welcome_title), um den entsprechenden übersetzten String in den Ressourcendateien der App für das Gebietsschema des Geräts zu suchen.

3. Argumente einfügen: Das Betriebssystem nimmt das Array aus *_loc_args (["Alice"]) und fügt die Werte in den lokalisierten String ein, wobei die Formatierungsregeln des Gebietsschemas berücksichtigt werden (Interpunktion, Wortreihenfolge usw.).

So erhält jeder Nutzer eine Nachricht, die an seine Spracheinstellungen angepasst ist und die richtige sprachliche Struktur verwendet. Gleichzeitig wird eine standardisierte Nutzlast von Ihrem Server beibehalten.

Beispiel: Benachrichtigungsnachricht mit Lokalisierungsoptionen

Die folgende Sendeanfrage sendet eine Benachrichtigung an das Thema Tech und enthält Lokalisierungsoptionen für den Client, um lokalisierte Nachrichten anzuzeigen. Hier ein Beispiel für die visuelle Wirkung auf dem Gerät eines Nutzers:

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

Weitere Informationen finden Sie in der HTTP v1 Referenzdokumentation unter AndroidNotification und ApnsConfig für vollständige Details zu den Schlüsseln, die in plattformspezifischen Blöcken im Inhalt der Nachricht verfügbar sind. Informationen zu den von APNS unterstützten Schlüsseln finden Sie in der Payload Key Reference von Apple.