@intlayer/docs 9.5.4 → 9.5.6

package/docs/ko/how_works_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-12
-updatedAt: 2026-08-30
+updatedAt: 2026-09-19
 title: Intlayer 작동 방식
 description: Intlayer가 내부적으로 어떻게 작동하는지 알아보세요. Intlayer를 강력하게 만드는 아키텍처와 구성 요소를 이해하십시오.
 keywords:
@@ -135,49 +135,105 @@ Intlayer는 번역 프로세스에서 특정 역할을 하는 여러 패키지
 
 `intlayer` 패키지는 애플리케이션에서 콘텐츠 파일 내의 콘텐츠를 선언하는 데 사용됩니다.
 
-### react-intlayer
+### 프론트엔드 프레임워크
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
 
 `react-intlayer` 패키지는 Intlayer 사전을 해석하여 React 애플리케이션에서 사용할 수 있도록 합니다.
 
-### next-intlayer
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
 
 `next-intlayer` 패키지는 `react-intlayer` 위에 레이어로 작동하여 Intlayer 사전을 Next.js 애플리케이션에서 사용할 수 있도록 합니다. 번역 미들웨어, 라우팅, 또는 `next.config.js` 파일 구성과 같은 Next.js 환경에서 Intlayer가 작동하도록 필수 기능을 통합합니다.
 
-### vue-intlayer
+  </Tab>
+  <Tab label="Vue" value="vue">
 
 `vue-intlayer` 패키지는 Intlayer 사전을 해석하여 Vue 애플리케이션에서 사용할 수 있도록 합니다.
 
-### nuxt-intlayer
+  </Tab>
+  <Tab label="Nuxt" value="nuxt">
 
 `nuxt-intlayer` 패키지는 Nuxt 모듈로서 Intlayer 사전을 Nuxt 애플리케이션에서 사용할 수 있도록 합니다. 이 패키지는 번역 미들웨어, 라우팅, `nuxt.config.js` 파일 구성 등 Nuxt 환경에서 Intlayer가 작동하는 데 필요한 필수 기능을 통합합니다.
 
-### svelte-intlayer (작업 중)
+  </Tab>
+  <Tab label="Svelte" value="svelte">
 
 `svelte-intlayer` 패키지는 Intlayer 사전을 해석하여 Svelte 애플리케이션에서 사용할 수 있도록 합니다.
 
-### solid-intlayer (작업 중)
+  </Tab>
+  <Tab label="Solid" value="solid">
 
 `solid-intlayer` 패키지는 Intlayer 사전을 해석하여 Solid.js 애플리케이션에서 사용할 수 있도록 합니다.
 
-### preact-intlayer
+  </Tab>
+  <Tab label="Preact" value="preact">
 
 `preact-intlayer` 패키지는 Intlayer 사전을 해석하여 Preact 애플리케이션에서 사용할 수 있도록 합니다.
 
-### angular-intlayer (작업 중)
+  </Tab>
+  <Tab label="Angular" value="angular">
 
 `angular-intlayer` 패키지는 Intlayer 사전을 해석하여 Angular 애플리케이션에서 사용할 수 있도록 합니다.
 
-### express-intlayer
+  </Tab>
+  <Tab label="Astro" value="astro">
 
-`express-intlayer` 패키지는 Express.js 백엔드에서 Intlayer를 사용할 수 있도록 합니다.
+`astro-intlayer` 패키지는 Intlayer를 Astro 애플리케이션에 통합하기 위한 필수 도구를 제공합니다. 로케일 기반 라우팅 및 사전 관리(딕셔너리 관리를) 구성합니다.
+
+  </Tab>
+  <Tab label="Remix" value="remix">
+
+`remix-intlayer` 패키지는 Intlayer를 Remix 애플리케이션에 통합하기 위한 필수 도구를 제공합니다. 로케일 기반 라우팅, 서버 측 컨텍스트 및 사전 관리를 구성합니다.
 
-### react-native-intlayer
+  </Tab>
+  <Tab label="React Native" value="react-native">
 
 `react-native-intlayer` 패키지는 Metro 번들러와 함께 작동하도록 Intlayer 플러그인을 통합하는 도구를 제공합니다.
 
