---
createdAt: 2024-03-07
updatedAt: 2026-05-31
title: "Astro i18n - 앱을 번역하는 완전 가이드"
description: "i18next는 이제 그만. 2026년 다국어 (i18n) Astro 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
keywords:
- 국제화
- 문서
- Intlayer
- Vite
- React
- i18n
- JavaScript
slugs:
- doc
- environment
- astro
applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
applicationShowcase: https://intlayer-astro-template.vercel.app
history:
- version: 8.9.0
date: 2026-05-04
changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
- version: 7.5.9
date: 2025-12-30
changes: "init 명령어 추가"
- version: 6.2.0
date: 2025-10-03
changes: "Astro 통합, 설정 및 사용법 업데이트"
---
# Intlayer를 사용하여 Astro 사이트 번역하기 | 국제화 (i18n)
## 목차
## 대안보다 Intlayer를 선택해야 하는 이유는 무엇입니까?
'astro-i18n' 또는 'i18next'와 같은 주요 솔루션과 비교할 때 Intlayer는 다음과 같은 통합 최적화가 제공되는 솔루션입니다.
Intlayer는 **다국어 라우팅**, **사이트맵** 및 국제화 확장(i18n)에 필요한 모든 기능을 제공하여 Astro와 완벽하게 작동하도록 최적화되어 있습니다.
대용량 JSON 파일을 페이지에 로드하는 대신 필요한 콘텐츠만 로드하세요. Intlayer는 **번들 및 페이지 크기를 최대 50%** 줄이는 데 도움이 됩니다.
애플리케이션 콘텐츠의 범위를 지정하면 대규모 애플리케이션의 **유지 관리가 용이해집니다**. 전체 콘텐츠 코드베이스를 검토해야 하는 정신적 부담 없이 단일 기능 폴더를 복제하거나 삭제할 수 있습니다. 또한 Intlayer는 **완전히 유형**되어 콘텐츠의 정확성을 보장합니다.
콘텐츠를 같은 위치에 배치하면 LLM(대형 언어 모델)에 **필요한 컨텍스트가 줄어듭니다**. Intlayer에는 누락된 번역을 테스트하기 위한 **CLI**, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** 및 **[agent)와 같은 도구 모음도 함께 제공됩니다. 기술](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, AI 에이전트를 위한 개발자 경험(DX)을 더욱 원활하게 만듭니다.
AI 공급자의 비용으로 선택한 LLM을 사용하여 CI/CD 파이프라인을 번역하려면 자동화를 사용하세요. Intlayer는 또한 콘텐츠 추출을 자동화하는 **컴파일러**와 **백그라운드에서 번역**을 돕는 [웹 플랫폼](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)을 제공합니다.
대규모 JSON 파일을 구성 요소에 연결하면 성능 및 반응성 문제가 발생할 수 있습니다. Intlayer는 빌드 시 콘텐츠 로딩을 최적화합니다.
Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는 **자체 호스팅 [비주얼 편집기](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** 및 **[전체 CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**를 제공합니다. 다국어 콘텐츠를 **실시간**으로 제공하여 번역가, 카피라이터, 기타 팀원과 원활하게 협업할 수 있습니다. 콘텐츠는 로컬 및/또는 원격으로 저장될 수 있습니다.
---
## Astro에서 Intlayer 설정을 위한 단계별 가이드
GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer-astro-template) 보기.
### 1단계: 종속성 설치
선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치합니다:
```bash packageManager="npm"
npm install intlayer astro-intlayer
# 선택 사항: React 아일랜드 지원 추가 시
npm install react react-dom react-intlayer @astrojs/react
```
```bash packageManager="pnpm"
pnpm add intlayer astro-intlayer
# 선택 사항: React 아일랜드 지원 추가 시
pnpm add react react-dom react-intlayer @astrojs/react
```
```bash packageManager="yarn"
yarn add intlayer astro-intlayer
# 선택 사항: React 아일랜드 지원 추가 시
yarn add react react-dom react-intlayer @astrojs/react
```
- **intlayer**
설정 관리, 번역, [콘텐츠 선언](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md), 트랜스파일 및 [CLI 명령어](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/index.md)를 위한 국제화 도구를 제공하는 핵심 패키지입니다.
- **astro-intlayer**
Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Astro 통합 플러그인과 사용자의 선호 로케일을 감지하고 쿠키를 관리하며 URL 리디렉션을 처리하는 미들웨어가 포함되어 있습니다.
### 2단계: 프로젝트 설정
애플리케이션의 언어를 설정하기 위한 설정 파일을 생성합니다:
```typescript fileName="intlayer.config.ts"
import { Locales, type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
locales: [
Locales.ENGLISH,
Locales.FRENCH,
Locales.SPANISH,
// 기타 로케일
],
defaultLocale: Locales.ENGLISH,
},
};
export default config;
```
> 이 설정 파일을 통해 로컬라이즈된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언 위치 및 확장자 설정, 콘솔의 Intlayer 로그 비활성화 등을 구성할 수 있습니다. 사용 가능한 파라미터의 전체 목록은 [설정 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
### 3단계: Astro 설정에 Intlayer 통합
Astro 설정에 intlayer 플러그인을 추가합니다.
```typescript fileName="astro.config.ts"
// @ts-check
import { intlayer } from "astro-intlayer";
import { defineConfig } from "astro/config";
// https://astro.build/config
export default defineConfig({
integrations: [intlayer()],
});
```
> `intlayer()` 통합 플러그인은 Intlayer를 Astro와 통합하는 데 사용됩니다. 콘텐츠 선언 파일의 빌드를 보장하고 개발 모드에서 이를 감시합니다. Astro 애플리케이션 내에서 Intlayer 환경 변수를 정의하며, 성능 최적화를 위한 에일리어스(alias)를 제공합니다.
### 4단계: 콘텐츠 선언
번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리합니다:
```tsx fileName="src/app.content.tsx"
import { t, type Dictionary } from "intlayer";
import type { ReactNode } from "react";
const appContent = {
key: "app",
content: {
title: t({
en: "Hello World",
fr: "Bonjour le monde",
es: "Hola mundo",
ko: "안녕하세요",
}),
},
} satisfies Dictionary;
export default appContent;
```
> 콘텐츠 선언은 `contentDir`(기본값 `./src`)에 포함되어 있고 콘텐츠 선언 파일 확장자(기본값 `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`)와 일치한다면 애플리케이션 어디에서나 정의할 수 있습니다.
> 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요.
### 5단계: Astro에서 콘텐츠 사용
`intlayer`에서 내보낸 핵심 헬퍼를 사용하여 `.astro` 파일에서 직접 사전을 소비할 수 있습니다.
```astro fileName="src/pages/index.astro"
---
import {
getIntlayer,
getLocaleFromPath,
getLocalizedUrl,
defaultLocale,
localeMap,
getHTMLTextDir,
type LocalesValues,
} from "intlayer";
import LocaleSwitcher from "../components/LocaleSwitcher.astro";
// Get the current locale from the URL (e.g. /es/about -> 'es')
const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
// Get the content for the 'app' dictionary
const { title } = getIntlayer("app", locale);
---
```
### 6단계: 로컬라이즈된 라우팅
로컬라이즈된 페이지를 제공하기 위해 동적 라우트 세그먼트를 생성합니다(예: `src/pages/[locale]/index.astro`):
```astro fileName="src/pages/[locale]/index.astro"
---
import { getIntlayer } from "intlayer";
const { title } = getIntlayer('app');
---
{title}
```
Astro 통합은 개발 중에 언어 인식 라우팅 및 환경 정의를 돕는 Vite 미들웨어를 추가합니다. 또한 직접 로직을 작성하거나 `intlayer`의 `getLocalizedUrl`과 같은 유틸리티를 사용하여 언어 간 링크를 생성할 수 있습니다.
### 7단계: 선호하는 프레임워크 계속 사용하기
선호하는 프레임워크를 사용하여 애플리케이션을 계속 빌드하세요.
- Intlayer + React: [Intlayer with React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+react.md)
- Intlayer + Vue: [Intlayer with Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+vue.md)
- Intlayer + Svelte: [Intlayer with Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+svelte.md)
- Intlayer + Solid: [Intlayer with Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+solid.md)
- Intlayer + Preact: [Intlayer with Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+preact.md)
### TypeScript 설정
Intlayer는 모듈 증강(module augmentation)을 사용하여 TypeScript의 이점을 활용함으로써 코드베이스를 더 견고하게 만듭니다.


TypeScript 설정에 자동 생성된 타입이 포함되어 있는지 확인하세요.
```json5 fileName="tsconfig.json"
{
// ... 기존 TypeScript 설정
"include": [
// ... 기존 TypeScript 설정
".intlayer/**/*.ts", // 자동 생성된 타입 포함
],
}
```
### Git 설정
Intlayer가 생성한 파일은 무시하는 것이 좋습니다. 이를 통해 Git 리포지토리에 커밋되는 것을 방지할 수 있습니다.
무시하려면 `.gitignore` 파일에 다음 지침을 추가하세요:
```bash
# Intlayer가 생성한 파일 무시
.intlayer
```
### VS Code 확장 프로그램
Intlayer 개발 환경을 개선하기 위해 **공식 Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.
[VS Code Marketplace에서 설치](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
이 확장 프로그램은 다음 기능을 제공합니다:
- 번역 키 **자동 완성**.
- 누락된 번역에 대한 **실시간 오류 감지**.
- 번역된 콘텐츠의 **인라인 미리보기**.
- 번역을 쉽게 생성하고 업데이트할 수 있는 **빠른 작업(Quick Actions)**.
확장 프로그램 사용에 대한 자세한 내용은 [Intlayer VS Code 확장 프로그램 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.
---
### 15단계: 컴포넌트에서 콘텐츠 추출(선택 사항)
기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.
이 프로세스를 용이하게 하기 위해 Intlayer는 컴포넌트를 변환하고 콘텐츠를 추출하기 위한 [컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md) / [추출기](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)를 제안합니다.
설정하려면 `intlayer.config.ts` 파일에 `compiler` 섹션을 추가할 수 있습니다.
```typescript fileName="intlayer.config.ts" codeFormat="typescript"
import { type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
// ... 나머지 구성
compiler: {
/**
* 컴파일러 활성화 여부를 나타냅니다.
*/
enabled: true,
/**
* 출력 파일 경로를 정의합니다.
*/
output: ({ fileName, extension }) => `./${fileName}${extension}`,
/**
* 변환 후 컴포넌트를 저장할지 여부를 나타냅니다. 그렇게 하면 컴파일러를 한 번만 실행하여 앱을 변환한 다음 제거할 수 있습니다.
*/
saveComponents: false,
/**
* 사전 키 접두사
*/
dictionaryKeyPrefix: "",
},
};
export default config;
```
컴포넌트를 변환하고 콘텐츠를 추출하기 위해 추출기를 실행합니다
```bash packageManager="npm"
npx intlayer extract
```
```bash packageManager="pnpm"
pnpm intlayer extract
```
```bash packageManager="yarn"
yarn intlayer extract
```
```bash packageManager="bun"
bun x intlayer extract
```
`vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
```ts fileName="vite.config.ts"
import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";
export default defineConfig({
plugins: [
intlayer(),
intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
],
});
```
---
### 더 알아보기
더 자세히 알고 싶다면 [비주얼 에디터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)를 구현하거나 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)를 사용하여 콘텐츠를 외부화할 수 있습니다.