국제화

Astro의 국제화 (i18n) 기능을 사용하면 전 세계의 방문자들을 대상으로 프로젝트를 조정할 수 있습니다.

i18n 라우팅

Added in: astro@3.5.0

Astro의 i18n 라우팅을 사용하면 기본 언어 구성, 상대 페이지 URL 계산, 방문자 브라우저에서 제공하는 기본 언어 허용을 지원하여 다국어 콘텐츠를 추가할 수 있습니다. 방문자가 항상 사이트의 기존 콘텐츠로 이동할 수 있도록 언어별로 대체 언어를 지정할 수도 있습니다.

이 라우팅 API는 다국어 사이트가 생성하는 URL을 생성, 사용, 확인하는 데 도움이 됩니다. 이 API가 계속 개발됨에 따라 최신 기능을 정기적으로 확인하고 업데이트하세요!

i18n 라우팅 구성

기본 언어 (defaultLocale) 및 지원할 모든 언어 목록 (locales)을 사용하여 Astro 구성에 i18n 객체를 추가하여 라우팅 옵션을 활성화합니다.
astro.config.mjs
```
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'pt-br'],
  },
});
```
defaultLocale에 대해 원하는 URL 경로를 기반으로 routing을 선택하고 구성합니다.
- "prefixDefaultLocale: false" (기본값): 기본 언어로 된 URL에는 /[locale]/ 접두사가 없습니다. 다른 모든 언어에는 접두사가 추가됩니다.
- "prefixDefaultLocale: true": 기본 언어를 포함한 모든 URL에는 /[locale]/ 접두사가 붙습니다.
astro.config.mjs
```
import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    routing: {
      prefixDefaultLocale: false,
    },
  },
});
```
언어별로 현지화된 콘텐츠로 콘텐츠 폴더를 구성합니다. 폴더 이름은 locales의 항목과 정확히 일치해야 하며, 폴더 구성은 routing에서 선택한 URL 경로와 일치해야 합니다.

현지화된 URL 경로를 표시하도록 prefixDefaultLocale: true를 구성한 경우에만 defaultLocale에 대한 현지화된 폴더를 포함하세요.
- src - pages - about.astro - index.astro - es - about.astro - index.astro - pt-br - about.astro - index.astro
현지화된 폴더는 /pages/ 폴더의 루트에 있을 필요는 없습니다.
src/pages/ 내 어디에나 개별 /[locale]/ 폴더를 생성하면 Astro의 파일 기반 라우팅이 해당 URL 경로에 페이지를 생성합니다.
i18n 라우팅이 구성되면 이제 astro:i18n 모듈에서 사용할 수 있는 getRelativeLocaleURL() 도우미를 사용하여 사이트 내 페이지에 대한 링크를 계산할 수 있습니다. 이는 항상 정확하고 현지화된 경로를 제공하며 사이트에서 URL을 올바르게 사용하거나 확인하는 데 도움이 될 수 있습니다. 링크를 수동으로 작성할 수도 있습니다.
src/pages/es/index.astro
```
---
import { getRelativeLocaleUrl } from 'astro:i18n';

// 기본 언어는 "es"
const aboutURL = getRelativeLocaleUrl('es', 'about');
---

<a href="/get-started/">¡Vamos!</a>
<a href={getRelativeLocaleUrl('es', 'blog')}>Blog</a>
<a href={aboutURL}>Acerca</a>
```

`라우팅`

Astro의 내장 파일 기반 라우팅은 src/pages/ 디렉터리의 파일 구조를 기반으로 URL 경로를 자동으로 생성합니다. i18n 라우팅을 구성할 때 routing 값을 사용하면 도우미 기능을 사용하여 프로젝트에서 경로를 생성, 사용, 확인할 수 있도록 파일 구조 (및 생성된 URL 경로)를 지정할 수 있습니다.

`prefixDefaultLocale: false`

import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    routing: {
      prefixDefaultLocale: false,
    },
  },
});

이것이 기본값입니다. 기본 언어의 URL에 /[locale]/ 접두사가 없으며 기본 언어의 파일이 src/pages/ 루트에 존재하는 경우 이 옵션을 설정하십시오.

