@intlayer/docs 9.5.5 → 9.5.7

package/docs/ko/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-09-19
+updatedAt: 2026-09-21
 title: "Astro i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Astro 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -160,6 +160,29 @@ bun add intlayer astro-intlayer
 </Step>
 <Step number={2} title="프로젝트 설정">
 
+### 아키텍처
+
+이 아키텍처에서 `astro.config.ts`에 등록된 `intlayer()` 통합은 사전을 빌드하고 모든 요청의 로케일을 확인하여 `Astro.locals.intlayer`에 노출하는 미들웨어를 추가합니다. 페이지는 `src/pages/[...locale]/` 나머지(rest) 세그먼트 아래에 위치하므로 기본 로케일은 접두사 없이 제공되고 다른 모든 로케일은 전용 URL을 갖습니다. `.astro` 파일은 `astro-intlayer`의 `useIntlayer` / `useLocale` 훅을 사용하여 콘텐츠를 읽으며, 콘텐츠 선언은 `src/`의 컴포넌트와 함께 배치됩니다.
+
+```bash
+.
+├── src
+│   ├── app.content.tsx               # App content declaration
+│   ├── components
+│   │   └── LocaleSwitcher.astro      # Locale switcher component
+│   └── pages
+│       ├── [...locale]
+│       │   └── index.astro           # Localized page (rest param also serves the default locale)
+│       ├── robots.txt.ts             # robots.txt endpoint
+│       └── sitemap.xml.ts            # Localized sitemap endpoint
+├── astro.config.ts                   # Astro config with the intlayer() integration
+├── intlayer.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### 설정
+
 애플리케이션의 언어를 설정하기 위한 설정 파일을 생성합니다:
 
 ```typescript fileName="intlayer.config.ts"
@@ -401,7 +424,7 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 ```
 
 > **영속성에 대한 참고 사항:**
-> 클라이언트 측 `useLocale`의 `setLocale`은 사용자의 언어 설정을 쿠키에 저장합니다. 이를 통해 Intlayer 미들웨어는 선택 항목을 기억하고 향후 방문 시 사용자를 선호하는 언어로 자동 리디렉션할 수 있습니다.
+> 클라이언트 측 `useLocale`의 `setLocale`은 사용자의 언어 설정을 쿠키에 저장합니다. 이를 통해 Intlayer는 선택 사항을 기억하고 향후 방문 시 사용자를 선호하는 언어로 자동 리디렉션할 수 있습니다. 온디맨드 렌더링 페이지(`output: 'server'` 또는 `prerender = false`인 어댑터)는 HTML이 전송되기 전에 Intlayer 미들웨어에 의해 리디렉션되며, 정적 파일로 제공되는 사전 렌더링 페이지는 통합 플러그인이 모든 페이지에 삽입하는 작은 스크립트에 의해 리디렉션됩니다. 둘 다 끄려면 `routing.enableProxy`를 `false`로 설정하세요. `astro dev`에서는 `routing.enableProxy`가 `true`로 설정되지 않는 한 쿠키가 리디렉션 소스로 무시되므로 오래된 쿠키가 작업 중인 페이지를 가로채지 않습니다.
 >
 > **서버 / 클라이언트 상호 호환성:**
 > `astro-intlayer`는 프론트매터에서는 서버 훅(`Astro.locals` 읽기)으로 확인되고, `<script>` 블록과 아일랜드에서는 `vanilla-intlayer`의 클라이언트 훅으로 확인되며 동일한 이름과 데이터 구조를 가집니다. `setLocale`과 `onChange`는 클라이언트에서만 동작하므로, 클라이언트 스토어를 초기화하려면 클라이언트에서 `installIntlayer()`를 한 번 호출하세요. `astro-intlayer/client`는 클라이언트 엔트리를 명시적으로 노출합니다.
@@ -428,10 +451,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -478,7 +501,6 @@ export const GET: APIRoute = ({ site }) => {
 - Intlayer + Solid: [Intlayer with Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_astro_solid.md)
 - Intlayer + Preact: [Intlayer with Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_astro_preact.md)
 - Intlayer + Lit: [Intlayer with Lit](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_astro_lit.md)
-- Intlayer + Vanilla JS: [Intlayer with Vanilla JS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_astro_vanilla.md)
 </Step>
 
 <Step number={15} title="컴포넌트에서 콘텐츠 추출" isOptional={true}>
@@ -548,21 +570,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> v9 이후로, `intlayerCompiler`는 `intlayer` 플러그인에 포함되어 있습니다. 따라서 수동으로 추가할 필요가 없습니다.
-
-`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(), // 컴파일러 플러그인 추가
-  ],
-});
-```
+애플리케이션을 빌드하여 컴포넌트를 변환하고 콘텐츠를 추출합니다.
 
 ```bash packageManager="npm"
 npm run build # 또는 npm run dev

