Konfigurowanie przepisywania internacjonalizacji (i18n)

Korzystaj z modyfikacji internacjonalizacji („i18n rewrites”) do wyświetlania różnych treści w zależności od kraju lub preferowanego języka użytkownika. 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 standardowe treści w języku francuskim użytkownikom, którzy wolą język francuski, ale użytkownikom z Kanady, którzy wolą język francuski, wyświetlaj treści w języku francuskim.
  Przykład: strona główna ze standardowym sformułowaniem w języku francuskim i strona główna ze sformułowaniami w języku francuskim

• 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 sformułowaniem w języku francuskim i funkcją charakterystyczną dla Kanady (np. motywem świątecznym)

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 o tematyce świątecznej lub strony 404 w wybranych 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

   Wyświetlanie żądań pasujących do treści podfolderów

   public/
       // matches requests that aren't specified by your "i18n content" subfolders
       // example: display your homepage in the "default" language for your site with no country-specific features
       index.html  // your site's default homepage
       404.html  // your site's custom 404 page
   
       localized-files/
   
           // matches requests from Canada with any language preference
           // example: display your homepage in the "default" language for your site with a Canada-specific feature
           ALL_ca/
               index.html
   
           // matches requests from any country with a language preference of `es` or `es-foo`
           // example: display your homepage in Spanish with no country-specific features
           es_ALL/
               index.html
               404.html  // your site's custom 404 page in Spanish
   
           // matches requests from any country with a language preference of `fr` or `fr-foo`
           // example: display your homepage in Standard French with no country-specific features
           fr/
               index.html
               404.html  // your site's custom 404 page in French
   
           // matches requests from Canada with a language preference of `fr` or `fr-foo`
           // example: display your homepage in Canadian French and/or with a Canada-specific feature
           fr_ca/
               index.html

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

   • languageCode_countryCode: zawiera treści przeznaczone dla użytkowników, którzy wybrali dany język, oraz 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.

   Uwaga: aby dowiedzieć się, w jakiej kolejności Hosting wyświetla pliki „treści zlokalizowanych”, zapoznaj się z poniższą listą priorytetów.

2. Dodaj atrybut i18n do pliku firebase.json i określ katalog zawierający „treści z lokalizacją”. Kontynuując nasz przykład:

   // 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 „i18n content” znajdują się w katalogu głównym katalogu public, użyj / dla wartości root. Średniki na początku i na końcu wartości root są opcjonalne.

3. Wdrożyć w witrynie Hosting treści i konfigurację związane z międzynarodową obsługą języków.

Możesz przetestować konfigurację, korzystając z zastąpienia 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/).