-### lynx-intlayer
+  </Tab>
+  <Tab label="Lit" value="lit">
+
+`lit-intlayer` 패키지는 Lit 애플리케이션에서 Intlayer 사전을 해석하고 사용하기 위한 도구와 컴포넌트를 제공합니다.
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+
+`vanilla-intlayer` 패키지는 Intlayer를 바닐라 JavaScript, HTML 또는 PHP 애플리케이션에 통합하기 위한 도구를 제공합니다.
+
+  </Tab>
+</Tabs>
+
+### 백엔드 프레임워크
+
+<Tabs group="backend">
+  <Tab label="Express" value="express">
+
+`express-intlayer` 패키지는 Express.js 백엔드에서 Intlayer를 사용할 수 있도록 합니다.
+
+  </Tab>
+  <Tab label="Fastify" value="fastify">
+
+`fastify-intlayer` 패키지는 Fastify 애플리케이션에서 국제화를 처리하기 위한 플러그인을 제공합니다. 사용자 로케일을 감지하고 요청(request) 객체에 데코레이터를 추가합니다.
 
-`lynx-intlayer` 패키지는 Lynx 번들러와 함께 작동하도록 Intlayer 플러그인을 통합하는 도구를 제공합니다.
+  </Tab>
+  <Tab label="Hono" value="hono">
+
+`hono-intlayer` 패키지는 국제화를 처리하기 위한 Hono 애플리케이션용 미들웨어를 제공합니다. 사용자의 로케일을 감지하고 컨텍스트 객체를 채웁니다.
+
+  </Tab>
+  <Tab label="Elysia" value="elysia">
+
+`elysia-intlayer` 패키지는 Elysia 애플리케이션에서 국제화를 처리하기 위한 플러그인을 제공합니다. 사용자 로케일을 감지하고 라우트 컨텍스트에 `intlayer` 객체를 주입합니다.
+
+  </Tab>
+  <Tab label="AdonisJS" value="adonis">
+
+`adonis-intlayer` 패키지는 AdonisJS 애플리케이션이 국제화를 처리할 수 있도록 미들웨어를 제공합니다. 사용자의 로케일을 감지하고 번역 기능을 제공합니다.
+
+  </Tab>
+</Tabs>
 
 ### vite-intlayer
 
@@ -187,6 +243,10 @@ Intlayer는 번역 프로세스에서 특정 역할을 하는 여러 패키지
 
 `react-scripts-intlayer` 명령어와 플러그인을 포함하며, Create React App 기반 애플리케이션과 Intlayer를 통합하는 데 사용됩니다. 이 플러그인들은 [craco](https://craco.js.org/)를 기반으로 하며, [Webpack](https://webpack.js.org/) 번들러에 대한 추가 구성을 포함합니다.
 
+### eslint-plugin-intlayer
+
+`eslint-plugin-intlayer` 패키지는 번역되지 않은 문자열을 감지하고 사전 정의를 검증하며 i18n 모범 사례를 적용하기 위한 ESLint 및 oxlint 규칙을 제공합니다.
+
 ### intlayer-editor
 
 `intlayer-editor` 패키지는 시각적 편집기를 사용할 수 있도록 하는 데 사용됩니다. 이 패키지는 선택 사항으로, 애플리케이션에 설치할 수 있으며 `react-intlayer` 패키지에서 사용됩니다.  
@@ -220,6 +280,18 @@ Express를 기반으로 한 서버는 시각적 편집기 요청을 수신하고
 
 `@intlayer/mcp` 패키지는 Intlayer 생태계에 맞춘 AI 기반 IDE 지원을 제공하는 MCP(Model Context Protocol) 서버를 제공합니다. 이 서버는 문서를 자동으로 로드하며 Intlayer CLI와 통합됩니다.
 
+### @intlayer/lsp
+
+`@intlayer/lsp` 패키지는 Intlayer에 맞춘 Language Server Protocol (LSP) 서버를 제공합니다. 정의로 이동, 모든 참조 찾기, 호버 미리보기, 사전 키 자동 완성 및 진단 경고와 같은 IDE 기능을 지원합니다.
+
+### @intlayer/ai
+
+`@intlayer/ai` 패키지는 Intlayer 애플리케이션을 위한 SDK 기능을 제공하여 자동 번역 및 AI 기반 콘텐츠 생성을 지원합니다.
+
+### @intlayer/analytics
+
+`@intlayer/analytics` 패키지는 콘텐츠 노출 지표, 페이지/로케일 및 노드 수준 분석을 수집하고 콘텐츠 A/B 테스트를 지원하는 도구를 제공합니다.
+
 ### @intlayer/dictionaries-entry
 
 `@intlayer/dictionaries-entry` 패키지는 Intlayer 사전의 진입 경로를 반환합니다. 루트의 병합된 사전과 `/unmerged`, `/remote`, `/dynamic`, `/fetch` 하위 경로의 미병합, 원격, 동적 및 fetch 사전입니다. 브라우저에서 파일 시스템을 검색하는 것이 불가능하기 때문에, Webpack이나 Rollup과 같은 번들러를 사용하여 사전의 진입 경로를 가져오는 것은 불가능합니다. 이 패키지와 해당 하위 경로는 별칭(alias)으로 설계되어 Vite, Webpack, Turbopack 등 다양한 번들러에서 번들링 최적화를 가능하게 합니다.

package/docs/ko/intlayer_visual_editor.md

@@ -278,6 +278,13 @@ pnpm intlayer-editor start -e development
 
 비주얼 에디터는 편집 후 재빌드가 허용되는 개발 및 스테이징 환경용으로 설계되었습니다. 배포 없이 실시간 사이트의 콘텐츠를 편집하려면 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)와 원격 사전을 사용하는 것이 좋습니다.
 