src/pages/blog.astro는 example.com/blog/ 경로를 생성합니다.
src/pages/fr/blog.astro는 example.com/fr/blog/ 경로를 생성합니다.
src/pages/es/blog.astro 파일이 없으면 대체 전략를 지정하지 않는 한 example.com/es/blog/ 경로는 404가 됩니다.

`prefixDefaultLocale: true`

import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    routing: {
      prefixDefaultLocale: true,
    },
  },
});

모든 경로의 URL에 /locale/ 접두사가 있고 defaultLocale에 대한 파일을 포함한 모든 페이지 콘텐츠 파일이 현지화된 폴더에 있는 경우 이 옵션을 설정하세요.

디렉터리src
- 디렉터리pages
  - index.astro // 참고: 이 파일은 항상 필요합니다.
  - 디렉터리en
    index.astro
    about.astro
  - 디렉터리es
    about.astro
    index.astro
  - 디렉터리pt-br
    about.astro
    index.astro

언어 접두사가 없는 URL (예: example.com/blog/)은 404 (찾을 수 없음) 상태 코드를 반환합니다.

`redirectToDefaultLocale`

Added in: astro@4.2.0

src/pages/index.astro에 의해 생성된 홈 URL (/)이 /<defaultLocale>로 리디렉션되는지 여부를 구성합니다.

prefixDefaultLocale: true를 설정하면 routing 구성 객체에서 redirectToDefaultLocale: true도 자동으로 설정됩니다. 기본적으로 필수 src/pages/index.astro 파일은 자동으로 기본 로케일의 인덱스 페이지로 리디렉션됩니다.

redirectToDefaultLocale: false 설정을 통해 이 동작을 선택 해제할 수 있습니다. 이를 통해 구성된 로케일 폴더 구조 외부에 존재하는 사이트 홈 페이지를 가질 수 있습니다.

`domains` (실험적)

Added in: astro@4.3.0 New

이 라우팅 옵션을 사용하면 site가 구성된 @astrojs/node 또는 @astrojs/vercel 어댑터를 사용하여 서버 렌더링 프로젝트에 대해 언어별로 도메인을 사용자 정의할 수 있습니다.

프로젝트에서 이를 활성화하려면, 아직 구성하지 않은 경우 기본 설정으로 i18n 라우팅을 구성하세요. 그런 다음 experimental.i18nDomains 플래그를 true로 설정하고 i18n.domains를 추가하여 지원되는 locales을 사용자 정의 URL에 매핑합니다.

import { defineConfig } from 'astro/config';
export default defineConfig({
  site: 'https://example.com',
  output: 'server', // 필수, 사전 렌더링된 페이지 없음
  adapter: node({
    mode: 'standalone',
  }),
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr', 'ja'],
    routing: {
      prefixDefaultLocale: false,
    },
    domains: {
      fr: 'https://fr.example.com',
      es: 'https://example.es',
    },
  },
  experimental: {
    i18nDomains: true,
  },
});

매핑되지 않은 모든 locales는 prefixDefaultLocales 구성을 따릅니다. 그러나 이 값이 false인 경우에도 defaultLocale에 대한 페이지 파일은 현지화된 폴더 내에 있어야 합니다. 위 구성을 위해서는 /en/ 폴더가 필요합니다.

위 구성을 사용하면 다음과 같습니다.

/fr/about.astro 파일은 https://fr.example.com/about URL을 생성합니다.
/es/about.astro 파일은 https://example.es/about URL을 생성합니다.
/ja/about/astro 파일은 https://example.com/ja/about URL을 생성합니다.
/en/about.astro 파일은 https://example.com/about URL을 생성합니다.

위 URL은 getAbsoluteLocaleUrl() 및 getAbsoluteLocaleUrlList() 함수에서도 반환됩니다.

제한사항

이 기능에는 몇 가지 제한사항이 있습니다.

site 옵션은 필수입니다.
output 옵션은 "server"로 설정되어야 합니다.
사전 렌더링된 개별 페이지는 있을 수 없습니다.
어댑터의 functionPerRoute 기능은 지원되지 않습니다.

Astro는 이 기능을 지원하기 위해 다음 헤더를 사용합니다.

