Định cấu hình tính năng viết lại cho quy trình quốc tế hoá (i18n)

Sử dụng tính năng viết lại quốc tế hoá ("viết lại i18n") để phân phát nội dung khác nhau tuỳ thuộc vào quốc gia hoặc ngôn ngữ ưu tiên của người dùng. Dưới đây là một số ví dụ về cấu hình mà bạn có thể thiết lập:

• Cung cấp cùng một nội dung bằng tiếng Pháp cho tất cả người dùng ưu tiên tiếng Pháp (bất kể quốc gia).
  Ví dụ: trang chủ có văn bản bằng tiếng Pháp

• Phân phát nội dung bằng tiếng Pháp tiêu chuẩn cho những người dùng thích tiếng Pháp, nhưng đối với những người dùng ở Canada thích tiếng Pháp, hãy phân phát nội dung bằng tiếng Pháp Canada.
  Ví dụ: trang chủ có cụm từ bằng tiếng Pháp chuẩn so với trang chủ có cụm từ bằng tiếng Pháp ở Canada

• Phân phát cùng một nội dung cho tất cả người dùng ở Canada (bất kể lựa chọn ưu tiên về ngôn ngữ của họ).
  Ví dụ: trang chủ có ngôn ngữ "mặc định" của trang web nhưng có một tính năng dành riêng cho Canada (chẳng hạn như chủ đề ngày lễ)

• Phân phát nội dung bằng tiếng Pháp của Canada cho những người dùng ở Canada thích tiếng Pháp.
  Ví dụ: trang chủ có cụm từ tiếng Pháp ở Canada và một tính năng dành riêng cho Canada (chẳng hạn như chủ đề ngày lễ)

Firebase Hosting xác định quốc gia của người dùng dựa trên địa chỉ IP và lựa chọn ngôn ngữ của người dùng dựa trên tiêu đề yêu cầu Accept-Language (thường là do trình duyệt web của họ tự động đặt).

Thiết lập quy tắc viết lại i18n

Để thiết lập việc viết lại i18n cho trang web Hosting, bạn cần tạo một thư mục "nội dung i18n" cho tất cả nội dung đã bản địa hoá, sau đó thêm thuộc tính i18n vào tệp firebase.json để trỏ đến thư mục "nội dung i18n" mới.

Sau đây là các bước chi tiết:

1. Trong thư mục public của ứng dụng cục bộ, hãy tạo một thư mục riêng cho "nội dung i18n", sau đó tạo các thư mục con cho từng tổ hợp ngôn ngữ và quốc gia mà trang web của bạn hỗ trợ.

   Trong mỗi thư mục con, hãy thêm nội dung dành riêng cho tổ hợp đó, chẳng hạn như trang chủ theo chủ đề ngày lễ hoặc trang 404 theo ngôn ngữ cụ thể.

   Sau đây là ví dụ về thư mục "nội dung i18n" có tên là 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

   Xem các yêu cầu trùng khớp cho nội dung của từng thư mục con

   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

   Thư mục localized-files/ chứa các thư mục con riêng biệt cho từng tổ hợp ngôn ngữ và quốc gia mà trang web của bạn hỗ trợ. Mẫu đặt tên cho mỗi thư mục con phải tuân theo một trong các định dạng sau:

   • languageCode_countryCode: Chứa nội dung dành riêng cho những người dùng có lựa chọn ngôn ngữ ưu tiên và mã quốc gia đó

   • languageCode: Chứa nội dung dành riêng cho những người dùng có lựa chọn ưu tiên ngôn ngữ đó, nhưng nội dung không dành riêng cho quốc gia; về cơ bản tương đương với languageCode_ALL

   Hãy tham khảo tiểu mục Mã quốc gia và ngôn ngữ bên dưới để biết thêm thông tin về các mã này. Bạn có thể dùng giá trị của ALL (có phân biệt chữ hoa chữ thường) để cho biết bất kỳ quốc gia nào (chẳng hạn như es_ALL/) hoặc bất kỳ ngôn ngữ nào (chẳng hạn như ALL_ca/).

   Các tệp trong một thư mục con không cần có các tệp tương tự trong thư mục public hoặc các thư mục con khác. Bạn có thể tạo nội dung hoàn toàn dành riêng cho một ngôn ngữ và/hoặc quốc gia.

2. Thêm thuộc tính i18n vào tệp firebase.json và chỉ định thư mục chứa "nội dung i18n". Tiếp tục ví dụ của chúng ta:

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

   Thư mục được chỉ định cho root phải là tên của thư mục chứa tất cả các thư mục con "nội dung i18n". Nếu bạn đặt tất cả các thư mục con "nội dung i18n" ở thư mục gốc public, hãy sử dụng / cho giá trị của root. Bạn không bắt buộc phải có dấu gạch chéo ở đầu và cuối trong giá trị root.