+</Question>
+<Question title="비주얼 에디터의 비용은 얼마인가요? 필요하지 않은 경우 과도한가요?">
+
+Intlayer 비주얼 에디터는 설정되지 않은 경우 애플리케이션에 **비용이 전혀 들지 않습니다**. 추가 로직은 명시적으로 활성화되고 필요할 때만 로드됩니다.
+
+활성화하더라도 대부분의 로직은 [app.intlayer.org](https://app.intlayer.org)의 서버 에디터나 `intlayer-editor` 패키지를 통해 처리되므로 영향은 극히 미미합니다(활성화 시 동적으로 로드되는 +5 kB에 불과함). 비주얼 편집 없이 간단한 번역 솔루션만 필요한 경우 Intlayer는 앱에 어떠한 오버헤드도 추가하지 않습니다.
+
 </Question>
 <Question title="비주얼 에디터는 무료인가요?">
 

package/docs/ko/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-08-30
+updatedAt: 2026-09-20
 title: "Astro i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Astro 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -18,6 +18,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-intlayer에 useIntlayer / useLocale 훅 및 Astro.locals 미들웨어 추가"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
@@ -152,7 +155,7 @@ bun add intlayer astro-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 리디렉션을 처리하는 미들웨어가 포함되어 있습니다.
+  Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Astro 통합 플러그인, 모든 요청의 로케일을 `Astro.locals.intlayer`로 확인하는 미들웨어, `useIntlayer` / `useDictionary` / `useLocale` 훅이 포함되어 있습니다. 동일한 import 경로가 `.astro` 프론트매터에서는 서버 구현체로, `<script>` 블록에서는 클라이언트 구현체(`vanilla-intlayer` 기반)로 확인됩니다.
 
 </Step>
 <Step number={2} title="프로젝트 설정">
@@ -229,26 +232,28 @@ export default appContent;
 </Step>
 <Step number={5} title="Astro에서 콘텐츠 사용">
 
-`intlayer`에서 내보낸 핵심 헬퍼를 사용하여 `.astro` 파일에서 직접 사전을 소비할 수 있습니다.
+`astro-intlayer`에서 내보낸 훅을 사용하여 `.astro` 파일에서 사전을 사용하세요. 이 훅들은 `react-intlayer`와 동일한 시그니처를 공유합니다. `useIntlayer("key")`는 사전의 내용을 반환하고 `useLocale()`은 인수를 전달할 필요 없이 현재 로케일을 반환합니다.
+
+로케일은 통합 플러그인이 자체 `src/middleware.ts`보다 먼저 등록하는 `astro-intlayer` 미들웨어에서 제공됩니다. URL 접두사, 클라이언트가 저장한 로케일(쿠키 또는 헤더), `Accept-Language` 순으로 모든 요청에 대해 로케일을 확인하고 이를 `Astro.locals.intlayer`에 저장합니다. 사전 렌더링된 페이지는 방문자마다 한 번만 렌더링되므로 URL만 사용합니다.
+
+또한 각 페이지에 hreflang 및 정식(canonical) 링크와 같은 SEO 메타데이터를 추가하고 사용자가 언어를 변경할 수 있도록 언어 전환기를 포함해야 합니다.
 
 ```astro fileName="src/pages/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 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;
+// 미들웨어에 의해 확인된 로케일 (예: /ko/about -> 'ko')
+const { locale } = useLocale();
 
-// Get the content for the 'app' dictionary
-const { title } = getIntlayer("app", locale);
+// 해당 로케일의 'app' 사전 내용
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -300,6 +305,8 @@ const { title } = getIntlayer("app", locale);
 </html>
 ```
 
+> `Astro.locals.intlayer`는 자체 미들웨어 및 엔드포인트에 `locale`, `defaultLocale`, `availableLocales`도 노출합니다. 단일 호출에 대해 요청 로케일을 재정의하려면 로케일이나 선택기를 두 번째 인수로 전달하세요(`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`).
+
 </Step>
 <Step number={6} title="로컬라이즈된 라우팅">
 
@@ -325,44 +332,51 @@ Astro 통합은 개발 중에 언어 인식 라우팅 및 환경 정의를 돕
 
 ```astro fileName="src/components/LocaleSwitcher.astro"
 ---
-import {
-  locales,
-  getLocaleName,
-  getLocalizedUrl,
-  getLocaleFromPath,
-  getPathWithoutLocale,
-  type LocalesValues,
-} from "intlayer";
+import { useLocale } from "astro-intlayer";
+import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+const { locale, availableLocales } = useLocale();
 const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 ---
 
-<nav>
-  {
-    locales.map((localeItem) => (
-      <a
-        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
-        data-locale={localeItem}
-        aria-current={localeItem === locale ? "page" : undefined}
-      >
-        {getLocaleName(localeItem)}
-      </a>
-    ))
-  }
+<nav aria-label="Languages">
+  <ul>
+    {
+      availableLocales.map((localeItem) => (
+        <li key={localeItem} class="p-1">
+          <a
+            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+            data-locale={localeItem}
+            aria-current={localeItem === locale ? "page" : undefined}
+          >
+            {getLocaleName(localeItem)}
+          </a>
+        </li>
+      ))
+    }
+  </ul>
 </nav>
 
 <script>
-  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";
+  // 브라우저에서는 동일한 import가 클라이언트 구현체로 확인됩니다
+  import { useLocale } from "astro-intlayer";
+  import { getLocalizedUrl, type LocalesValues } from "intlayer";
+
+  // 로케일 쿠키에 선택 사항을 저장한 다음 현지화된 URL로 이동합니다
+  const { setLocale } = useLocale({
+    onLocaleChange: (newLocale) => {
+      window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
+    },
+  });
 
   const localeLinks = document.querySelectorAll("[data-locale]");
 
   localeLinks.forEach((link) => {
-    link.addEventListener("click", (e) => {
+    link.addEventListener("click", (event) => {
       const locale = link.getAttribute("data-locale") as LocalesValues;
 
-      // Update the locale cookie
-      setLocaleInStorageClient(locale);
+      event.preventDefault();
+      setLocale(locale);
     });
   });
 </script>
@@ -372,6 +386,13 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
     display: flex;
     gap: 1rem;
   }
+  ul {
+    display: flex;
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    gap: 0.5rem;
+  }
   a[aria-current="page"] {
     font-weight: bold;
     text-decoration: underline;
@@ -379,8 +400,11 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 </style>
 ```
 
-> **지속성에 대한 참고 사항:**
-> 클라이언트 측 스크립트에서 `setLocaleInStorageClient`를 사용하면 사용자의 언어 선호도가 쿠키에 저장됩니다. 이를 통해 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`는 클라이언트 엔트리를 명시적으로 노출합니다.
 
 </Step>
 <Step number={8} title="Sitemap 및 Robots.txt">
@@ -404,10 +428,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" },
@@ -454,7 +478,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}>
@@ -524,21 +547,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-20
 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 패키지입니다.
@@ -257,19 +260,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 +283,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 +346,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 +504,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 +611,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-20
 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의 빠르고 가벼운 대안입니다.
@@ -253,19 +256,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 +280,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 +340,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 +458,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 +565,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
@@ -736,6 +732,13 @@ Astro 페이지가 이를 prop으로 전달하고 아일랜드의 Intlayer 프
 
 자체 인프라에서 실행되어 실행 중인 앱에서 직접 텍스트를 수정할 수 있는 [비주얼 에디터](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)를 통해 가능합니다.
 
+</Question>
+<Question title="비주얼 에디터의 비용은 얼마인가요? 필요하지 않은 경우 과도한가요?">
+
+Intlayer [비주얼 에디터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)는 설정되지 않은 경우 애플리케이션에 **비용이 전혀 들지 않습니다**. 추가 로직은 명시적으로 활성화되고 필요할 때만 로드됩니다.
+
+활성화하더라도 대부분의 로직은 [app.intlayer.org](https://app.intlayer.org)의 서버 에디터나 `intlayer-editor` 패키지를 통해 처리되므로 영향은 극히 미미합니다(활성화 시 동적으로 로드되는 +5 kB에 불과함). 비주얼 편집 없이 간단한 번역 솔루션만 필요한 경우 Intlayer는 앱에 어떠한 오버헤드도 추가하지 않습니다.
+
 </Question>
 <Question title="Intlayer는 무료이며 오픈 소스인가요?">