Jika Anda membangun aplikasi Angular atau Next.js yang dirender server, lihat Firebase App Hosting generasi berikutnya, sebuah solusi full stack untuk framework web modern.

Mengonfigurasi penulisan ulang internasionalisasi (i18n)

Gunakan penulisan ulang internasionalisasi ("penulisan ulang i18n") untuk menayangkan konten yang berbeda bergantung pada negara atau bahasa pilihan pengguna. Berikut adalah beberapa contoh konfigurasi yang dapat Anda siapkan:

Menayangkan konten berbahasa Prancis yang sama kepada semua pengguna yang memilih bahasa Prancis (apa pun negaranya).
Contoh: halaman beranda dengan teks berbahasa Prancis
Menayangkan konten berbahasa Prancis Standar kepada pengguna yang memilih bahasa Prancis, tetapi untuk pengguna Kanada yang memilih bahasa Prancis, tayangkan konten berbahasa Prancis Kanada.
Contoh: halaman beranda dengan frasa berbahasa Prancis Standar versus halaman beranda dengan frasa berbahasa Prancis Kanada
Menayangkan konten yang sama kepada semua pengguna Kanada (terlepas dari preferensi bahasanya).
Contoh: halaman beranda dengan bahasa "default" situs Anda tetapi dengan fitur khusus Kanada (seperti tema liburan)
Menayangkan konten berbahasa Prancis Kanada kepada pengguna Kanada yang memilih bahasa Prancis.
Contoh: halaman beranda dengan frasa berbahasa Prancis Kanada dan fitur khusus Kanada (seperti tema liburan)

Firebase Hosting menentukan negara pengguna dari alamat IP dan preferensi bahasa pengguna dari header permintaan Accept-Language (biasanya disetel secara otomatis oleh browser web).

Menyiapkan penulisan ulang i18n

Untuk menyiapkan penulisan ulang i18n di situs Hosting, Anda perlu membuat direktori "konten i18n" untuk semua konten yang dilokalkan, lalu menambahkan atribut i18n ke file firebase.json agar mengarah ke direktori "konten i18n" baru Anda.

Berikut adalah langkah-langkah detailnya:

Dalam folder public direktori aplikasi lokal Anda, buat direktori terpisah untuk "konten i18n", lalu buat subfolder untuk setiap kombinasi bahasa dan negara yang didukung oleh situs Anda.

Di setiap subfolder, tambahkan konten yang khusus untuk kombinasi tersebut, seperti halaman beranda bertema liburan atau halaman 404 dalam bahasa tertentu.

Berikut adalah contoh direktori "konten i18n" yang disebut 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

Menampilkan permintaan yang sesuai untuk konten setiap subfolder

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

Direktori localized-files/ berisi subfolder terpisah untuk setiap kombinasi bahasa dan negara yang didukung oleh situs Anda. Pola penamaan setiap subfolder harus mengikuti salah satu format berikut:

languageCode_countryCode: Berisi konten yang khusus untuk pengguna yang memiliki preferensi bahasa dan kode negara tersebut
languageCode: Berisi konten yang khusus untuk pengguna yang memiliki preferensi bahasa tersebut, tetapi kontennya tidak khusus untuk negara tertentu; pada dasarnya setara dengan languageCode_ALL

Baca subbagian Kode negara dan bahasa di bawah untuk mengetahui detail selengkapnya tentang kode ini. Anda dapat menggunakan nilai ALL (peka huruf besar/kecil) untuk menunjukkan negara mana pun (misalnya es_ALL/) atau bahasa apa pun (misalnya ALL_ca/).

File dalam subfolder tidak perlu memiliki file yang sepadan dalam direktori public atau subfolder lainnya. Anda dapat membuat konten yang sepenuhnya spesifik untuk bahasa dan/atau negara tertentu.