3. Triển khai "nội dung i18n" và cấu hình cho trang web Hosting của bạn.

Bạn có thể kiểm tra chế độ thiết lập bằng cách sử dụng cookie ghi đè.

Mã quốc gia và ngôn ngữ

Khi đặt tên cho các thư mục con "nội dung i18n", bạn phải sử dụng chữ thường cho cả mã quốc gia và mã ngôn ngữ. Bạn có thể sử dụng giá trị của ALL (có phân biệt chữ hoa chữ thường) để cho biết bất kỳ quốc gia nào (chẳng hạn như es_ALL/) hoặc bất kỳ ngôn ngữ nào (chẳng hạn như ALL_ca/).

Hosting lấy mã quốc gia từ địa chỉ IP của người dùng. Mã quốc gia là mã ISO 3166-1 alpha-2 gồm hai chữ cái.

Mã ngôn ngữ được lấy từ tiêu đề yêu cầu Accept-Language của người dùng (thường là do trình duyệt web của họ tự động đặt). Đó là mã ISO 639-1. Khi sử dụng mã ngôn ngữ, hãy lưu ý những điều sau:

• Khi Hosting tìm kiếm "nội dung i18n" để phân phát, nó sẽ sắp xếp các ngôn ngữ dựa trên giá trị chất lượng trong tiêu đề Accept-Language.

• Hosting sẽ xoá mọi thẻ phụ theo khu vực và quốc gia trong tiêu đề Accept-Language, do đó, mã ngôn ngữ trong tên thư mục con "nội dung i18n" không được chứa các thẻ phụ này. Ví dụ: bạn không thể sử dụng es-419 hoặc es-US làm mã ngôn ngữ trong tên thư mục con, nhưng bạn có thể sử dụng es.

  Nếu muốn phân phát nội dung theo khu vực hoặc quốc gia cụ thể, bạn có thể tạo các thư mục con chứa nội dung theo ngôn ngữ và quốc gia cụ thể mà bạn muốn hỗ trợ.

  Xem ví dụ để hỗ trợ nội dung theo khu vực hoặc quốc gia cụ thể

  Phục vụ nội dung bằng tiếng Tây Ban Nha áp dụng cho Tây Ban Nha so với bất kỳ quốc gia nào khác (mô phỏng hành vi của es-419)

  Trong ví dụ này, một yêu cầu từ Tây Ban Nha có lựa chọn ưu tiên ngôn ngữ là es, es-es hoặc thậm chí es-419 sẽ nhận được nội dung từ thư mục con es_es/ vì Hosting coi tất cả các mã ngôn ngữ đó là es.

  Yêu cầu từ Hoa Kỳ, Mexico hoặc bất kỳ quốc gia nào khác có lựa chọn ưu tiên về ngôn ngữ là es-419 sẽ nhận được nội dung từ thư mục con es_ALL/ vì Hosting coi es-419 là 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

  Phân phát nội dung bằng tiếng Tây Ban Nha áp dụng cho một số quốc gia

  Trong ví dụ này, một yêu cầu từ Mexico có lựa chọn ưu tiên về ngôn ngữ là es-419 sẽ nhận được nội dung từ thư mục con es_mx/ vì Hosting coi mã ngôn ngữ es-419 là es.

  Tuy nhiên, một yêu cầu từ Hoa Kỳ có lựa chọn ưu tiên ngôn ngữ là es-419 sẽ nhận được nội dung từ thư mục con es_ALL/ vì Hosting coi es-419 là es và không có thư mục con 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

Thứ tự ưu tiên cho "nội dung i18n"

Nếu bạn thiết lập các quy tắc viết lại i18n, Hosting sẽ phân phát nội dung dựa trên thứ tự ưu tiên sau:

