다국어 지원(i18n) 재작성 구성

다국어 지원 재작성('i18n 재작성')을 사용하여 사용자의 국가 또는 선호 언어에 따라 서로 다른 콘텐츠를 제공할 수 있습니다. 설정 가능한 구성 예시는 다음과 같습니다.

• 국가에 관계없이 프랑스어를 선호하는 모든 사용자에게 동일한 프랑스어 콘텐츠를 제공합니다.
  예: 프랑스어 텍스트로 표시된 홈페이지

• 프랑스어를 선호하는 사용자에게는 표준 프랑스어 콘텐츠를 제공하고, 프랑스어를 선호하는 캐나다인 사용자에게는 대신 캐나다 프랑스어 콘텐츠를 제공합니다.
  예: 표준 프랑스어 문구로 표시된 홈페이지와 캐나다 프랑스어 문구로 표시된 홈페이지

• 언어 설정과 관계없이 모든 캐나다 사용자에게 동일한 콘텐츠를 제공합니다.
  예: 사이트의 '기본' 언어로 표시되지만 캐나다 특정 기능(예: 휴일 테마)이 포함된 홈페이지

• 프랑스어를 선호하는 캐나다인 사용자에게 캐나다 프랑스어 콘텐츠를 제공합니다.
  예: 캐나다 프랑스어 문구로 표시되고 캐나다 특정 기능(예: 휴일 테마)이 포함된 홈페이지

Firebase Hosting은 IP 주소로부터 사용자의 국가를 확인하고, 일반적으로 웹브라우저에서 자동으로 설정되는 Accept-Language 요청 헤더로부터 사용자의 언어 환경설정을 확인합니다.

i18n 재작성 설정

Hosting 사이트에 i18n 재작성을 설정하려면 모든 현지화 콘텐츠에 대해 'i18n 콘텐츠' 디렉터리를 만든 후 새로운 'i18n 콘텐츠' 디렉터리를 가리키도록 i18n 속성을 firebase.json 파일에 추가해야 합니다.

자세한 단계는 다음과 같습니다.

1. 로컬 앱 디렉터리의 public 폴더 내에서 'i18n 콘텐츠'를 위해 개별 디렉터리를 만든 후 사이트에서 지원되는 각 언어와 국가의 조합에 대한 하위 폴더를 만듭니다.

   각 하위 폴더에서 휴일 테마 홈페이지 또는 언어별 404 페이지와 같은 조합별 특정 콘텐츠를 추가합니다.

   다음은 localized-files라는 'i18n 콘텐츠' 디렉터리 예시입니다.

   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

   각 하위 폴더 콘텐츠와 일치하는 요청 보기

   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

   localized-files/ 디렉터리에는 해당 사이트에서 지원되는 각 언어-국가 조합에 대한 개별 하위 폴더가 포함되어 있습니다. 각 하위 폴더의 이름 지정 패턴은 다음 형식을 따라야 합니다.

   • languageCode_countryCode: 해당 언어 환경설정 및 해당 언어 코드를 갖고 있는 사용자에 해당하는 콘텐츠를 포함합니다.

   • languageCode: 언어 환경설정을 갖고 있는 사용자에 해당하는 콘텐츠를 포함하지만, 콘텐츠가 해당 국가에 해당하지 않고, 기본적으로 languageCode_ALL과 동일합니다.

   이러한 코드에 대한 자세한 내용은 아래에서 국가 및 언어 코드를 참조하세요. ALL 값(대소문자 구분)을 사용하여 모든 국가(예: es_ALL/) 또는 모든 언어(예: ALL_ca/)를 나타낼 수 있습니다.

   하위 폴더의 파일은 public 디렉터리 또는 다른 하위 폴더에 동일한 파일을 포함할 필요가 없습니다. 특정 언어 또는 국가에만 전적으로 해당되는 콘텐츠를 만들 수 있습니다.

2. i18n 속성을 firebase.json 파일에 추가하고 'i18n 콘텐츠'가 포함된 디렉터리를 지정합니다. 예시를 계속 진행합니다.

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

   root에 지정된 디렉터리는 모든 'i18n 콘텐츠' 하위 폴더를 포함하는 디렉터리의 이름이어야 합니다. public 디렉터리의 루트에 모든 'i18n 콘텐츠' 하위 폴더를 둔 경우 /를 root 값으로 사용합니다. root 값의 선행 및 후행 슬래시는 선택사항입니다.

