Konfigurowanie przepisywania internacjonalizacji (i18n)

Używaj przekształceń na potrzeby międzynarodowości („przekształceń i18n”), aby wyświetlać różne treści w zależności od kraju użytkownika lub preferowanego języka. Oto kilka przykładowych konfiguracji, które możesz skonfigurować:

  • Wyświetlaj te same treści w języku francuskim wszystkim użytkownikom, którzy preferują ten język (niezależnie od kraju).
    Przykład: strona główna z tekstem w języku francuskim

  • Wyświetlaj treści w języku francuskim standardowe użytkownikom, którzy preferują ten język, ale w przypadku użytkowników z Kanady, którzy preferują francuski, wyświetlaj treści w języku francuskim kanadyjskim.
    Przykład: strona główna z formułowaniem w języku francuskim standardowym a strona główna z formułowaniem w języku francuskim kanadyjskim

  • Wyświetlaj te same treści wszystkim użytkownikom z Kanady (niezależnie od wybranego języka).
    Przykład: strona główna w języku domyślnym witryny, ale z funkcją dostępną tylko w Kanadach (np. motyw świąteczny).

  • Wyświetlanie treści w języku francuskim (kanadyjskim) użytkownikom z Kanady, którzy preferują ten język.
    Przykład: strona główna z kanadyjskim francuskim wyrażeniem i funkcją specyficzną dla Kanady (np. motyw świąteczny)

Firebase Hosting określa kraj użytkownika na podstawie jego adresu IP, a preferencje językowe na podstawie nagłówka żądania Accept-Language (zwykle ustawiane automatycznie przez przeglądarkę).

Konfigurowanie przekierowań i18n

Aby skonfigurować przeredagowanie kodu i18n w witrynie Hosting, musisz utworzyć katalog „i18n content” zawierający wszystkie zlokalizowane treści, a następnie dodać atrybut i18n do pliku firebase.json, aby wskazać nowy katalog „i18n content”.

Oto szczegółowe instrukcje:

  1. W folderze public w lokalnym katalogu aplikacji utwórz osobny folder na „treści z lokalizacją”, a potem utwórz podfoldery dla każdej pary języka i kraju obsługiwanej przez witrynę.

    W każdym podfolderze dodaj treści odpowiednie dla danej kombinacji, np. strony główne na tematy świąteczne lub strony 404 w różnych językach.

    Oto przykład katalogu „treści i18n” o nazwie localized-files:

    public/
        index.html  // your site's default homepage
        404.html  // your site's custom 404 page
    
        localized-files/
            ALL_ca/
                index.html
            es_ALL/
                index.html
                404.html
            fr/
                index.html
                404.html
            fr_ca/
                index.html

    Katalog localized-files/ zawiera osobne podfoldery dla każdej obsługiwanej przez witrynę kombinacji języka i kraju. Wzór nazewnictwa każdego folderu podrzędnego musi być zgodny z jednym z tych formatów:

    • languageCode_countryCode: zawiera treści przeznaczone dla użytkowników, którzy mają wybrany ten język i ten kod kraju.

    • languageCode: zawiera treści przeznaczone dla użytkowników, którzy wybrali dany język, ale nie są związane z konkretnym krajem; w zasadzie jest to odpowiednik languageCode_ALL

    Więcej informacji o tych kodach znajdziesz w sekcji Kody krajów i języków. Wartość ALL (z rozróżnianiem wielkości liter) może wskazywać dowolny kraj (np. es_ALL/) lub dowolny język (np. ALL_ca/).

    Pliki w podfolderze nie muszą mieć analogicznych plików w katalogu public ani w innych podfolderach. Możesz tworzyć treści, które są przeznaczone wyłącznie dla określonego języka lub kraju.

  2. Dodaj atrybut i18n do pliku firebase.json i wskaż katalog zawierający „treść i18n”. W nawiązaniu do naszego przykładu:

    // firebase.json
    
    "hosting": {
    
      "public": "public",
    
      "ignore": [
        "firebase.json",
        "**/.*",
        "**/node_modules/**"
      ],
    
      "i18n": {
        "root": "/localized-files"  // directory that contains your "i18n content"
      }
    
      ...
    }

    Katalog podany w przypadku parametru root musi być nazwą katalogu zawierającego wszystkie podkatalogi „treści i18n”. Jeśli wszystkie podfoldery „tłumaczenie” umieścisz w katalogu głównym public, użyj wartości / dla root. Ukośniki na początku i na końcu wartości root są opcjonalne.

  3. Wdróż i skonfiguruj „treść i18n” w swojej witrynie Hosting.

Konfigurację możesz przetestować, używając zastępowania plików cookie.

Kody krajów i języków

Gdy nazywamy podfoldery „i18n content”, musisz używać małych liter zarówno w kodach kraju, jak i języka. Wartość ALL (z rozróżnianiem wielkości liter) może wskazywać dowolny kraj (np. es_ALL/) lub dowolny język (np. ALL_ca/).

Hosting pobiera kod kraju z adresu IP użytkownika. Kody krajów to dwuliterowe kody ISO 3166-1 alfa-2.