1. Không gian tên dành riêng bắt đầu bằng một phân đoạn đường dẫn /__/*

2. Đã định cấu hình lệnh chuyển hướng

3. Nội dung tĩnh khớp chính xác

   1. Mã ngôn ngữ + Mã quốc gia (ví dụ: nội dung từ fr_ca/)
      Thứ tự tuân theo các giá trị chất lượng cho từng ngôn ngữ trong tiêu đề Accept-Language của yêu cầu.

   2. Chỉ có mã quốc gia (ví dụ: nội dung từ ALL_ca/)

   3. Chỉ mã ngôn ngữ (ví dụ: nội dung từ fr/ hoặc es_ALL/)
      Thứ tự tuân theo các giá trị chất lượng cho từng ngôn ngữ trong tiêu đề Accept-Language của yêu cầu.

   4. Nội dung tĩnh khớp chính xác "Mặc định"
      Đây là nội dung nằm ngoài thư mục "nội dung i18n", chẳng hạn như ở gốc của thư mục public.

4. Đã định cấu hình viết lại

5. Xử lý lỗi 404

   1. Trang 404 i18n
      Trang này tuân theo cùng thứ tự ưu tiên được liệt kê ở trên cho nội dung tĩnh khớp chính xác.

   2. Trang 404 tuỳ chỉnh

   3. Trang 404 mặc định (do Firebase cung cấp)

Ví dụ về thứ tự ưu tiên

Hãy tiếp tục ví dụ ở trên. Chúng ta sẽ sử dụng cùng một thư mục ví dụ và một yêu cầu ví dụ.

• Ví dụ về thư mục dự án cục bộ có thư mục "nội dung i18n" (gọi là 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

• Thông tin yêu cầu mẫu

  • Mã ngôn ngữ: fr, en (tiếng Pháp, sau đó là tiếng Anh)
    Các mã ngôn ngữ được sắp xếp dựa trên các giá trị chất lượng trong tiêu đề Accept-Language.

  • Mã quốc gia: ca (Canada)

Theo thứ tự ưu tiên khớp chính xác và các giá trị chất lượng cho lựa chọn ưu tiên về ngôn ngữ, Hosting sẽ tìm kiếm các thư mục cho một trang được yêu cầu theo thứ tự sau.

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. Xử lý lỗi 404

Người dùng sẽ được phân phát trang nào?

• Trang được yêu cầu: index.html

  Trả lời

  index.html trong thư mục con fr_ca/

  Vì Hosting tìm kiếm trong thư mục con fr_ca/ trước, nên hàm này sẽ tìm thấy kết quả khớp chính xác cho index.html trong thư mục con đó.

• Trang được yêu cầu: awesome-page.html

  Trả lời

  404.html trong thư mục con fr/

  Hosting trước tiên sẽ tìm kiếm toàn bộ thư mục (bao gồm tất cả các thư mục con "nội dung i18n" và thư mục gốc) theo thứ tự ưu tiên để tìm một kết quả khớp chính xác, nhưng không có kết quả khớp chính xác nào cho awesome-page.html.

  Vì vậy, Hosting sẽ bắt đầu xử lý lỗi 404, theo cùng thứ tự ưu tiên i18n như các cụm từ tìm kiếm khớp chính xác. Thư mục con fr/ là thư mục con đầu tiên được tìm kiếm có chứa trang 404.

Lưu ý những điều sau đây về hoạt động tìm kiếm và phân phát thư mục "nội dung i18n":

• Thư mục localized-files/ thực sự không chứa các thư mục con en_ca/, en_ALL/ hoặc en/, vì vậy Hosting sẽ chỉ bỏ qua danh sách ưu tiên cho đến khi tìm thấy một thư mục con phù hợp cho tổ hợp ngôn ngữ-quốc gia của yêu cầu.

• Mặc dù thư mục localized-files/ chứa một thư mục con es_ALL/, nhưng yêu cầu mẫu ở trên không bao gồm mã ngôn ngữ es hoặc es-foo, vì vậy Hosting sẽ không tìm kiếm "nội dung i18n" khớp với es.

• Các thư mục con có tên fr/ và fr_ALL/ tương đương nhau theo lựa chọn ưu tiên về quốc gia và ngôn ngữ của người dùng. Tuy nhiên, nếu cả hai thư mục con đều tồn tại, thì Hosting sẽ phân phát nội dung fr_ALL/ trước nội dung fr/.

Ghi đè mã ngôn ngữ và mã quốc gia bằng cookie

Bạn có thể thay đổi nội dung được phân phát bằng cách sử dụng cookie để ghi đè tiêu đề quốc gia và ngôn ngữ.

Sau đây là một số cách bạn có thể sử dụng chế độ ghi đè cookie:

• Kiểm thử một tính năng với nhiều tổ hợp ngôn ngữ/quốc gia để kiểm tra nội dung nào được phân phát.

• Cho phép người dùng thay đổi nội dung mà họ thấy. Ví dụ: bạn có thể triển khai một bộ chọn ngôn ngữ, sau đó đặt cookie firebase-language-override của người dùng cho phù hợp.

Để định cấu hình các chế độ ghi đè cookie, hãy đặt cookie bằng cả hai hoặc một trong hai tên sau: firebase-country-override và firebase-language-override. Ví dụ: đoạn mã JavaScript sau đây sẽ ghi đè mã quốc gia thành ca và tiêu đề Accept-Language thành fr,en:

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

Cookie ghi đè ngôn ngữ phải là danh sách mã ngôn ngữ được phân tách bằng dấu phẩy theo thứ tự ưu tiên, không có thẻ phụ hoặc giá trị chất lượng.

Các chế độ ghi đè cookie không được phản ánh trong nhật ký.