\n```\n\n> **라우팅 설정에 관한 참고 사항:**\n> 사용하는 디렉토리 구조는 `intlayer.config.ts`의 `middleware.routing` 설정에 따라 달라집니다:\n>\n> - **`prefix-no-default` (기본값):** 루트(프레픽스 없음)에 기본 언어를 유지하고 나머지에 프레픽스를 붙입니다. 모든 케이스를 처리하려면 `[...locale]`을 사용하세요.\n> - **`prefix-all`:** 모든 URL에 언어 프레픽스가 붙습니다. 루트를 분리해서 처리할 필요가 없다면 표준 `[locale]`을 사용할 수 있습니다.\n> - **`search-param` 또는 `no-prefix`:** 로케일 폴더가 필요 없습니다. 로케일은 검색 파라미터나 쿠키를 통해 처리됩니다.\n\n### 6단계: Lit 커스텀 엘리먼트 생성\n\nLit 커스텀 엘리먼트를 생성합니다. 클라이언트에서 Intlayer 싱글톤을 초기화하기 위해 서버에서 감지된 `locale` 프로퍼티를 사용하여 `connectedCallback`에서 `installIntlayer`를 호출합니다.\n\n```typescript fileName=\"src/components/lit/LitDemo.ts\"\nimport { LitElement, html } from \"lit\";\nimport { installIntlayer, useIntlayer, useLocale } from \"lit-intlayer\";\nimport { getLocalizedUrl, getLocaleName, type LocalesValues } from \"intlayer\";\n\nclass LitDemo extends LitElement {\n static properties = {\n locale: { type: String },\n };\n\n locale: LocalesValues = \"en\" as LocalesValues;\n\n private _content = useIntlayer(this, \"lit-demo\");\n private _localeCtrl = useLocale(this, {\n onLocaleChange: (newLocale: LocalesValues) => {\n window.location.href = getLocalizedUrl(\n window.location.pathname,\n newLocale\n );\n },\n });\n\n override connectedCallback() {\n super.connectedCallback();\n // 서버에서 감지된 로케일로 초기화\n installIntlayer({ locale: this.locale as any });\n }\n\n override render() {\n const { greeting, description } = this._content;\n const {\n locale: currentLocale,\n availableLocales,\n setLocale,\n } = this._localeCtrl;\n\n return html`\n \n `;\n }\n}\n\ncustomElements.define(\"lit-demo\", LitDemo);\n```\n\n> `locale` 프롭은 Astro 페이지(서버 감지)에서 전달되어 `connectedCallback`에서 `installIntlayer`를 초기화하는 데 사용되며, 이로 인해 엘리먼트 내 모든 `ReactiveController` 훅의 초기 로케일이 결정됩니다.\n\n> `useIntlayer`는 `ReactiveController`로 등록됩니다. 언어가 변경되면 엘리먼트가 자동으로 다시 렌더링되므로 추가 설정이 필요 없습니다.\n\n### 7단계: 언어 전환기 추가\n\n언어 전환 기능은 Lit 커스텀 엘리먼트의 `render()` 메서드(6단계 참조)에 직접 통합되어 있습니다. `lit-intlayer`의 `useLocale`을 사용하며, 사용자가 새 언어를 선택할 때 로컬라이즈된 URL로 이동합니다:\n\n```typescript fileName=\"src/components/lit/LitDemo.ts\"\n// LitElement 클래스 내에서 useLocale 설정(6단계 항목) 이후:\n\nprivate _localeCtrl = useLocale(this, {\n onLocaleChange: (newLocale: LocalesValues) => {\n // 언어 변경 시 로컬라이즈된 URL로 이동\n window.location.href = getLocalizedUrl(window.location.pathname, newLocale);\n },\n});\n\noverride render() {\n const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;\n\n return html`\n \n `;\n}\n```\n\n> **Lit 반응성에 관한 참고 사항:**\n> `useLocale`은 `ReactiveController`를 반환합니다. `setLocale`이 호출되면 컨트롤러가 자동으로 다시 렌더링을 예약하므로 별도의 DOM 조작 없이도 활성 버튼 상태가 업데이트됩니다.\n\n> **영속성에 관한 참고 사항:**\n> `window.location.href`를 통한 리디렉션을 위해 `onLocaleChange`를 사용하면 새 언어 URL이 확실히 방문되도록 보장합니다. 이를 통해 Intlayer 미들웨어가 언어 쿠키를 설정하고 향후 방문 시 사용자의 선호도를 기억할 수 있습니다.\n\n### 8단계: Sitemap 및 Robots.txt\n\nIntlayer는 동적으로 로컬라이즈된 사이트맵과 robots.txt 파일을 생성하기 위한 유틸리티를 제공합니다.\n\n#### 사이트맵\n\nIntlayer는 애플리케이션의 사이트맵을 쉽게 만들 수 있는 내장 사이트맵 생성기를 제공합니다. 로컬라이즈된 경로를 처리하고 검색 엔진에 필요한 메타데이터를 추가합니다.\n\n> Intlayer에서 생성한 사이트맵은 `xhtml:link` 네임스페이스(Hreflang XML 확장)를 지원합니다. 원시 URL만 나열하는 기본 사이트맵 생성기와 달리, Intlayer는 페이지의 모든 언어 버전(예: `/about`, `/about?lang=fr`, `/about?lang=es`) 간에 필요한 양항향 링크를 자동으로 생성합니다. 이를 통해 검색 엔진이 올바른 언어 버전을 올바른 사용자에게 색인화하고 제공할 수 있도록 보장합니다.\n\n모든 로컬라이즈된 경로를 포함하는 사이트맵을 생성하기 위해 `src/pages/sitemap.xml.ts`를 생성합니다.\n\n```typescript fileName=\"src/pages/sitemap.xml.ts\"\nimport type { APIRoute } from \"astro\";\nimport { generateSitemap, type SitemapUrlEntry } from \"intlayer\";\n\nconst pathList: SitemapUrlEntry[] = [\n { path: \"/\", changefreq: \"daily\", priority: 1.0 },\n { path: \"/about\", changefreq: \"monthly\", priority: 0.7 },\n];\n\nconst SITE_URL = import.meta.env.SITE ?? \"http://localhost:4321\";\n\nexport const GET: APIRoute = async ({ site }) => {\n const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });\n\n return new Response(xmlOutput, {\n headers: { \"Content-Type\": \"application/xml\" },\n });\n};\n```\n\n#### Robots.txt\n\n검색 엔진 크롤링을 제어하기 위해 `src/pages/robots.txt.ts`를 생성합니다.\n\n```typescript fileName=\"src/pages/robots.txt.ts\"\nimport type { APIRoute } from \"astro\";\nimport { getMultilingualUrls } from \"intlayer\";\n\nconst getAllMultilingualUrls = (urls: string[]) =>\n urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);\n\nconst disallowedPaths = getAllMultilingualUrls([\"/admin\", \"/private\"]);\n\nexport const GET: APIRoute = ({ site }) => {\n const robotsTxt = [\n \"User-agent: *\",\n \"Allow: /\",\n ...disallowedPaths.map((path) => `Disallow: ${path}`),\n \"\",\n `Sitemap: ${new URL(\"/sitemap.xml\", site).href}`,\n ].join(\"\\n\");\n\n return new Response(robotsTxt, {\n headers: { \"Content-Type\": \"text/plain\" },\n });\n};\n```\n\n### TypeScript 설정\n\nIntlayer는 모듈 증강(module augmentation)을 사용하여 TypeScript의 이점을 활용함으로써 코드베이스를 더 견고하게 만듭니다. 데코레이터 구문을 사용하는 경우 Lit에서 `experimentalDecorators`를 활성화해야 합니다.\n\n\n\n\n\nTypeScript 설정에 자동 생성된 타입이 포함되어 있는지 확인하세요.\n\n```json5 fileName=\"tsconfig.json\"\n{\n compilerOptions: {\n // ...\n experimentalDecorators: true,\n useDefineForClassFields: false, // 데코레이터 지원을 위해 Lit에서 필수\n },\n include: [\n // ... 기존 TypeScript 설정\n \".intlayer/**/*.ts\", // 자동 생성된 타입 포함\n ],\n}\n```\n\n### Git 설정\n\nIntlayer가 생성한 파일은 무시하는 것이 좋습니다. 이를 통해 Git 리포지토리에 커밋되는 것을 방지할 수 있습니다.\n\n무시하려면 `.gitignore` 파일에 다음 지침을 추가하세요:\n\n```bash\n# Intlayer가 생성한 파일 무시\n.intlayer\n```\n\n### VS Code 확장 프로그램\n\nIntlayer 개발 환경을 개선하기 위해 **공식 Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.\n\n[VS Code Marketplace에서 설치](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)\n\n이 확장 프로그램은 다음 기능을 제공합니다:\n\n- 번역 키 **자동 완성**.\n- 누락된 번역에 대한 **실시간 오류 감지**.\n- 번역된 콘텐츠의 **인라인 미리보기**.\n- 번역을 쉽게 생성하고 업데이트할 수 있는 **빠른 작업(Quick Actions)**.\n\n확장 프로그램 사용에 대한 자세한 내용은 [Intlayer VS Code 확장 프로그램 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.\n\n---\n\n### 15단계: 컴포넌트에서 콘텐츠 추출(선택 사항)\n\n기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.\n\n이 프로세스를 용이하게 하기 위해 Intlayer는 컴포넌트를 변환하고 콘텐츠를 추출하기 위한 [컴파일러](/ko/doc/compiler) / [추출기](/ko/doc/concept/cli/extract)를 제안합니다.\n\n설정하려면 `intlayer.config.ts` 파일에 `compiler` 섹션을 추가할 수 있습니다.\n\n```typescript fileName=\"intlayer.config.ts\" codeFormat=\"typescript\"\nimport { type IntlayerConfig } from \"intlayer\";\n\nconst config: IntlayerConfig = {\n // ... 나머지 구성\n compiler: {\n /**\n * 컴파일러 활성화 여부를 나타냅니다.\n */\n enabled: true,\n\n /**\n * 출력 파일 경로를 정의합니다.\n */\n output: ({ fileName, extension }) => `./${fileName}${extension}`,\n\n /**\n * 변환 후 컴포넌트를 저장할지 여부를 나타냅니다. 그렇게 하면 컴파일러를 한 번만 실행하여 앱을 변환한 다음 제거할 수 있습니다.\n */\n saveComponents: false,\n\n /**\n * 사전 키 접두사\n */\n dictionaryKeyPrefix: \"\",\n },\n};\n\nexport default config;\n```\n\n\n \n\n컴포넌트를 변환하고 콘텐츠를 추출하기 위해 추출기를 실행합니다\n\n```bash packageManager=\"npm\"\nnpx intlayer extract\n```\n\n```bash packageManager=\"pnpm\"\npnpm intlayer extract\n```\n\n```bash packageManager=\"yarn\"\nyarn intlayer extract\n```\n\n```bash packageManager=\"bun\"\nbun x intlayer extract\n```\n\n \n \n\n`vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.\n\n```ts fileName=\"vite.config.ts\"\nimport { defineConfig } from \"vite\";\nimport { intlayer, intlayerCompiler } from \"vite-intlayer\";\n\nexport default defineConfig({\n plugins: [\n intlayer(),\n intlayerCompiler(), // 컴파일러 플러그인을 추가합니다\n ],\n});\n```\n\n \n\n\n---\n\n### 더 알아보기\n\n더 자세히 알고 싶다면 [비주얼 에디터](/ko/doc/concept/editor)를 구현하거나 [CMS](/ko/doc/concept/cms)를 사용하여 콘텐츠를 외부화할 수 있습니다.\n","about":"Intlayer를 사용하여 Astro + Lit 사이트에 국제화(i18n)를 추가하는 방법을 배워보세요. 이 가이드를 따라 사이트를 다국어로 만들어 보세요.","url":"https://intlayer.org/ko/doc/environment/astro/lit","datePublished":"24-04-2026","dateModified":"06-05-2026","keywords":"국제화, 문서, Intlayer, Astro, Lit, 웹 컴포넌트, i18n, JavaScript","license":"https://raw.githubusercontent.com/aymericzip/intlayer/refs/heads/main/LICENSE","audience":{"@type":"Audience","audienceType":"개발자, 콘텐츠 관리자"}}

생성:2026-04-24마지막 업데이트:2026-05-06