Konfigurowanie przepisywania internacjonalizacji (i18n)

Używaj przepisów na internacjonalizację („przepisy 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 ustawić:

• Wyświetlanie tych samych 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świetlanie treści w standardowym języku francuskim użytkownikom, którzy go preferują, ale w przypadku użytkowników z Kanady preferujących język francuski wyświetlanie treści w kanadyjskiej odmianie tego języka.
  Przykład: strona główna z treścią w standardowym języku francuskim i strona główna z treścią w kanadyjskiej odmianie tego języka.

• Wyświetlanie tych samych treści wszystkim użytkownikom z Kanady (niezależnie od preferowanego języka).
  Przykład: strona główna w „domyślnym” języku witryny, ale z funkcją dostępną tylko w Kanadzie (np. motyw świąteczny).

• Wyświetlanie treści w kanadyjskiej odmianie języka francuskiego użytkownikom z Kanady, którzy preferują ten język.
  Przykład: strona główna z treścią w kanadyjskiej odmianie języka francuskiego i funkcją dostępną tylko w Kanadzie (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 ustawianego automatycznie przez przeglądarkę internetową).

Konfigurowanie przepisów i18n

Aby skonfigurować przepisy i18n w witrynie Hosting, musisz utworzyć katalog "i18n content" na potrzeby wszystkich zlokalizowanych treści, a następnie dodać atrybut i18ndo pliku firebase.json, aby wskazywał on nowy katalog "i18n content".

Oto szczegółowe instrukcje:

1. W folderze public lokalnego katalogu aplikacji utwórz osobny katalog na potrzeby „i18n content”, a następnie utwórz podfoldery dla każdej kombinacji języka i kraju obsługiwanej przez witrynę.

   W każdym podfolderze dodaj treści odpowiednie dla danej kombinacji, np. strony główne z motywem świątecznym lub strony 404 w określonym języku.

   Oto przykład katalogu „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

   Wyświetlanie pasujących żądań dotyczących treści w każdym podfolderze

   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 kombinacji języka i kraju obsługiwanej przez witrynę. Nazwa każdego podfolderu musi być zgodna z jednym z tych formatów:

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

   • languageCode: zawiera treści przeznaczone dla użytkowników, którzy mają preferencje językowe, ale treści nie są specyficzne dla danego kraju. Jest to odpowiednik languageCode_ALL.

   Więcej informacji o tych kodach znajdziesz w podsekcji Kody krajów i języków poniżej. Możesz użyć wartości ALL (z uwzględnieniem wielkości liter), aby wskazać 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ą w całości specyficzne dla danego języka lub kraju.

2. Dodaj atrybut i18n do pliku firebase.json i określ katalog, który zawiera „i18n content”. 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 określony w przypadku root musi być nazwą katalogu, który zawiera wszystkie podfoldery „i18n content”. Jeśli wszystkie podfoldery „i18n content” znajdują się w katalogu głównym public, użyj / jako wartości root. Ukośniki na początku i na końcu wartości root są opcjonalne.

3. Wdróż "i18n content" i konfigurację w witrynie Hosting.

Możesz przetestować konfigurację za pomocą zastępowania plików cookie.

Kody krajów i języków

Podczas nazywania podfolderów „i18n content” musisz używać małych liter zarówno w przypadku kodu kraju, jak i kodu języka. Możesz użyć wartości ALL (z uwzględnieniem wielkości liter), aby wskazać 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 ustawianego automatycznie przez przeglądarkę internetową). Są to kody ISO 639-1. Korzystając z kodów języków, pamiętaj o tych kwestiach:

• Gdy Hosting szuka „i18n content”, które ma udostępnić, porządkuje języki na podstawie wartości jakości w Accept-Language nagłówku.

• Hosting usuwa wszystkie podtagi regionalne i krajowe w nagłówku Accept-Language, więc kod języka w nazwie podfolderu "i18n content" nie może zawierać tych podtagó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 udostępniać treści specyficzne dla regionu lub kraju, możesz utworzyć podfoldery zawierające treści w określonym języku i kraju.

  Przykłady obsługi treści specyficznych dla regionu lub kraju

  Wyświetlanie treści w języku hiszpańskim obowiązujących w Hiszpanii, a nie w żadnym innym kraju (naśladuj zachowanie es-419)

  W tym przykładzie żądanie z Hiszpanii z preferencjami językowymi es, es-es lub nawet es-419 otrzyma treści z es_es/ podfolderu, ponieważ Hosting traktuje wszystkie te kody języków jako es.

  Żądanie ze Stanów Zjednoczonych, Meksyku lub innego kraju z preferencjami językowymi es-419 otrzyma treści z es_ALL/ podfolderu, 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 obowiązujących w określonych krajach

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

  Jednak żądanie ze Stanów Zjednoczonych z preferencjami językowymi es-419 otrzyma treści z podfolderu es_ALL/, ponieważ Hosting traktuje es-419 jako es i nie ma podfolderu 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 „i18n content”