package/docs/ko/intlayer_with_astro_lit.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-08-30
+updatedAt: 2026-09-21
 title: "Astro + Lit i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Astro + Lit 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -20,6 +20,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Astro 페이지에서 astro-intlayer의 useIntlayer / useLocale 훅 사용"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
@@ -163,7 +166,7 @@ bun x intlayer init
   설정 관리, 번역, [콘텐츠 선언](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 리디렉션을 처리하는 미들웨어가 포함되어 있습니다.
+  Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Astro 통합 플러그인, 모든 요청의 로케일을 `Astro.locals.intlayer`로 확인하는 미들웨어, `useIntlayer` / `useDictionary` / `useLocale` 훅이 포함되어 있습니다. 동일한 import 경로가 `.astro` 프론트매터에서는 서버 구현체로, `<script>` 블록에서는 클라이언트 구현체(`vanilla-intlayer` 기반)로 확인됩니다.
 
 - **lit**
   빠르고 가벼운 웹 컴포넌트를 빌드하기 위한 핵심 Lit 패키지입니다.
@@ -177,6 +180,30 @@ bun x intlayer init
 </Step>
 <Step number={2} title="프로젝트 설정">
 
+### 아키텍처
+
+이 아키텍처에서 `astro.config.ts`에 등록된 `intlayer()` 통합은 사전을 빌드하고 모든 요청의 로케일을 확인하여 `Astro.locals.intlayer`에 노출하는 미들웨어를 추가합니다. 페이지는 `src/pages/[...locale]/` 나머지(rest) 세그먼트 아래에 위치하므로 기본 로케일은 접두사 없이 제공되고 다른 모든 로케일은 전용 URL을 갖습니다. `.astro` 파일은 서버 렌더링을 위해 `astro-intlayer`의 `useIntlayer` / `useLocale` 훅을 사용하여 콘텐츠를 읽고, Lit 아일랜드(`src/components/lit/LitDemo.ts`)는 서버에서 감지된 로케일을 prop으로 받아 대화형 처리를 위해 `lit-intlayer`에 전달합니다. 콘텐츠 선언은 `src/`의 컴포넌트와 함께 배치됩니다.
+
+```bash
+.
+├── src
+│   ├── components
+│   │   └── lit
+│   │       ├── app.content.ts        # App content declaration
+│   │       └── LitDemo.ts            # Lit custom element (content + locale switcher)
+│   └── pages
+│       ├── [...locale]
+│       │   └── index.astro           # Localized page mounting the custom element
+│       ├── robots.txt.ts             # robots.txt endpoint
+│       └── sitemap.xml.ts            # Localized sitemap endpoint
+├── astro.config.ts                   # Astro config with the intlayer() and lit() integrations
+├── intlayer.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### 설정
+
 애플리케이션의 언어를 설정하기 위한 설정 파일을 생성합니다:
 
 ```typescript fileName="intlayer.config.ts"
@@ -257,19 +284,21 @@ export default litDemoContent;
 </Step>
 <Step number={5} title="Astro에서 콘텐츠 사용">
 
-`intlayer`에서 내보낸 핵심 헬퍼를 사용하여 `.astro` 파일에서 직접 사전을 소비할 수 있습니다. 또한 각 페이지에 hreflang 및 canonical 링크와 같은 SEO 메타데이터를 추가해야 합니다. Lit 커스텀 엘리먼트는 클라이언트 사이드 `<script>`를 통해 임포트되어 body에 배치됩니다.
+`astro-intlayer`에서 내보낸 훅을 사용하여 `.astro` 파일에서 사전을 사용하세요. 이 훅들은 `react-intlayer`와 동일한 시그니처를 공유합니다. `useIntlayer("key")`는 사전의 내용을 반환하고 `useLocale()`은 인수를 전달할 필요 없이 현재 로케일을 반환합니다.
+
+로케일은 통합 플러그인이 자체 `src/middleware.ts`보다 먼저 등록하는 `astro-intlayer` 미들웨어에서 제공됩니다. URL 접두사, 클라이언트가 저장한 로케일(쿠키 또는 헤더), `Accept-Language` 순으로 모든 요청에 대해 로케일을 확인하고 이를 `Astro.locals.intlayer`에 저장합니다. 사전 렌더링된 페이지는 방문자마다 한 번만 렌더링되므로 URL만 사용합니다.
+
+Lit 커스텀 엘리먼트는 클라이언트 사이드 `<script>`를 통해 임포트되어 body에 배치됩니다.
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 
 export const getStaticPaths = () => {
@@ -278,8 +307,11 @@ export const getStaticPaths = () => {
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { greeting } = getIntlayer("lit-demo", locale);
+// 미들웨어에 의해 확인된 로케일 (예: /ko/about -> 'ko')
+const { locale } = useLocale();
+
+// 해당 로케일의 'lit-demo' 사전 내용
+const { greeting } = useIntlayer("lit-demo");
 ---
 
 <!doctype html>
@@ -338,6 +370,8 @@ const { greeting } = getIntlayer("lit-demo", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> `Astro.locals.intlayer`는 자체 미들웨어 및 엔드포인트에 `locale`, `defaultLocale`, `availableLocales`도 노출합니다. 단일 호출에 대해 요청 로케일을 재정의하려면 로케일이나 선택기를 두 번째 인수로 전달하세요(`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`).
+
 > **라우팅 설정에 관한 참고 사항:**
 > 사용하는 디렉토리 구조는 `intlayer.config.ts`의 `middleware.routing` 설정에 따라 달라집니다:
 >
@@ -494,10 +528,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -601,21 +635,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> v9부터 `intlayerCompiler`는 `intlayer` plugin에 포함되어 있습니다. 따라서 수동으로 추가할 필요가 없습니다.
-
-`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(), // 컴파일러 플러그인 추가
-  ],
-});
-```
+애플리케이션을 빌드하여 컴포넌트를 변환하고 콘텐츠를 추출합니다.
 
 ```bash packageManager="npm"
 npm run build # 또는 npm run dev

package/docs/ko/intlayer_with_astro_preact.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-08-30
+updatedAt: 2026-09-21
 title: "Astro + Preact i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Astro + Preact 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -19,6 +19,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Astro 페이지에서 astro-intlayer의 useIntlayer / useLocale 훅 사용"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
@@ -162,7 +165,7 @@ bun x intlayer init
   설정 관리, 번역, [콘텐츠 선언](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 리디렉션을 처리하는 미들웨어가 포함되어 있습니다.
+  Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Astro 통합 플러그인, 모든 요청의 로케일을 `Astro.locals.intlayer`로 확인하는 미들웨어, `useIntlayer` / `useDictionary` / `useLocale` 훅이 포함되어 있습니다. 동일한 import 경로가 `.astro` 프론트매터에서는 서버 구현체로, `<script>` 블록에서는 클라이언트 구현체(`vanilla-intlayer` 기반)로 확인됩니다.
 
 - **preact**
   핵심 Preact 패키지 - React의 빠르고 가벼운 대안입니다.
@@ -176,6 +179,31 @@ bun x intlayer init
 </Step>
 <Step number={2} title="프로젝트 설정">
 
+### 아키텍처
+
+이 아키텍처에서 `astro.config.ts`에 등록된 `intlayer()` 통합은 사전을 빌드하고 모든 요청의 로케일을 확인하여 `Astro.locals.intlayer`에 노출하는 미들웨어를 추가합니다. 페이지는 `src/pages/[...locale]/` 나머지(rest) 세그먼트 아래에 위치하므로 기본 로케일은 접두사 없이 제공되고 다른 모든 로케일은 전용 URL을 갖습니다. `.astro` 파일은 서버 렌더링을 위해 `astro-intlayer`의 `useIntlayer` / `useLocale` 훅을 사용하여 콘텐츠를 읽고, Preact 아일랜드(`src/components/preact/PreactIsland.tsx`)는 서버에서 감지된 로케일을 prop으로 받아 대화형 처리를 위해 `preact-intlayer`에 전달합니다. 콘텐츠 선언은 `src/`의 컴포넌트와 함께 배치됩니다.
+
+```bash
+.
+├── src
+│   ├── app.content.tsx               # App content declaration
+│   ├── components
+│   │   └── preact
+│   │       ├── LocaleSwitcher.tsx    # Locale switcher rendered inside the island
+│   │       └── PreactIsland.tsx      # Preact island wrapping the tree in IntlayerProvider
+│   └── pages
+│       ├── [...locale]
+│       │   └── index.astro           # Localized page mounting the island
+│       ├── robots.txt.ts             # robots.txt endpoint
+│       └── sitemap.xml.ts            # Localized sitemap endpoint
+├── astro.config.ts                   # Astro config with the intlayer() and preact() integrations
+├── intlayer.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### 설정
+
 애플리케이션의 언어를 설정하기 위한 설정 파일을 생성합니다:
 
 ```typescript fileName="intlayer.config.ts"
@@ -253,19 +281,21 @@ export default appContent;
 </Step>
 <Step number={5} title="Astro에서 콘텐츠 사용">
 
-`intlayer`에서 내보낸 핵심 헬퍼를 사용하여 `.astro` 파일에서 직접 사전을 소비할 수 있습니다. 또한 각 페이지에 hreflang 및 canonical 링크와 같은 SEO 메타데이터를 추가하고, 클라이언트 사이드의 인터랙티브 콘텐츠를 위해 Preact 아일랜드를 포함해야 합니다.
+`astro-intlayer`에서 내보낸 훅을 사용하여 `.astro` 파일에서 사전을 사용하세요. 이 훅들은 `react-intlayer`와 동일한 시그니처를 공유합니다. `useIntlayer("key")`는 사전의 내용을 반환하고 `useLocale()`은 인수를 전달할 필요 없이 현재 로케일을 반환합니다.
+
+로케일은 통합 플러그인이 자체 `src/middleware.ts`보다 먼저 등록하는 `astro-intlayer` 미들웨어에서 제공됩니다. URL 접두사, 클라이언트가 저장한 로케일(쿠키 또는 헤더), `Accept-Language` 순으로 모든 요청에 대해 로케일을 확인하고 이를 `Astro.locals.intlayer`에 저장합니다. 사전 렌더링된 페이지는 방문자마다 한 번만 렌더링되므로 URL만 사용합니다.
+
+또한 각 페이지에 hreflang 및 canonical 링크와 같은 SEO 메타데이터를 추가하고, 클라이언트 사이드의 인터랙티브 콘텐츠를 위해 Preact 아일랜드를 포함해야 합니다.
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 import { PreactIsland } from "../../components/preact/PreactIsland";
 
@@ -275,8 +305,11 @@ export const getStaticPaths = () => {
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { title } = getIntlayer("app", locale);
+// 미들웨어에 의해 확인된 로케일 (예: /ko/about -> 'ko')
+const { locale } = useLocale();
+
+// 해당 로케일의 'app' 사전 내용
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -332,6 +365,8 @@ const { title } = getIntlayer("app", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> `Astro.locals.intlayer`는 자체 미들웨어 및 엔드포인트에 `locale`, `defaultLocale`, `availableLocales`도 노출합니다. 단일 호출에 대해 요청 로케일을 재정의하려면 로케일이나 선택기를 두 번째 인수로 전달하세요(`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`).
+
 > **라우팅 설정에 관한 참고 사항:**
 > 사용하는 디렉토리 구조는 `intlayer.config.ts`의 `middleware.routing` 설정에 따라 달라집니다:
 >
@@ -448,10 +483,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -555,21 +590,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> v9부터 `intlayerCompiler`가 `intlayer` 플러그인에 포함되어 있습니다. 따라서 수동으로 추가할 필요가 없습니다.
-
-`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(), // 컴파일러 플러그인 추가
-  ],
-});
-```
+애플리케이션을 빌드하여 컴포넌트를 변환하고 콘텐츠를 추출합니다.
 
 ```bash packageManager="npm"
 npm run build # 또는 npm run dev

package/docs/ko/intlayer_with_astro_react.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-08-30
+updatedAt: 2026-09-21
 title: "Astro + React i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Astro + React 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -19,6 +19,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Astro 페이지에서 astro-intlayer의 useIntlayer / useLocale 훅 사용"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
@@ -165,7 +168,7 @@ bun x intlayer init
   설정 관리, 번역, [콘텐츠 선언](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 리디렉션을 처리하는 미들웨어가 포함되어 있습니다.
+  Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Astro 통합 플러그인, 모든 요청의 로케일을 `Astro.locals.intlayer`로 확인하는 미들웨어, `useIntlayer` / `useDictionary` / `useLocale` 훅이 포함되어 있습니다. 동일한 import 경로가 `.astro` 프론트매터에서는 서버 구현체로, `<script>` 블록에서는 클라이언트 구현체(`vanilla-intlayer` 기반)로 확인됩니다.
 
 - **react**, **react-dom**
   브라우저에서 React 컴포넌트를 렌더링하는 데 필요한 핵심 React 패키지입니다.
@@ -179,6 +182,31 @@ bun x intlayer init
 </Step>
 <Step number={2} title="프로젝트 설정">
 
+### 아키텍처
+
+이 아키텍처에서 `astro.config.ts`에 등록된 `intlayer()` 통합은 사전을 빌드하고 모든 요청의 로케일을 확인하여 `Astro.locals.intlayer`에 노출하는 미들웨어를 추가합니다. 페이지는 `src/pages/[...locale]/` 나머지(rest) 세그먼트 아래에 위치하므로 기본 로케일은 접두사 없이 제공되고 다른 모든 로케일은 전용 URL을 갖습니다. `.astro` 파일은 서버 렌더링을 위해 `astro-intlayer`의 `useIntlayer` / `useLocale` 훅을 사용하여 콘텐츠를 읽고, React 아일랜드(`src/components/react/ReactIsland.tsx`)는 서버에서 감지된 로케일을 prop으로 받아 대화형 처리를 위해 `react-intlayer`에 전달합니다. 콘텐츠 선언은 `src/`의 컴포넌트와 함께 배치됩니다.
+
+```bash
+.
+├── src
+│   ├── app.content.tsx               # App content declaration
+│   ├── components
+│   │   └── react
+│   │       ├── LocaleSwitcher.tsx    # Locale switcher rendered inside the island
+│   │       └── ReactIsland.tsx       # React island wrapping the tree in IntlayerProvider
+│   └── pages
+│       ├── [...locale]
+│       │   └── index.astro           # Localized page mounting the island
+│       ├── robots.txt.ts             # robots.txt endpoint
+│       └── sitemap.xml.ts            # Localized sitemap endpoint
+├── astro.config.ts                   # Astro config with the intlayer() and react() integrations
+├── intlayer.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### 설정
+
 애플리케이션의 언어를 설정하기 위한 설정 파일을 생성합니다:
 
 ```typescript fileName="intlayer.config.ts"
@@ -254,19 +282,21 @@ export default appContent;
 </Step>
 <Step number={5} title="Astro에서 콘텐츠 사용">
 
-`intlayer`에서 내보낸 핵심 헬퍼를 사용하여 `.astro` 파일에서 직접 사전을 소비할 수 있습니다. 또한 각 페이지에 hreflang 및 canonical 링크와 같은 SEO 메타데이터를 추가하고, 클라이언트 사이드의 인터랙티브 콘텐츠를 위해 React 아일랜드를 포함해야 합니다.
+`astro-intlayer`에서 내보낸 훅을 사용하여 `.astro` 파일에서 사전을 사용하세요. 이 훅들은 `react-intlayer`와 동일한 시그니처를 공유합니다. `useIntlayer("key")`는 사전의 내용을 반환하고 `useLocale()`은 인수를 전달할 필요 없이 현재 로케일을 반환합니다.
+
+로케일은 통합 플러그인이 자체 `src/middleware.ts`보다 먼저 등록하는 `astro-intlayer` 미들웨어에서 제공됩니다. URL 접두사, 클라이언트가 저장한 로케일(쿠키 또는 헤더), `Accept-Language` 순으로 모든 요청에 대해 로케일을 확인하고 이를 `Astro.locals.intlayer`에 저장합니다. 사전 렌더링된 페이지는 방문자마다 한 번만 렌더링되므로 URL만 사용합니다.
+
+또한 각 페이지에 hreflang 및 canonical 링크와 같은 SEO 메타데이터를 추가하고, 클라이언트 사이드의 인터랙티브 콘텐츠를 위해 React 아일랜드를 포함해야 합니다.
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 import { ReactIsland } from "../../components/react/ReactIsland";
 
@@ -276,8 +306,11 @@ export const getStaticPaths = () => {
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { title } = getIntlayer("app", locale);
+// 미들웨어에 의해 확인된 로케일 (예: /ko/about -> 'ko')
+const { locale } = useLocale();
+
+// 해당 로케일의 'app' 사전 내용
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -333,6 +366,8 @@ const { title } = getIntlayer("app", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> `Astro.locals.intlayer`는 자체 미들웨어 및 엔드포인트에 `locale`, `defaultLocale`, `availableLocales`도 노출합니다. 단일 호출에 대해 요청 로케일을 재정의하려면 로케일이나 선택기를 두 번째 인수로 전달하세요(`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`).
+
 > **라우팅 설정에 관한 참고 사항:**
 > 사용하는 디렉토리 구조는 `intlayer.config.ts`의 `middleware.routing` 설정에 따라 달라집니다:
 >
@@ -445,10 +480,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -552,21 +587,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> v9 이후로 `intlayerCompiler`는 `intlayer` 플러그인에 포함되어 있습니다. 따라서 수동으로 추가할 필요가 없습니다.
-
-`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(), // 컴파일러 플러그인을 추가합니다
-  ],
-});
-```
+애플리케이션을 빌드하여 컴포넌트를 변환하고 콘텐츠를 추출합니다.
 
 ```bash packageManager="npm"
 npm run build # 또는 npm run dev