X-Forwarded-Host 및 Host. Astro는 전자를 사용하고, 없을 경우 후자를 시도할 것입니다.
서버 요청의 X-Forwarded-Proto 및 URL#protocol.

서버 프록시/호스팅 플랫폼이 이 정보를 제공할 수 있는지 확인하세요. 이러한 헤더를 검색하지 못하면 404 (상태 코드) 페이지가 표시됩니다.

`defaultLocale` 및 `locales`

i18n 라우팅 구성에는 기본 언어 (defaultLocale)와 지원되는 모든 언어 목록 (locales)이 모두 지정되어야 합니다.

locales 구성 배열의 각 항목은 문자열 (예: "fr", "pt-br") 또는 사용자 정의 언어 경로여야 합니다. locales에는 문자열과 사용자 정의 경로의 조합이 포함될 수 있습니다.

/[locale]/ 폴더 이름은 목록의 locales (문자열 또는 path 값)과 정확히 일치해야 하며, 라우팅 구성은 기본 언어에 대한 현지화된 폴더가 있는지 여부와 일치해야 합니다. 기타 지원되는 모든 언어에는 현지화된 자체 폴더가 있어야 합니다.

배포 호스트에 따라 URL 경로의 변환을 발견할 수 있으므로 배포된 사이트를 확인하여 locale 값에 가장 적합한 구문을 결정하세요.

사용자 정의 언어 경로

사이트에서 지원되는 locales를 문자열 (예: “en”, “pt-br”)로 정의하는 것 외에도 Astro를 사용하면 브라우저에서 인식할 수 있는 임의 개수의 언어 codes를 사용자 정의 URL path에 매핑할 수 있습니다. locales는 프로젝트 폴더 구조에 해당하는 한 모든 형식의 문자열이 될 수 있지만 codes는 브라우저에서 허용되는 구문을 따라야 합니다.

맞춤 URL 접두사를 정의하려면 path 키를 사용하여 locales 배열에 객체를 전달하고, 이 URL에 매핑된 언어를 나타내는 codes를 전달합니다. 이 경우 /[locale]/ 폴더 이름은 path 값과 정확히 일치해야 하며 URL은 path 값을 사용하여 생성됩니다.

이는 언어의 여러 변형 (예: "fr", "fr-BR", "fr-CA")을 지원하고 이러한 모든 변형을 동일한 URL /fr/ 아래에 매핑하거나 사용자 정의하려는 경우에 유용합니다. (예: /french/):

import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    locales: [
      'es',
      'en',
      {
        path: 'french', // 슬래시가 포함되지 않음
        codes: ['fr', 'fr-BR', 'fr-CA'],
      },
    ],
    routing: {
      prefixDefaultLocale: true,
    },
  },
});

astro:i18n 가상 모듈의 함수를 사용하여 구성 (예: getRelativeLocaleUrl())에 따라 유효한 URL 경로를 계산하는 경우, 해당 path를 locale 값으로 사용하세요.

브라우저 언어 감지

Astro의 주문형 서버 렌더링 모드 (output:'server' 또는 output:'hybrid') 중 하나와 결합된 Astro의 i18n 라우팅을 사용하면 브라우저 언어 감지를 위한 두 가지 속성인 Astro.preferredLocale 및 Astro.preferredLocaleList에 액세스할 수 있습니다.

이는 브라우저의 Accept-Language 헤더와 locales (문자열 또는 codes)를 결합하여 방문자가 선호하는 언어를 자동으로 적용합니다.

Astro.preferredLocale: Astro는 브라우저의 선호 언어가 locales 배열에 포함된 경우, 방문자를 위한 선호 언어를 계산할 수 있습니다. 일치 항목이 없으면 이 값은 undefined가 됩니다.
Astro.preferredLocaleList: 브라우저에서 요청하고 웹사이트에서 지원하는 모든 언어의 배열입니다. 그러면 여러분의 사이트와 방문자 간 호환되는 모든 언어 목록이 생성됩니다. 브라우저가 요청한 언어가 locales 배열에 없으면 값은 []입니다. 브라우저가 기본 언어를 지정하지 않으면 이 값은 i18n.locales가 됩니다.
Astro.currentLocale: locales 구성에 지정된 구문을 사용하여 현재 URL에서 계산된 언어입니다. URL에 /[locale]/ 접두사가 포함되어 있지 않으면 값은 기본적으로 i18n.defaultLocale이 됩니다.

