컨텐츠로 건너뛰기

국제화 (i18n) 라우팅

Astro의 국제화 (i18n) 기능을 사용하면 전 세계의 방문자들을 대상으로 프로젝트를 조정할 수 있습니다. 이 라우팅 API는 다국어 사이트가 생성하는 URL을 생성, 사용 및 확인하는 데 도움이 됩니다.

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

라우팅 로직

섹션 제목: 라우팅 로직

Astro는 미들웨어를 사용하여 라우팅 로직을 구현합니다. 이 미들웨어 함수는 최종적으로 자체 로직을 실행하기 전에 추가 미들웨어 및 각 페이지 경로에서 나오는 모든 Response을 기다리는 첫 번째 위치에 배치됩니다.

이는 자체 미들웨어 및 페이지 로직의 작업 (예: 리디렉션)이 먼저 실행되고 경로가 렌더링된 다음 i18n 미들웨어가 현지화된 URL이 유효한 경로에 해당하는지 확인하는 등의 자체 작업을 수행함을 의미합니다.

Astro의 i18n 미들웨어에 추가하거나 대신에 자신만의 i18n 로직을 추가하도록 선택할 수도 있습니다. 그러면 astro:i18n 도우미 함수에 계속 액세스하면서 경로를 더욱 효과적으로 제어할 수 있습니다.

i18n 라우팅 구성

섹션 제목: i18n 라우팅 구성

기본 언어 (defaultLocale) 및 지원되는 모든 언어 목록 (locales )은 i18n 구성 객체에 지정되어야 합니다. 또한 원하는 URL과 일치하도록 보다 구체적인 라우팅 및 대체 동작을 구성할 수 있습니다.

astro.config.mjs
import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["es", "en", "pt-br"],
  }
})

현지화된 폴더 생성

섹션 제목: 현지화된 폴더 생성

언어별로 현지화된 콘텐츠로 콘텐츠 폴더를 구성하세요. src/pages/ 내 어디에든 개별 /[locale]/ 폴더를 생성하면 Astro의 파일 기반 라우팅이 해당 URL 경로에 페이지를 생성합니다.

폴더 이름은 locales 항목과 정확히 일치해야 합니다. 기본 언어에 대한 현지화된 URL 경로 (예: /en/about/)를 표시하도록 prefixDefaultLocale: true를 구성한 경우에만 defaultLocale에 대한 현지화된 폴더를 포함합니다.

  • Directorysrc
    • Directorypages
      • about.astro
      • index.astro
      • Directoryes
        • about.astro
        • index.astro
      • Directorypt-br
        • about.astro
        • index.astro

링크 생성

섹션 제목: 링크 생성

i18n 라우팅이 구성되면 이제 astro:i18n 모듈에서 사용할 수 있는 getRelativeLocaleURL()과 같은 도우미 함수를 사용하여 사이트 내 페이지에 대한 링크를 계산할 수 있습니다. 생성된 링크는 항상 정확하고 현지화된 경로를 제공하며 사이트에서 URL을 올바르게 사용하거나 확인하는 데 도움이 될 수 있습니다.

링크를 수동으로 작성할 수도 있습니다.

src/pages/es/index.astro
---
import { getRelativeLocaleUrl } from 'astro:i18n';
// defaultLocale는 "es"입니다.
const aboutURL = getRelativeLocaleUrl("es", "about");
---
<a href="/get-started/">¡Vamos!</a>
<a href={getRelativeLocaleUrl('es', 'blog')}>Blog</a>
<a href={aboutURL}>Acerca</a>

routing

섹션 제목: routing

Astro의 내장 파일 기반 라우팅은 src/pages/ 내 파일 구조를 기반으로 URL 경로를 자동으로 생성합니다.

i18n 라우팅을 구성하면 이 파일 구조 (및 생성된 해당 URL 경로)에 대한 정보를 i18n 도우미 함수에서 사용할 수 있으므로 프로젝트에서 경로를 생성, 사용 및 확인할 수 있습니다. 더 많은 사용자 정의 및 언어별 유연성을 위해 이러한 옵션 중 다수를 함께 사용할 수 있습니다.

더 강력한 제어를 위해 자신만의 라우팅 로직을 수동으로 구현할 수도 있습니다.

prefixDefaultLocale

섹션 제목: prefixDefaultLocale

Added in: astro@3.5.0

이 라우팅 옵션은 기본 언어의 URL이 언어 접두사 (예: /en/about/)를 사용해야 하는지 여부를 정의합니다.

기본이 아닌 모든 지원 언어는 지역화된 접두사 (예: /fr/ 또는 /french/)를 사용하며 콘텐츠 파일은 적절한 폴더에 있어야 합니다. 이 구성 옵션을 사용하면 기본 언어도 지역화된 URL 구조를 따라야 하는지 여부를 지정할 수 있습니다.