3. 'i18n 콘텐츠' 및 구성을 Hosting 사이트에 배포합니다.

쿠키 재정의를 사용하여 설정을 테스트할 수 있습니다.

국가 및 언어 코드

'i18n 콘텐츠' 하위 폴더 이름을 지정할 때는 국가 및 언어 코드 모두에 소문자를 사용해야 합니다. ALL 값(대소문자 구분)을 사용하여 모든 국가(예: es_ALL/) 또는 모든 언어(예: ALL_ca/)를 나타낼 수 있습니다.

Hosting은 사용자의 IP 주소에서 국가 코드를 가져옵니다. 국가 코드는 2자로 구성된 ISO 3166-1 알파-2 코드입니다.

언어 코드는 사용자의 Accept-Language 요청 헤더(일반적으로 웹브라우저에서 자동으로 설정됨)로부터 가져옵니다. ISO 639-1 코드입니다. 언어 코드를 사용할 때는 다음 사항에 유의하세요.

• 제공할 'i18n 콘텐츠'를 검색할 때 Hosting은 Accept-Language 헤더에 있는 품질 값을 기준으로 언어 순서를 지정합니다.

• Hosting이 모든 리전 및 국가 하위 태그를 Accept-Language 헤더에서 삭제하므로, 'i18n 콘텐츠' 하위 폴더 이름의 언어 코드는 이러한 하위 태그를 포함할 수 없습니다. 예를 들어 es-419 또는 es-US를 하위 폴더 이름에 언어 코드로 사용할 수 없지만 es를 사용할 수 있습니다.

  특정 리전 또는 국가 콘텐츠를 제공하려면 지원하려는 특정 언어-국가 콘텐츠가 포함된 하위 폴더를 만들 수 있습니다.

  특정 리전 또는 국가 콘텐츠를 지원하기 위한 예시 보기

  스페인에 적용 가능한 스페인어 콘텐츠 제공과 모든 다른 국가 콘텐츠 제공 비교(es-419 동작 모방)

  이 예시에서 언어 환경설정이 es, es-es 또는 심지어 es-419인 스페인에서의 요청에는 Hosting이 모든 언어 코드를 es로 취급하기 때문에 es_es/ 하위 폴더의 콘텐츠가 수신됩니다.

  미국, 멕시코 또는 언어 환경설정이 es-419인 다른 국가에서의 요청에는 Hosting이 es-419를 es 취급하기 때문에 es_ALL/ 하위 폴더의 콘텐츠가 수신됩니다.

  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

  특정 국가에 적용 가능한 스페인어 콘텐츠 제공

  이 예시에서 언어 환경설정이 es-419인 멕시코에서의 요청에는 Hosting이 언어 코드 es-419를 es로 취급하기 때문에 es_mx/ 하위 폴더의 콘텐츠가 수신됩니다.

  하지만 언어 환경설정이 es-419인 미국에서의 요청에는 Hosting이 es-419를 es로 취급하고 그리고 es_us/ 하위 폴더가 없기 때문에 es_ALL/ 하위 폴더의 콘텐츠가 수신됩니다.

  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

'i18n 콘텐츠'의 우선순위 순서

i18n 재작성을 설정할 경우 Hosting은 다음 우선순위 순서에 따라 콘텐츠를 제공합니다.

