Zlokalizuj wiadomości

W tym dokumencie opisujemy użycie FCMpól lokalizacji*_loc_key (*_loc_key i *_loc_args) do dostarczania powiadomień, które automatycznie dostosowują się do ustawień języka użytkownika na urządzeniach z Androidem i iOS. Dzięki temu serwer może wysyłać jeden ładunek niezależny od języka, a tłumaczenie jest delegowane na urządzenie klienta.

FCM Omówienie lokalizacji

Aby zlokalizować aplikację, możesz wysłać klucz odpowiadający wpisowi zasobu tekstowego w aplikacji użytkownika. System operacyjny urządzenia obsługuje wyszukiwanie i wstawianie argumentów dynamicznych.

Krok 1. Zdefiniuj w aplikacjach zlokalizowane zasoby ciągów tekstowych

Aby rozpocząć FCMlokalizację, musisz mieć w projektach na Androida i iOS dostępne niezbędne tłumaczenia.

Konfiguracja Androida

Zdefiniuj zasoby ciągów znaków: wpisz domyślne ciągi znaków w języku res/values/strings.xml. W przypadku wszystkich wartości dynamicznych, które chcesz przekazać w parametrze *_loc_args, użyj specyfikatorów formatu (%1$s, %2$d itp.).

Domyślny (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>

Dodaj tłumaczenia: utwórz katalogi dla poszczególnych języków, używając kodów języków ISO (np. values-fr dla języka francuskiego, values-es dla języka hiszpańskiego) i przetłumacz klucze.

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

Więcej informacji znajdziesz w tych dokumentach:

• Zasoby tekstowe – Android Developers

• Lokalizowanie aplikacji – Deweloperzy Androida

Konfiguracja iOS

Zdefiniuj zasoby ciągów znaków: zdefiniuj podstawowe ciągi znaków w pliku Localizable.strings (zwykle w folderze Base.lproj lub w katalogu ciągów znaków). W przypadku wartości dynamicznych używaj specyfikatorów formatu (%@, %ld itp.). Klucze są często definiowane w całości wielkimi literami zgodnie z konwencją.

Domyślny (angielski Localizable.strings):

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

Dodaj tłumaczenia: utwórz foldery .lproj dla poszczególnych języków (lub dodaj lokalizacje za pomocą katalogu ciągów znaków) i przetłumacz klucze.

Francuski (fr.lproj/Localizable.strings):

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

Więcej informacji znajdziesz w tych dokumentach:

• Lokalizacja – dokumentacja dla deweloperów Apple

• Zasoby ciągów znaków – dokumentacja Apple Developer

Krok 2. Skonstruuj ładunek wiadomości FCM

Podczas wysyłania powiadomienia za pomocą interfejsu FCM HTTP v1 serwer tworzy pojedynczy ładunek, który używa kluczy zasobów (*_loc_key) i danych dynamicznych (*_loc_args) jako tablicy ciągów znaków.

Przykład FCM ładunku HTTP w wersji 1

Klucze lokalizacji są umieszczane w blokach zastępowania specyficznych dla platformy (android.notification i 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"]
          }
        }
      }
    }
  }
}

Najważniejsze kwestie dotyczące argumentów ładunku

• Kolejność ma znaczenie: ciągi znaków w *_loc_args muszą być w dokładnej kolejności wymaganej przez symbole zastępcze w pliku zasobów ciągów znaków (np. %1$s, %2$s).

• Tylko ciągi znaków: wszystkie elementy tablicy *_loc_args muszą być ciągami znaków, nawet jeśli reprezentują liczby (np. "3" w przykładzie). Ostateczną konwersję typu na podstawie specyfikatora formatu (%ld lub %1$d) przeprowadza moduł formatowania ciągów znaków systemu operacyjnego klienta.

Krok 3. Przetwarzanie i wyświetlanie po stronie klienta

Gdy urządzenie otrzyma powiadomienie, automatycznie wykonuje te czynności:

1. Sprawdzanie języka: urządzenie określa podstawowe ustawienia regionalne użytkownika (np. niemiecki, włoski).

2. Wyszukiwanie klucza: system operacyjny używa wartości *_loc_key (welcome_title), aby wyszukać odpowiedni przetłumaczony ciąg znaków w plikach zasobów aplikacji dla lokalizacji urządzenia.

3. Wstawianie argumentów: system operacyjny pobiera tablicę z *_loc_args (["Alice"]) i wstawia wartości do zlokalizowanego ciągu znaków, uwzględniając reguły formatowania danego języka (interpunkcja, kolejność słów itp.).

Dzięki temu każdy użytkownik otrzyma wiadomość dostosowaną do jego preferencji językowych, z prawidłową strukturą językową, przy zachowaniu standardowego ładunku z serwera.

Przykład: wiadomość z powiadomieniem i opcjami lokalizacji

Ten przykładowy kod wysyła żądanie wysłania powiadomienia do tematu Tech, w tym opcje lokalizacji, aby klient mógł wyświetlać zlokalizowane wiadomości. Oto przykład efektu wizualnego na urządzeniu użytkownika:

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

Więcej informacji znajdziesz w AndroidNotification i ApnsConfig w dokumentacji referencyjnej HTTP w wersji 1. Znajdziesz tam szczegółowe informacje o kluczach dostępnych w blokach specyficznych dla platformy w treści wiadomości. Listę kluczy obsługiwanych przez APNS znajdziesz w dokumentacji kluczy ładunku Apple.