또한 이 설정은 파일 구조와 URL 구조가 모든 언어에 대해 일치해야 하므로 기본 언어에 대한 페이지 파일이 존재해야 하는 위치 (예: src/pages/about/ 또는 src/pages/en/about)를 결정합니다.

  • "prefixDefaultLocale: false" (기본값): 기본 언어로 된 URL에는 /[locale]/ 접두사가 없습니다. 다른 모든 로케일에는 적용됩니다.

  • "prefixDefaultLocale: true": 기본 언어를 포함한 모든 URL에는 /[locale]/ 접두사가 붙습니다.

prefixDefaultLocale: false

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

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

  • Directorysrc
    • Directorypages
      • about.astro
      • index.astro
      • Directoryes
        • about.astro
        • index.astro
      • Directoryfr
        • about.astro
        • index.astro
  • src/pages/about.astro는 example.com/about/ 경로를 생성합니다.
  • src/pages/fr/about.astro는 example.com/fr/about/ 경로를 생성합니다.

prefixDefaultLocale: true

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

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

  • Directorysrc
    • Directorypages
      • index.astro // 참고: 이 파일은 항상 필요합니다.
      • Directoryen
        • index.astro
        • about.astro
      • Directoryes
        • about.astro
        • index.astro
      • Directorypt-br
        • about.astro
        • index.astro
  • 로케일 접두사가 없는 URL (예: example.com/about/)은 대체 전략을 지정하지 않는 한 404 (찾을 수 없음) 상태 코드를 반환합니다.

redirectToDefaultLocale

섹션 제목: redirectToDefaultLocale

Added in: astro@4.2.0

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

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

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

manual

섹션 제목: manual

Added in: astro@4.6.0

이 옵션이 활성화되면 Astro는 사용자 정의 로직을 구현할 수 있도록 i18n 미들웨어를 비활성화합니다. 다른 routing 옵션 (예: prefixDefaultLocale)은 routing: "manual"으로 구성할 수 없습니다.

여러분은 자신만의 라우팅 로직을 작성하거나 Astro의 i18n 미들웨어를 수동으로 실행할 책임이 있습니다.

astro.config.mjs
import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["es", "en", "fr"],
    routing: "manual"
  }
})

Astro는 미들웨어를 위한 도우미 함수를 제공하므로 기본 라우팅, 예외, 대체 동작, 오류 캐치 등을 제어할 수 있습니다: redirectToDefaultLocale(), notFound () 및 redirectToFallback():

src/middleware.js
import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n"; // 'manual' 라우팅으로 사용 가능한 함수
export const onRequest = defineMiddleware(async (ctx, next) => {
  if (ctx.url.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(302);
  }
})

미들웨어 함수

섹션 제목: 미들웨어 함수

middleware 함수는 Astro의 i18n 미들웨어를 수동으로 생성합니다. 이를 통해 Astro의 i18n 라우팅을 완전히 교체하는 대신 확장할 수 있습니다.

순서를 결정하기 위해 sequence 유틸리티를 사용하여 자체 미들웨어와 함께 라우팅 옵션과 함께 middleware를 실행할 수 있습니다.

src/middleware.js
import {defineMiddleware, sequence} from "astro:middleware";
import { middleware } from "astro:i18n"; // Astro의 자체 i18n 라우팅 구성


export const userMiddleware = defineMiddleware(async (ctx, next) => {
  // 이 response는 Astro의 i18n 미들웨어에서 나올 수 있으며 404를 반환할 수 있습니다.
  const response = await next();
  // /about 페이지는 예외이므로 렌더링하고 싶습니다.
  if (ctx.url.startsWith("/about")) {
    return new Response("About page", {
      status: 200
    });
  } else {
    return response;
  }
});


export const onRequest = sequence(
  userMiddleware,
  middleware({
    redirectToDefaultLocale: false,
    prefixDefaultLocale: true
  })
)

domains

섹션 제목: domains

Added in: astro@4.9.0 New

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

지원되는 locales를 맞춤 URL에 매핑하려면 i18n.domains를 추가하세요.

astro.config.mjs
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() 함수에서도 반환됩니다.

fallback

섹션 제목: fallback

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

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

astro.config.mjs
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 경로로 리디렉션되는 페이지가 생성됩니다.

사용자 정의 로케일 경로

섹션 제목: 사용자 정의 로케일 경로

사이트에서 지원되는 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/):

astro.config.mjs
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 값으로 사용하세요.

제한 사항

섹션 제목: 제한 사항

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

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

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

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

브라우저 언어 감지

섹션 제목: 브라우저 언어 감지

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를 제공하십시오.