1. /__/* 경로 세그먼트로 시작하는 예약된 네임스페이스

2. 구성된 리디렉션

3. 일치검색 정적 콘텐츠

   1. 언어 코드 + 국가 코드(예: fr_ca/의 콘텐츠)
      이 순서는 요청의 Accept-Language 헤더에 있는 각 언어의 품질 값을 따릅니다.

   2. 국가 코드만(예: ALL_ca/의 콘텐츠)

   3. 언어 코드만(예: fr/ 또는 es_ALL/의 콘텐츠)
      이 순서는 요청의 Accept-Language 헤더에 있는 각 언어의 품질 값을 따릅니다.

   4. '기본' 일치검색 정적 콘텐츠
      이 콘텐츠는 public 디렉터리의 루트와 같이 'i18n 콘텐츠' 디렉터리의 외부에 있는 콘텐츠입니다.

4. 구성된 재작성

5. 404 처리

   1. i18n 404 페이지
      일치검색 정적 콘텐츠에 대해 위에 나열된 동일한 우선순위 순서를 따릅니다.

   2. 커스텀 404 페이지

   3. 기본 404 페이지(Firebase에서 제공됨)

우선순위 순서 예시

위 예시를 계속 진행합니다. 동일한 예시 디렉터리와 예시 요청이 사용됩니다.

• 'i18n 콘텐츠' 디렉터리가 포함된 로컬 프로젝트 디렉터리 예시(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

• 요청 정보 예시

  • 언어 코드: fr, en(프랑스어, 이후 영어)
    언어 코드는 Accept-Language 헤더의 품질 값을 기준으로 순서가 지정됩니다.

  • 국가 코드: ca(캐나다)

일치검색 우선순위 순서 및 언어 환경설정의 품질 값에 따라 Hosting은 요청된 페이지의 디렉터리를 다음 순서로 검색합니다.

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. 404 처리

사용자에게 어떤 페이지가 제공되나요?

• 요청된 페이지: index.html

  답변

  fr_ca/ 하위 폴더의 index.html

  Hosting이 fr_ca/ 하위 폴더를 먼저 검색하기 때문에 해당 하위 폴더에서 index.html에 일치검색을 수행합니다.

• 요청된 페이지: awesome-page.html

  답변

  fr/ 하위 폴더의 404.html

  Hosting이 먼저 일치검색을 위한 우선순위 순서에 따라 전체 디렉터리(모든 'i18n 콘텐츠' 하위 폴더 및 루트 디렉터리)를 검색하지만 awesome-page.html에 대한 일치검색 항목이 없습니다.

  따라서 Hosting은 일치검색과 동일한 i18n 우선순위 순서를 따르는 404 처리를 시작합니다. fr/ 하위 폴더는 404 페이지를 포함하는 첫 번째로 검색된 하위 폴더입니다.

'i18n 콘텐츠' 디렉터리의 검색 및 제공에 대해서는 다음을 참조하세요.

• localized-files/ 디렉터리에 실제로 en_ca/, en_ALL/, en/ 하위 폴더가 포함되지 않으므로 Hosting이 요청의 언어-국가 조합에 대해 일치하는 하위 폴더를 찾을 때까지 우선순위 목록을 건너뜁니다.

• localized-files/ 디렉터리에 es_ALL/ 하위 폴더가 포함되더라도 위의 예시 요청에는 es 또는 es-foo 언어 코드가 포함되지 않습니다. 따라서 Hosting이 es와 일치하는 'i18n 콘텐츠'를 검색하지 않습니다.

• fr/ 및 fr_ALL/ 하위 폴더는 사용자의 국가 및 언어 환경설정의 관점에서 동일합니다. 하지만 두 하위 폴더가 모두 존재할 경우 Hosting은 fr/ 콘텐츠 이전에 fr_ALL/ 콘텐츠를 제공합니다.

쿠키로 언어 및 국가 코드 재정의

쿠키를 사용해 국가 및 언어 헤더를 재정의하여 제공되는 콘텐츠를 변경할 수 있습니다.

쿠키 재정의 사용 방법은 다음과 같습니다.

• 다른 언어-국가 조합으로 기능을 테스트해서 제공할 콘텐츠를 확인합니다.

• 사용자가 자신에게 표시되는 콘텐츠를 변경할 수 있도록 지원합니다. 예를 들어 언어 선택기를 구현한 후 그에 맞게 사용자의 firebase-language-override 쿠키를 설정할 수 있습니다.

쿠키 재정의를 구성하려면 firebase-country-override 및 firebase-language-override 모두 또는 둘 중 하나로 쿠키를 설정합니다. 예를 들어 다음 자바스크립트 코드 스니펫은 국가 코드를 ca로 재정의하고 Accept-Language 헤더를 fr,en으로 재정의합니다.

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

언어 쿠키 재정의는 하위 태그 또는 품질 값 없이 환경설정 순서에 따라 쉼표로 구분된 언어 코드 목록이어야 합니다.

쿠키 재정의는 로그에 반영되지 않습니다.