Jeśli skonfigurujesz przepisy i18n, Hosting będzie wyświetlać treści w tej kolejności priorytetów:

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

2. Skonfigurowane przekierowania

3. Treści statyczne w dopasowaniu ścisłym.

   1. Kod języka + kod kraju (np. treści z fr_ca/)
      Kolejność jest zgodna z wartościami jakości dla każdego języka w nagłówku Accept-Language żądania.

   2. Tylko kod kraju (np. treści z ALL_ca/).

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

   4. „Domyślne” treści statyczne w dopasowaniu ścisłym.
      Są to treści znajdujące się poza katalogiem „i18n content”, np. w katalogu głównym public directory.

4. Skonfigurowane przepisy

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

   1. Strony 404 i18n
      Obowiązuje ta sama kolejność priorytetów co w przypadku treści statycznych w dopasowaniu ścisłym.

   2. Niestandardowa strona 404.

   3. Domyślna strona 404 (udostępniana przez Firebase).

Przykład kolejności priorytetów

Kontynuujmy przykład z powyższej sekcji. Użyjemy tego samego przykładowego katalogu i przykładowego żądania.

• Przykładowy projekt lokalny 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 (najpierw francuski, potem angielski)
    Kody języków są uporządkowane na podstawie wartości jakości w Accept-Language nagłówku.

  • Kod kraju: ca (Kanada).

Zgodnie z kolejnością priorytetów w dopasowaniu ścisłym i wartościami jakości dla preferencji językowych Hosting będzie przeszukiwać katalogi pod kątem żądanej strony 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.

  Odpowiedź

  index.html z podfolderu fr_ca/.

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

• Żądana strona: awesome-page.html.

  Odpowiedź

  404.html z podfolderu fr/.

  Hosting najpierw przeszukuje cały katalog (w tym wszystkie podfoldery „i18n content” i katalog główny) w kolejności priorytetów pod kątem dopasowania ścisłego, ale nie znajduje dopasowania ścisłego do awesome-page.html.

  Dlatego Hosting rozpocznie obsługę błędów 404, która jest zgodna z tą samą kolejnością priorytetów i18n co w przypadku wyszukiwań w dopasowaniu ścisłym. Podfolder fr/ jest pierwszym przeszukiwanym podfolderem, który zawiera stronę 404.

Pamiętaj o tych kwestiach dotyczących wyszukiwania i wyświetlania katalogu „i18n content”:

• Katalog localized-files/ nie zawiera podfolderów en_ca/, en_ALL/ ani en/, więc Hosting pominie je i przejdzie do następnego podfolderu na liście priorytetów, aż znajdzie podfolder pasujący 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 będzie szukać „i18n content” pasującego do es.

• Podfoldery o nazwach fr/ i fr_ALL/ są równoważne z punktu widzenia preferencji językowych i krajowych użytkownika. Jeśli jednak oba podfoldery istnieją, Hosting wyświetli treści z fr_ALL/ przed treściami z fr/.

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

Możesz zmienić wyświetlane treści, używając plików cookie do zastępowania nagłówków kraju i języka.

Oto kilka sposobów użycia zastępowania plików cookie:

• Testowanie funkcji z różnymi kombinacjami języka i kraju, aby sprawdzić, które treści są wyświetlane.

• Umożliwianie użytkownikom zmiany wyświetlanych treści. Możesz na przykład wdrożyć selektor języka, a następnie odpowiednio ustawić plik cookie firebase-language-override użytkownika.

Aby skonfigurować zastępowanie plików cookie, ustaw pliki cookie z tymi nazwami lub jedną z nich: firebase-country-override i firebase-language-override. Na przykład ten fragment kodu JavaScript zastępuje kod kraju na ca, a nagłówek Accept-Language na fr,en:

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

Zastępowanie plików cookie języka musi być listą kodów języków oddzielonych przecinkami w kolejności preferencji, bez podtagów i wartości jakości.

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