Kody języków są pobierane z nagłówka żądania Accept-Language użytkownika (zwykle ustawiane automatycznie przez przeglądarkę). Są to kody ISO 639-1. Podczas korzystania z kodów języków pamiętaj o tych uwagach:

  • Gdy Hosting wyszukuje, jakie „treści w języku i18n” ma wyświetlić, sortuje języki według wartości jakości w nagłówku Accept-Language.

  • Hosting usuwa w nagłówku Accept-Language wszystkie subtagi regionalne i krajowe, więc kod języka w nazwie podfolderu „i18n content” nie może zawierać tych subtagów. Nie możesz na przykład użyć kodu języka es-419 ani es-US w nazwie podfolderu, ale możesz użyć kodu es.

    Jeśli chcesz wyświetlać treści dla określonego regionu lub kraju, możesz utworzyć podfoldery zawierające treści w określonym języku i kraju, które chcesz obsługiwać.

Priorytet dla „treści i18n”

Jeśli skonfigurujesz przekształcenia treści w wielu językach, Hosting będzie wyświetlać treści w następującej kolejności:

  1. Zarezerwowane przestrzenie nazw, które zaczynają się od segmentu ścieżki /__/*

  2. Skonfigurowane przekierowania

  3. Treści statyczne z dopasowaniem ścisłym

    1. Kod języka + kod kraju (np. treść z: fr_ca/)
      Zamówienie jest zgodne z wartościami dotyczącymi jakości dla każdego języka, które są podane w nagłówku Accept-Language żądania.

    2. Tylko kod kraju (np. ALL_ca/)

    3. Tylko kod języka (np. treści z języków: fr/ lub es_ALL/)
      Kolejność jest zgodna z wartościami dotyczącymi jakości dla każdego języka podanymi w nagłówku Accept-Language żądania.

    4. „Domyślne” treści statyczne z dopasowaniem dokładnym
      Treści te znajdują się poza katalogiem „Treści i18n”, na przykład w katalogu głównym public.

  4. Skonfigurowane przekierowania

  5. Obsługa błędów 404

    1. strony 404 w języku i18n
      . Są one wyświetlane w tym samym porządku priorytetów, co treści statyczne z dopasowaniem do wyrażenia dokładnego.

    2. Niestandardowa strona 404

    3. Domyślna strona 404 (dostarcza Firebase)

Przykład kolejności priorytetów

Wróćmy do przykładu z powyżej. Użyjemy tego samego katalogu przykładowego i przykładowego żądania.

  • Przykładowy katalog lokalnego projektu z katalogiem „i18n content” (o nazwie localized-files)

    public/
        index.html  // your site's default homepage
        404.html  // your site's custom 404 page
    
        localized-files/
            ALL_ca/
                index.html
            es_ALL/
                index.html
                404.html
            fr/
                index.html
                404.html
            fr_ca/
                index.html
  • Przykładowe informacje o żądaniu

    • Kody języków: fr, en (francuski, potem angielski)
      Kody języków są uporządkowane według wartości jakości w nagłówku Accept-Language.

    • Kod kraju: ca (Kanada)

Zgodnie z kolejnością priorytetów dopasowania ścisłego i wartościami jakości dla preferencji językowych Hosting będzie wyszukiwać żądane strony w katalogach w tej kolejności:

  1. public/localized-files/fr_ca/

  2. public/localized-files/en_ca/

  3. public/localized-files/ALL_ca/

  4. public/localized-files/fr_ALL/

  5. public/localized-files/fr/

  6. public/localized-files/en_ALL/

  7. public/localized-files/en/

  8. public/

  9. Obsługa 404

Która strona będzie wyświetlana użytkownikowi?

  • Żądana strona: index.html

  • Żądana strona: awesome-page.html

Pamiętaj o tych kwestiach dotyczących wyszukiwania i obsługi katalogu „Treści w języku i18n”:

  • Katalog localized-files/ nie zawiera podfolderów en_ca/, en_ALL/ ani en/, więc Hosting po prostu przeskoczy listę priorytetową, dopóki nie znajdzie podfolderu pasującego do kombinacji języka i kraju w żądaniu.

  • Mimo że katalog localized-files/ zawiera podfolder es_ALL/, przykładowe żądanie powyżej nie zawiera kodu języka es ani es-foo, więc Hosting nie wyszukuje hasła „i18n content”, które pasuje do wyrażenia es.

  • Foldery podrzędne o nazwach fr/fr_ALL/ są równoważne z perspektywy ustawień kraju i języka użytkownika. Jeśli jednak oba podfoldery istnieją, Hosting wyświetli treści fr_ALL/ przed treściami fr/.

Za pomocą plików cookie możesz zmienić wyświetlane treści, aby zastąpić nagłówki kraju i języka.

Oto kilka sposobów korzystania z zastąpień plików cookie:

  • Przetestuj funkcję z różnymi kombinacjami języka i kraju, aby sprawdzić, jakie treści są wyświetlane.

  • Pozwól użytkownikom zmieniać wyświetlane treści. Możesz na przykład zaimplementować selektor języka, a następnie odpowiednio ustawić plik cookie firebase-language-override użytkownika.

Aby skonfigurować zastąpienia plików cookie, ustaw pliki cookie o jednej z tych nazw: firebase-country-override i firebase-language-override. Na przykład ten fragment kodu JavaScript zastępuje kod kraju wartością ca, a nagłówek Accept-Language – wartością fr,en:

document.cookie = "firebase-country-override=ca";
document.cookie = "firebase-language-override=fr,en";

Zastąpienia plików cookie dotyczące języka muszą być rozdzielone przecinkami listą kodów języków w kolejności preferencji bez podtagów ani wartości jakości.

Zastępowanie plików cookie nie jest widoczne w logach.