방문자의 선호도를 성공적으로 일치시키려면 브라우저에서 사용하는 것과 동일한 패턴을 사용하여 codes를 제공하십시오.

대체 전략

Astro의 i18n 라우팅을 사용하면 대체 라우팅 전략을 구성할 수 있습니다. 한 언어로 된 페이지가 존재하지 않는 경우 (예: 아직 번역되지 않은 페이지) 404 페이지를 표시하는 대신 언어별로 사용자를 한 언어에서 다른 언어로 리디렉션할 수 있습니다. 이는 아직 모든 경로에 대한 페이지가 없지만 방문자에게 일부 콘텐츠를 제공하려는 경우에 유용합니다.

예를 들어 아래 구성은 누락된 fr 경로에 대한 대체 언어로 es를 설정합니다. 이는 src/pages/fr/my-page.astro 파일이 존재하지 않을때 example.com/fr/my-page/에 방문한 사용자가 404 페이지로 이동하지 않고 example.com/es/my-page/로 리디렉션되어 콘텐츠를 볼 수 있다는 것을 의미합니다.

import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['es', 'en', 'fr'],
    fallback: {
      fr: 'es',
    },
  },
});

Astro는 src/pages/es/에 존재하는 모든 페이지에 대해 src/pages/fr/에 페이지가 빌드되었는지 확인합니다. 페이지가 아직 존재하지 않으면 해당 es 경로로 리디렉션되는 페이지가 생성됩니다.

가상 모듈 `astro:i18n`

이 모듈은 프로젝트에 구성된 언어를 사용하여 URL을 생성하는 데 도움이 되는 기능을 제공합니다.

i18n 라우터를 사용하여 프로젝트에 대한 경로를 생성하는 것은 페이지 경로에 영향을 주는 특정 구성 값에 따라 달라집니다. 이러한 기능을 사용하여 경로를 생성할 때 다음에 대한 개별 설정을 고려해야 합니다.

또한 defaultLocale에 대해 이러한 함수에 의해 생성되어 반환된 URL은 i18n.routing 구성을 반영합니다.

prefixDefaultLocale: true가 구성된 경우, 생성된 URL에는 URL에 /lang/ 경로가 포함됩니다. prefixDefaultLocale: false로 생성된 URL에는 언어 접두사가 포함되지 않습니다.

`getRelativeLocaleUrl()`

getRelativeLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string

이 함수를 사용하여 언어의 상대 경로를 검색합니다. 해당 언어가 존재하지 않으면 Astro는 오류를 발생시킵니다.

---
getRelativeLocaleUrl('fr', '');
// /fr 반환

getRelativeLocaleUrl('fr', 'getting-started');
// /fr/getting-started 반환

getRelativeLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
});
// /blog/fr-ca/getting-started 반환

getRelativeLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
  normalizeLocale: false,
});
// /blog/fr_CA/getting-started 반환
---

`getAbsoluteLocaleUrl()`

getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string

site에 값이 있을 때 언어의 절대 경로를 검색하려면 이 함수를 사용하세요. site가 구성되지 않은 경우, 함수는 상대 URL을 반환합니다. 해당 언어가 존재하지 않으면 Astro는 오류를 발생시킵니다.

---
// `site`가 `https://example.com`로 설정된 경우

getAbsoluteLocaleUrl('fr', '');
// https://example.com/fr 반환

getAbsoluteLocaleUrl('fr', 'getting-started');
// https://example.com/fr/getting-started 반환

getAbsoluteLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
});
// https://example.com/blog/fr-ca/getting-started 반환

getAbsoluteLocaleUrl('fr_CA', 'getting-started', {
  prependWith: 'blog',
  normalizeLocale: false,
});
// https://example.com/blog/fr_CA/getting-started 반환
---

`getRelativeLocaleUrlList()`

모든 언어에 대한 상대 경로 목록을 반환하려면 getRelativeLocaleUrl과 같이 이것을 사용하세요.