Funkcja Hosting pobiera kod kraju na podstawie 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 ustawionego 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 wszystkie tagi regionalne i krajowe w nagłówku Accept-Language, więc kod języka w nazwie podfolderu „treści i18n” nie może zawierać tych tagów. Na przykład nie możesz użyć es-419 ani es-US jako kodu języka w nazwie podfolderu, ale możesz użyć 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ć.

  Przykłady treści regionalnych lub krajowych

  Wyświetlanie treści w języku hiszpańskim w Hiszpanii, a nie w żadnym innym kraju (naśladowanie działania es-419)

  W tym przykładzie żądanie z Hiszpanii z ustawieniami języka es, es-es, a nawet es-419 otrzyma treść z podfolderu es_es/, ponieważ Hosting traktuje wszystkie te kody języka jako es.

  Prośba z Stanów Zjednoczonych, Meksyku lub innego kraju z ustawionymi preferencjami językowymi es-419 zostanie obsłużona przez podfolder es_ALL/, ponieważ Hosting traktuje es-419 jako es.

  public/
      // matches requests that aren't specified by your "i18n content" subfolders
      index.html  // the site's default homepage
  
      localized-files/
  
          // matches requests from Spain with a language preference of `es` or `es-foo`
          es_es/
              index.html
  
          // matches requests from any other country with a language preference of `es` or `es-foo`
          es_ALL/
              index.html

  Wyświetlanie treści w języku hiszpańskim w określonych krajach

  W tym przykładzie żądanie z Meksyku z preferowanym językiem es-419 otrzyma treści z podfolderu es_mx/, ponieważ Hosting traktuje kod języka es-419 jako es.

  Jednak w przypadku zapytania z USA z preferowanym językiem es-419 wyświetlane są treści z folderu podrzędnego es_ALL/, ponieważ Hosting traktuje es-419 jako es i nie ma folderu podrzędnego es_us/.

  public/
      // matches requests that aren't specified by your "i18n content" subfolders
      index.html  // the site's default homepage
  
      localized-files/
  
          // matches requests from Argentina with a language preference of `es` or `es-foo` (mimics behavior of `es-ar` header tag)
          es_ar/
              index.html
  
          // matches requests from Spain with a language preference of `es` or `es-foo` (mimics behavior of `es-es` header tag)
          es_es/
              index.html
  
          // matches requests from Mexico with a language preference of `es` or `es-foo` (mimics behavior of `es-mx` header tag)
          es_mx/
              index.html
  
          // matches requests from any other country with a language preference of `es` or `es-foo` (mimics behavior of `es-419` header tag)
          es_ALL/
              index.html

Kolejność priorytetów w przypadku „treści z uwzględnieniem lokalizacji”

Jeśli skonfigurujesz przepisy i18n, Hosting będzie wyświetlać treści zgodnie z następującą kolejnością priorytetową:

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ści z fr_ca/)
      Kolejność odpowiada wartościom jakości dla poszczególnych języków w nagłówku Accept-Language żądania.

   2. Tylko kod kraju (na przykład treści z: ALL_ca/)

   3. Tylko kod języka (np. treści z fr/ lub es_ALL/)
      Kolejność odpowiada wartościom jakości w każdym języku 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. Strona Niestandardowa strona 404

   3. Domyślna strona 404 (dostarcza Firebase)

Przykład kolejności priorytetu

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

• Przykład katalogu lokalnego projektu z katalogiem „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

• 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 błędów 404

Która strona zostanie wyświetlona użytkownikowi?

• Żądana strona: index.html

  Odpowiedz

  index.html z podfolderu fr_ca/

  Ponieważ funkcja Hosting najpierw przeszukuje podfolder fr_ca/, znajdzie dopasowanie ścisłe do index.html w tym podfolderze.

• Żądana strona: awesome-page.html

  Odpowiedz

  404.html z podfolderu fr/

  Hosting najpierw przeszukuje cały katalog (w tym wszystkie podkatalogi „treści i18n” i katalog główny) w kolejności priorytetów w celu znalezienia dopasowania ścisłego, ale w przypadku awesome-page.html nie ma dopasowania ścisłego.

  W związku z tym Hosting rozpocznie obsługę błędu 404, która jest zgodna z tym samym porządkiem priorytetów i18n co w przypadku wyszukiwań w dopasowaniu ścisłym. Podfolder fr/ to pierwszy podfolder, który jest przeszukany i zawiera stronę 404.

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 będzie przewijać listę priorytetów, aż znajdzie podfolder pasujący do kombinacji język-kraj żądania.

• 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/ i fr_ALL/ są równoważne z perspektywy ustawień kraju i języka użytkownika. Jeśli jednak istnieją oba podfoldery, Hosting będzie wyświetlać treści fr_ALL/ przed treścią fr/.

Zastępowanie kodów języków i krajów za pomocą plików cookie

Możesz zmienić wyświetlane treści, korzystając z plików cookie do zastępowania nagłówków związanych z krajem i językiem.

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 wdrożyć selektor języka, a potem odpowiednio ustawić plik cookie użytkownika firebase-language-override.

Aby skonfigurować zastąpienia plików cookie, ustaw pliki cookie o nazwach 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.