Diese Seite wurde von der Cloud Translation API übersetzt.

Nachrichten lokalisieren

In dieser Dokumentation wird beschrieben, wie Sie FCM-Lokalisierungsfelder (*_loc_key und *_loc_args) verwenden, um Benachrichtigungen zu senden, die sich auf Android- und iOS-Geräten automatisch an die Spracheinstellungen des Nutzers anpassen. So kann Ihr Server eine einzelne, sprachunabhängige Nutzlast senden und die Übersetzung dem Clientgerät überlassen.

FCM Übersicht über die Lokalisierung

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

FCM-Feld	Beschreibung	Clientaktion
`title_loc_key`	Der Schlüssel für den Titelstring in den Stringressourcen der Client-App.	Das Betriebssystem sucht in den lokalisierten Dateien der App nach dem entsprechenden String.
`body_loc_key`	Der Schlüssel für den Body-String in den String-Ressourcen der Client-App.	Das Betriebssystem sucht in den lokalisierten Dateien der App nach dem entsprechenden String.
`title_loc_args`	Ein Array dynamischer Stringwerte, die in den `title_loc_key`-String eingefügt werden sollen.	Das Betriebssystem fügt diese Argumente in die Formatierungsspezifikationen des lokalisierten Strings ein.
`body_loc_args`	Ein Array dynamischer Stringwerte, die in den `body_loc_key`-String eingefügt werden sollen.	Das Betriebssystem fügt diese Argumente in die Formatierungsspezifikationen des lokalisierten Strings ein.

Schritt 1: Lokalisierte String-Ressourcen in Ihren Apps definieren

Bevor Sie mit der FCM-Lokalisierung beginnen, müssen Sie dafür sorgen, dass die erforderlichen Übersetzungen in Ihren Android- und iOS-Projekten verfügbar sind.

Android-Einrichtung

String-Ressourcen definieren: Geben Sie Ihre Standard-Sprachstrings 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:

iOS-Einrichtung

String-Ressourcen definieren: Definieren Sie Ihre Basis-Strings in der Datei Localizable.strings (normalerweise 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 (Deutsch 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:

Schritt 2: FCM-Nachrichtennutzlast erstellen

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

Beispiel für die FCM-HTTP-v1-Nutzlast

Die Lokalisierungsschlüssel befinden sich in den plattformspezifischen Überschreibungsblöcken (android.notification und 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"]
          }
        }
      }
    }
  }
}

Wichtige Hinweise zu Nutzlastargumenten

Reihenfolge wichtig: Die Strings in *_loc_args müssen in der genauen Reihenfolge vorliegen, die für die Platzhalter in der String-Ressourcendatei erforderlich ist (z.B. %1$s, %2$s).
Nur Strings: Alle Elemente im *_loc_args-Array müssen Strings sein, auch wenn sie Zahlen darstellen (wie "3" im Beispiel). Der String-Formatter des Clientbetriebssystems übernimmt die endgültige Typkonvertierung basierend auf dem Formatspezifizierer (%ld oder %1$d).

Schritt 3: Clientseitige Verarbeitung und Darstellung

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

Sprachprüfung: Das Gerät ermittelt die primäre Sprache des Nutzers (z.B. Deutsch, Italienisch).
Schlüsselsuche: Das Betriebssystem verwendet den Wert *_loc_key (welcome_title), um in den Ressourcendateien der App für die Sprache des Geräts nach dem entsprechenden übersetzten String zu suchen.
Argumente einfügen: Das Betriebssystem übernimmt das Array aus *_loc_args (["Alice"]) und fügt die Werte in den lokalisierten String ein. Dabei werden die Formatierungsregeln des jeweiligen Gebietsschemas (Satzzeichen, Wortfolge usw.) berücksichtigt.

Gerätesprache	`title_loc_key`: welcome_title	`title_loc_args`: ["Alice"]	Anzeige des endgültigen Titels
Englisch	`"Welcome, %1$s!"`	Anne	`"Welcome, Alice!"`
Französisch	`"Bienvenue, %1$s!"`	Anne	`"Bienvenue, Alice!"`
Deutsch	`"Willkommen, %1$s!"`	Anne	`"Willkommen, Alice!"`

So wird sichergestellt, dass jeder Nutzer eine Nachricht erhält, die auf seine Spracheinstellungen zugeschnitten ist und die richtige sprachliche Struktur verwendet, während gleichzeitig eine standardisierte Nutzlast von Ihrem Server beibehalten wird.

Beispiel: Benachrichtigung mit Lokalisierungsoptionen

Im folgenden Beispiel wird eine Benachrichtigung an das Thema Tech gesendet. Sie enthält Lokalisierungsoptionen für den Client, damit lokalisierte Nachrichten angezeigt werden können. Hier ein Beispiel für den visuellen Effekt auf dem Gerät eines Nutzers:

Einfache Zeichnung von zwei Geräten, auf denen Text auf Englisch und Spanisch angezeigt wird

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

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