getRelativeLocaleUrlList(locale: string, options?: GetLocaleOptions): string[]

`getAbsoluteLocaleUrlList()`

getAbsoluteLocaleUrlList(locale: string, options?: GetLocaleOptions): string[]

모든 언어에 대한 절대 경로 목록을 반환하려면 getAbsoluteLocaleUrl과 같이 이것을 사용하세요.

`getPathByLocale(locale: string): string`

사용자 정의 언어 경로가 구성될 때 하나 이상의 codes와 연결된 path를 반환하는 함수입니다.

사용자 정의 경로에서 URL 생성

locale이 사용자 정의 경로인 경우 locale 값으로 path를 사용하세요.

예를 들어, 아래 locales 구성에 대한 i18n 도우미 함수에서 french를 사용하세요.

locales: ["es", "en", {
  path: "french",
  codes: ["fr", "fr-BR", "fr-CA"]
}],

---
import { getPathByLocale, getRelativeLocaleUrl, getLocaleByPath } from 'astro:i18n';

getRelativeLocaleUrl('french', 'blog'); // /french/blog 반환
---

다른 astro:i18n 함수는 동일한 구성에 대해 다음 결과를 반환합니다.

---
getPathByLocale('fr'); // "french" 반환
getPathByLocale('fr-CA'); // "french" 반환
getLocaleByPath('french'); // 구성된 첫 번째 code이기 때문에 "fr"을 반환
---

`getLocaleByPath(path: string): string`

언어 path와 연관된 code를 반환하는 함수입니다.

사용자 정의 경로에 대한 언어 검색

여러 codes로 구성된 사용자 정의 경로가 주어지면, 함수는 구성된 첫 번째 코드를 반환합니다.

import { defineConfig } from 'astro/config';
export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: [
      'en',
      'es',
      'fr',
      {
        path: 'portugues',
        codes: ['pt-AO', 'pt', 'pt-BR'],
      },
    ],
  },
});

---
import { getLocaleByPath } from 'astro:18n';
console.log(getLocaleByPath('en')); // "en"를 기록합니다.
console.log(getLocaleByPath('fr')); // "fr"를 기록합니다.
console.log(getLocaleByPath('portugues')); // "pt-AO"를 기록합니다.
---

GitHub Issue 생성

의견 보내기

국제화

i18n 라우팅

i18n 라우팅 구성

`라우팅`

`prefixDefaultLocale: false`

`prefixDefaultLocale: true`

`redirectToDefaultLocale`

`domains` (실험적)

제한사항

`defaultLocale` 및 `locales`

사용자 정의 언어 경로

브라우저 언어 감지

대체 전략

가상 모듈 `astro:i18n`

`getRelativeLocaleUrl()`

`getAbsoluteLocaleUrl()`

`getRelativeLocaleUrlList()`

`getAbsoluteLocaleUrlList()`

`getPathByLocale(locale: string): string`

사용자 정의 경로에서 URL 생성

`getLocaleByPath(path: string): string`

사용자 정의 경로에 대한 언어 검색

국제화

i18n 라우팅

i18n 라우팅 구성

라우팅

prefixDefaultLocale: false

prefixDefaultLocale: true

redirectToDefaultLocale

domains (실험적)

제한사항

defaultLocale 및 locales

사용자 정의 언어 경로

브라우저 언어 감지

대체 전략

가상 모듈 astro:i18n

getRelativeLocaleUrl()

getAbsoluteLocaleUrl()

getRelativeLocaleUrlList()

getAbsoluteLocaleUrlList()

getPathByLocale(locale: string): string

사용자 정의 경로에서 URL 생성

getLocaleByPath(path: string): string

사용자 정의 경로에 대한 언어 검색

`라우팅`

`prefixDefaultLocale: false`

`prefixDefaultLocale: true`

`redirectToDefaultLocale`

`domains` (실험적)

`defaultLocale` 및 `locales`

가상 모듈 `astro:i18n`

`getRelativeLocaleUrl()`

`getAbsoluteLocaleUrl()`

`getRelativeLocaleUrlList()`

`getAbsoluteLocaleUrlList()`

`getPathByLocale(locale: string): string`

`getLocaleByPath(path: string): string`