Tambahkan atribut i18n ke file firebase.json dan tentukan direktori yang berisi "konten i18n" Anda. Melanjutkan contoh kita di atas:
```
// firebase.json

"hosting": {

  "public": "public",

  "ignore": [
    "firebase.json",
    "**/.*",
    "**/node_modules/**"
  ],

  "i18n": {
    "root": "/localized-files"  // directory that contains your "i18n content"
  }

  ...
}
```
Direktori yang ditentukan untuk root harus berupa nama direktori yang berisi semua subfolder "konten i18n". Jika Anda menempatkan semua subfolder "konten i18n" di root direktori public Anda, gunakan / untuk nilai root. Garis miring di awal dan di akhir dalam nilai root bersifat opsional.
Deploy konfigurasi dan "konten i18n" ke situs Hosting Anda.

Anda dapat menguji penyiapan menggunakan penggantian cookie.

Kode negara dan bahasa

Saat menamai subfolder "konten i18n", Anda harus menggunakan huruf kecil baik untuk kode negara maupun bahasa. Anda bisa menggunakan nilai ALL (peka huruf besar/kecil) untuk menunjukkan negara mana pun (misalnya es_ALL/) atau bahasa apa pun (misalnya ALL_ca/).

Hosting mendapatkan kode negara dari alamat IP pengguna. Kode negara berupa kode ISO 3166-1 alpha-2 yang terdiri dari dua huruf.

Kode bahasa didapatkan dari header permintaan Accept-Language pengguna (biasanya disetel secara otomatis oleh browser web). Kode bahasa berupa kode ISO 639-1. Perhatikan hal-hal berikut saat menggunakan kode bahasa:

Saat menelusuri "konten i18n" mana yang akan ditayangkan, Hosting mengurutkan bahasa berdasarkan nilai kualitas dalam header Accept-Language.
Hosting akan menghilangkan subtag regional dan negara di header Accept-Language, sehingga kode bahasa dalam nama subfolder "konten i18n" tidak boleh berisi subtag ini. Misalnya, Anda tidak dapat menggunakan es-419 atau es-US sebagai kode bahasa dalam nama subfolder, tetapi Anda dapat menggunakan es.

Jika ingin menayangkan konten untuk wilayah atau negara tertentu, Anda dapat membuat subfolder yang berisi konten untuk bahasa-negara tertentu yang ingin didukung.
Lihat contoh guna mendukung konten untuk negara atau wilayah tertentu
Menayangkan konten berbahasa Spanyol yang berlaku untuk Spanyol versus negara lain mana pun (yang meniru perilaku es-419)

Dalam contoh ini, permintaan dari Spanyol dengan preferensi bahasa es, es-es, atau bahkan es-419 akan menerima konten dari subfolder es_es/ karena Hosting memperlakukan semua kode bahasa tersebut sebagai es.

Permintaan dari Amerika Serikat, Meksiko, atau negara lainnya dengan preferensi bahasa es-419 akan menerima konten dari subfolder es_ALL/ karena Hosting memperlakukan es-419 sebagai 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
```
Menayangkan konten berbahasa Spanyol yang berlaku untuk negara tertentu

Dalam contoh ini, permintaan dari Meksiko yang memiliki preferensi bahasa es-419 akan menerima konten dari subfolder es_mx/ karena Hosting memperlakukan kode bahasa es-419 sebagai es.

Namun, permintaan dari Amerika Serikat yang memiliki preferensi bahasa es-419 akan menerima konten dari subfolder es_ALL/ karena Hosting memperlakukan es-419 sebagai es dan tidak ada subfolder 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
```

Urutan prioritas untuk "konten i18n"

Jika Anda menyiapkan penulisan ulang i18n, Hosting akan menayangkan konten berdasarkan urutan prioritas berikut:

Namespace yang dicadangkan yang dimulai dengan segmen jalur /__/*
Pengalihan yang dikonfigurasi
Konten statis pencocokan persis
1. Kode bahasa + Kode negara (contohnya, konten dari fr_ca/)
  Urutan mengikuti nilai kualitas untuk setiap bahasa di header Accept-Language permintaan.
2. Khusus kode negara (misalnya, konten dari ALL_ca/)
3. Khusus kode bahasa (misalnya, konten dari fr/ atau es_ALL/)
  Urutan mengikuti nilai kualitas untuk setiap bahasa di header Accept-Language permintaan.
4. Konten statis pencocokan persis "default"
  Ini adalah konten yang berada di luar direktori "konten i18n", seperti di root direktori public.
Penulisan ulang yang dikonfigurasi
Penanganan 404
1. Halaman 404 i18n
  Ini mengikuti urutan prioritas yang sama dengan yang dicantumkan di atas untuk konten statis pencocokan persis.
2. Halaman 404 kustom
3. Halaman 404 default (disediakan oleh Firebase)

Contoh urutan prioritas

Mari lanjutkan contoh di atas. Kita akan menggunakan direktori contoh dan permintaan contoh yang sama.

Contoh direktori project lokal dengan direktori "konten i18n" (disebut 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

Contoh informasi permintaan
- Kode bahasa: fr, en (Prancis, kemudian Inggris)
  Kode bahasa diurutkan berdasarkan nilai kualitas di header Accept-Language.
- Kode negara: ca (Kanada)

Berdasarkan urutan prioritas pencocokan persis dan nilai kualitas untuk preferensi bahasa, Hosting akan menelusuri direktori untuk halaman yang diminta dalam urutan berikut.

public/localized-files/fr_ca/
public/localized-files/en_ca/
public/localized-files/ALL_ca/
public/localized-files/fr_ALL/
public/localized-files/fr/
public/localized-files/en_ALL/
public/localized-files/en/
public/
Penanganan 404

Halaman mana yang akan ditayangkan kepada pengguna?

Halaman yang diminta: index.html

Jawaban

index.html dari subfolder fr_ca/

Karena menelusuri subfolder fr_ca/ terlebih dahulu, Hosting akan menemukan pencocokan persis untuk index.html di subfolder tersebut.
Halaman yang diminta: awesome-page.html

Jawaban

404.html dari subfolder fr/

Hosting akan menelusuri seluruh direktori (termasuk semua subfolder "konten i18n" dan direktori utama) dalam urutan prioritas untuk pencocokan persis terlebih dahulu, tetapi tidak ada pencocokan persis untuk awesome-page.html.

Jadi, Hosting akan memulai penanganan 404-nya, yang mengikuti urutan prioritas i18n yang sama dengan penelusuran pencocokan persis. Subfolder fr/ adalah subfolder pertama yang ditelusuri yang berisi halaman 404.

Harap perhatikan hal berikut terkait penelusuran dan penayangan direktori "konten i18n":

Direktori localized-files/ sebenarnya tidak berisi subfolder en_ca/, en_ALL/, atau en/, sehingga Hosting hanya akan melewati daftar prioritas hingga menemukan subfolder yang cocok untuk kombinasi bahasa-negara permintaan.
Meskipun direktori localized-files/ berisi subfolder es_ALL/, contoh permintaan di atas tidak menyertakan kode bahasa es atau es-foo, sehingga Hosting tidak akan menelusuri "konten i18n" yang cocok dengan es.
Subfolder bernama fr/ dan fr_ALL/ dianggap setara dari sudut pandang preferensi negara dan bahasa pengguna. Namun, jika kedua subfolder ada, Hosting akan menayangkan konten fr_ALL/ sebelum konten fr/.

Anda dapat mengubah konten yang ditayangkan menggunakan cookie untuk mengganti header negara dan bahasa.

Berikut adalah beberapa cara untuk menggunakan penggantian cookie:

Uji fitur dengan kombinasi bahasa/negara yang berbeda untuk memeriksa konten mana yang ditayangkan.
Mungkinkan pengguna Anda untuk mengubah konten yang dilihatnya. Misalnya, Anda dapat menerapkan alat pilih bahasa, lalu menyetel cookie firebase-language-override pengguna dengan semestinya.

Untuk mengonfigurasi penggantian cookie, setel cookie dengan kedua atau salah satu dari nama ini: firebase-country-override dan firebase-language-override. Misalnya, cuplikan kode JavaScript berikut akan mengganti kode negara menjadi ca dan header Accept-Language menjadi fr,en:

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

Penggantian cookie bahasa harus berupa daftar kode bahasa yang dipisahkan koma sesuai urutan preferensi, tanpa subtag atau nilai kualitas.

Penggantian cookie tidak tercermin dalam log.