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:

  1. 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
    

    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.

  2. 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.

  3. 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.

Urutan prioritas untuk "konten i18n"

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

  1. Namespace yang dicadangkan yang dimulai dengan segmen jalur /__/*

  2. Pengalihan yang dikonfigurasi

  3. 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.

  4. Penulisan ulang yang dikonfigurasi

  5. 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.

  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. Penanganan 404

Halaman mana yang akan ditayangkan kepada pengguna?

  • Halaman yang diminta: index.html

  • Halaman yang diminta: awesome-page.html

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.