Nachrichten lokalisieren

In dieser Dokumentation wird die Verwendung von FCM-Lokalisierungsfeldern (*_loc_key und *_loc_args) beschrieben, um Benachrichtigungen zu senden, die sich automatisch an die Spracheinstellungen eines Nutzers unter Android und iOS anpassen. So kann Ihr Server eine einzelne, sprachunabhängige Nutzlast senden und die Übersetzung an das Clientgerät delegieren.

FCM – Lokalisierung – Übersicht

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 String-Ressourcen in Ihren Apps definieren

Bevor Sie mit der Lokalisierung von FCM 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 die Strings für die Standardsprache in res/values/strings.xml ein. Verwenden Sie Formatspezifizierer (%1$s, %2$d usw.) für alle dynamischen Werte, die Sie in der *_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:

• String-Ressourcen – Android-Entwickler

• App lokalisieren – Android-Entwickler

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 konventionsgemäß 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 mithilfe eines String-Katalogs 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

• String-Ressourcen – 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 Überlegungen zu Nutzlastargumenten

• Reihenfolge beachten: Die Strings in *_loc_args müssen genau in der Reihenfolge angegeben werden, 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-Formatierer des Client-Betriebssystems übernimmt die endgültige Typkonvertierung basierend auf dem Formatbezeichner (%ld oder %1$d).

Schritt 3: Verarbeitung und Anzeige auf dem Client

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

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

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

3. Argumenteinfügung: Das Betriebssystem nimmt das Array aus *_loc_args (["Alice"]) und fügt die Werte in den lokalisierten String ein. Dabei werden die Formatierungsregeln der Sprache (Satzzeichen, Wortreihenfolge usw.) berücksichtigt.

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

Beispiel: Benachrichtigung mit Lokalisierungsoptionen

Im folgenden Beispiel wird eine Benachrichtigung an das Thema Tech gesendet, einschließlich Lokalisierungsoptionen für den Client, um lokalisierte Nachrichten anzuzeigen. Hier ein Beispiel für den visuellen Effekt 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 unter AndroidNotification und ApnsConfig in der HTTP v1-Referenzdokumentation. Dort finden Sie ausführliche Informationen 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.