@intlayer/docs 9.3.3 → 9.4.0

package/docs/ko/packages/intlayer/getDictionary.md

@@ -0,0 +1,155 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getDictionary 함수 문서 | intlayer
+description: intlayer 패키지의 getDictionary 함수를 사용하는 방법을 참조하세요
+keywords:
+  - getDictionary
+  - dictionary
+  - interpreter
+  - content
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionary
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "초기 문서"
+author: aymericzip
+---
+
+# `intlayer`의 `getDictionary` 함수 문서
+
+## 설명
+
+`getDictionary` 함수는 **직접 전달한 dictionary 객체**를 해석하고 주어진 로케일에 대해 해결된 콘텐츠를 반환합니다. 콘텐츠를 한 번에 순회하면서 필요에 따라 각 interpreter 플러그인을 적용하여 `t()` 번역, 열거형, 조건, 삽입, 중첩, markdown, HTML 및 파일 노드를 해결합니다.
+
+생성된 레지스트리에서 키로 dictionary를 조회하는 [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayer.md)와 달리, `getDictionary`는 dictionary 자체를 받습니다. 이것이 런타임에 구축된 콘텐츠, API 또는 CMS에서 가져온 콘텐츠 또는 테스트에서 인라인으로 선언된 콘텐츠에 적합한 도구입니다.
+
+**주요 기능:**
+
+- dictionary 구조(`{ key, content }`)를 따르는 모든 객체와 함께 작동
+- 선택자와 함께 정규화된 dictionary 그룹(컬렉션, 변형)도 수락
+- 완전히 타입됨: 반환된 객체는 전달한 `content`를 미러링
+- 사용자 정의 interpreter 플러그인 수락
+
+---
+
+## 함수 서명
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // 필수
+  localeOrSelector?: LocalesValues | DictionarySelector, // 선택사항
+  plugins?: Plugins[]                                // 선택사항
+): DeepTransformContent<...>
+```
+
+---
+
+## 매개변수
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **설명**: 해석할 dictionary (또는 qualified dictionary group).
+  - **타입**: `Dictionary | QualifiedDictionaryGroup`
+  - **필수**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **설명**: 콘텐츠를 해석할 locale, 또는 selector 객체 (`{ item }`, `{ variant }`, 선택적으로 `locale` 포함). [동적 dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)를 참조하세요.
+  - **타입**: `LocalesValues | DictionarySelector`
+  - **필수**: No (선택사항) — 설정된 `defaultLocale`로 기본값 설정.
+
+- `plugins: Plugins[]`
+  - **설명**: 인식된 노드가 어떻게 해석되는지를 정의하는 node transformer 배열. 생략되면 기본 interpreter plugin 세트가 사용됩니다.
+  - **타입**: `Plugins[]`
+  - **필수**: No (선택사항)
+
+### Returns
+
+- **Type**: 해석된 딕셔너리의 콘텐츠.
+- **Description**: 전달한 `content`에서 요청된 로케일에 대해 모든 Intlayer 노드가 해석됩니다. `item` 선택자가 없는 컬렉션 그룹의 경우 해석된 항목의 정렬된 배열이 반환되며, 선택자가 아무것도 대상으로 하지 않으면 `null`이 반환됩니다.
+
+---
+
+## 예제 사용법
+
+### 기본 사용법
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        ko: "안녕하세요",
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "fr"
+);
+
+console.log(content.greeting); // "Bonjour"
+```
+
+### 런타임에 가져온 콘텐츠 해석
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### 선택자 사용
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// 한정된 dictionary group은 단일 entry로 해결됩니다…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …또는 `item`이 주어지지 않으면 정렬된 배열로 해결됩니다
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## 관련 함수
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayer.md): 동일한 해석이지만, 생성된 registry에서 key로 dictionary를 조회합니다.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getDictionaryAsync.md): locale별 loader maps의 대응 함수입니다.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useDictionary.md): React hook 동등물로, provider에서 locale을 읽습니다.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionary<
+  const T extends Dictionary | QualifiedDictionaryGroup,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionary: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  ResolveQualifiedDictionaryContent<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

package/docs/ko/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getDictionaryAsync 함수 문서 | intlayer
+description: intlayer 패키지의 getDictionaryAsync 함수 사용 방법 알아보기
+keywords:
+  - getDictionaryAsync
+  - dictionary
+  - dynamic dictionaries
+  - loader map
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionaryAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentation: `getDictionaryAsync` Function in `intlayer`
+
+## 설명
+
+`getDictionaryAsync` 함수는 딕셔너리의 **단일 로케일 청크**를 로드하고 해석된 콘텐츠를 반환합니다.
+
+이는 `.intlayer/dynamic_dictionaries/`에서 내보낸 로케일별 로더 맵에 대한 [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getDictionary.md)의 대응물입니다: 모든 로케일을 포함하는 딕셔너리를 받는 대신, 로더 맵을 받고 요청된 로케일이 필요로 하는 청크만 기다립니다.
+
+> 애플리케이션 코드에서는 일반적으로 이 함수가 아닌 [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayerAsync.md)를 호출합니다. [빌드 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md)은 모든 `getIntlayerAsync('key', locale)` 호출을 `getDictionaryAsync(loaderMap, 'key', locale)` 호출로 다시 쓰습니다. `getDictionaryAsync`는 커스텀 로더와 자체 로더 맵을 빌드하는 도구를 위해 내보내집니다.
+
+**주요 기능:**
+
+- 요청된 로케일 청크만 로드합니다
+- 일반 (`locale → loader`) 및 한정된 (`locale → qualifierId → loader`) 로더 맵을 지원합니다
+- 동일한 청크의 동시 로드를 중복 제거하고 해석된 콘텐츠를 캐시합니다
+- 실패한 로드는 캐시에서 제거되므로 이후 호출이 청크를 재시도합니다
+
+---
+
+## 함수 시그니처
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // 필수
+  key: string,                                           // 필수
+  localeOrSelector?: LocalesValues | DictionarySelector, // 선택사항
+  plugins?: Plugins[]                                    // 선택사항
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## 매개변수
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **설명**: 로케일별 로더 맵입니다. 일반 맵은 로케일을 로더와 연결하고, 정규화된 맵(컬렉션 및 변형에서 사용됨)은 로케일을 정규화 id와 연결한 후 로더와 연결합니다. 정규화된 맵의 경우, 선택자가 대상으로 하는 청크만 로드됩니다.
+  - **타입**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **필수**: Yes
+
+- `key: string`
+  - **설명**: 청크 캐시의 네임스페이스에 사용되는 딕셔너리 키입니다.
+  - **타입**: `string`
+  - **필수**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **설명**: 콘텐츠를 해석할 로케일이거나, 선택자 객체(`{ item }`, `{ variant }`, 선택적으로 `locale` 포함)입니다. [동적 딕셔너리](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)를 참조하세요.
+  - **타입**: `LocalesValues | DictionarySelector`
+  - **필수**: No (선택사항) — 구성된 `defaultLocale`로 기본 설정됩니다.
+
+- `plugins: Plugins[]`
+  - **설명**: Node 변환기입니다. 기본 인터프리터 세트로 기본 설정됩니다.
+  - **타입**: `Plugins[]`
+  - **필수**: No (선택사항)
+
+### Returns
+
+- **Type**: `Promise<Content>` — loaded chunk의 interpreted content로 resolve되는 promise입니다.
+- **Description**: 요청된 locale에 대해 map이 chunk를 emit하지 않고 그 fallback 중 어느 것도 emit하지 않을 때 `null`로 resolve됩니다. 이는 missing qualified coordinate가 resolve되는 방식을 반영합니다.
+
+---
+
+## 사용 예시
+
+### 생성된 로더 맵 사용
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### 사용자 정의 로더 맵으로
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const loaderMap = {
+  en: () => import("./banner.en.json").then((mod) => mod.default),
+  fr: () => import("./banner.fr.json").then((mod) => mod.default),
+};
+
+const banner = await getDictionaryAsync(loaderMap, "banner", "fr");
+```
+
+### 정규화된 맵에서 선택자 사용
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## 동작 주의사항
+
+### 캐싱 및 중복 제거
+
+캐시는 각 `key + locale + selector` 조합의 **promise**를 저장하므로, 동일한 청크에 대한 동시 호출은 단일 로드를 기다립니다. 거부된 로드는 캐시에서 제거되므로, 실패한 청크는 동일한 실패를 계속 반복하는 대신 다음 호출 시 재시도됩니다.
+
+### 로캘 폴백
+
+일반 로더 맵은 동기 모드와 동일한 폴백 체인을 따라 탐색됩니다: 먼저 요청된 로캘, 그 다음 폴백, 마지막으로 어떤 청크도 방출되지 않은 경우 `null`입니다.
+
+---
+
+## 관련 함수
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayerAsync.md): 애플리케이션이 호출하는 함수이며, 빌드 플러그인이 이를 `getDictionaryAsync`로 다시 작성합니다.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getDictionary.md): 전체 사전을 받는 동기 대응 함수입니다.
+- [동적 사전](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md): 컬렉션과 변형, 그리고 이들이 생성하는 로더 맵입니다.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionaryAsync<
+  const T extends Dictionary,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionaryLoaders: PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap,
+  key: string,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    T["content"],
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

package/docs/ko/packages/intlayer/getEnumeration.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 `getEnumeration` 함수는 열거형 객체에 미리 정의된 조건에 따라 특정 수량에 해당하는 콘텐츠를 가져옵니다. 조건은 키로 정의되며, 우선순위는 객체 내 키의 순서에 의해 결정됩니다.
 
+열거형 선언 방법에 대한 자세한 내용은 [Enumeration 설명서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/enumeration.md)를 참조하세요.
+
 ## 매개변수
 
 - `enumerationContent: QuantityContent<Content>`

package/docs/ko/packages/intlayer/getIntlayer.md

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getIntlayer 함수 문서 | intlayer
+description: intlayer 패키지를 위한 getIntlayer 함수 사용 방법을 알아봅니다
+keywords:
+  - getIntlayer
+  - dictionary
+  - content
+  - selector
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentation: `intlayer`의 `getIntlayer` Function
+
+## Description
+
+`getIntlayer` 함수는 키로 하나의 딕셔너리를 선택하고 주어진 로케일에 대해 해석된 내용을 반환합니다. 이는 `useIntlayer` 훅의 프레임워크에 독립적인 대응물입니다: 동일한 내용, 동일한 선택자이지만 React 컨텍스트를 사용할 수 없는 곳(Node 스크립트, 서버 함수, 라우트 로더, 메타데이터 빌더, Express/Fastify 핸들러, 테스트)에서 사용 가능합니다.
+
+`.intlayer/`에서 Intlayer가 생성한 딕셔너리를 읽으므로, `key` 인자는 타입이 지정되고 자신의 콘텐츠 선언에서 자동 완성되며, 반환된 객체는 각 리프까지 완전히 타입이 지정됩니다.
+
+**주요 기능:**
+
+- 타입이 지정된 딕셔너리 키와 타입이 지정된 반환 콘텐츠
+- 모든 콘텐츠 노드 해석(`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- 로케일 또는 선택자 객체(컬렉션, 변형) 수용
+- 결과는 `key + locale + selector`당 메모이제이션됨
+- 개발 중 딕셔너리가 누락된 경우 충돌하는 대신 안전한 프록시로 폴백
+
+---
+
+## 함수 시그니처
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // 필수
+  localeOrSelector?: LocalesValues | DictionarySelector, // 선택사항
+  plugins?: Plugins[]                         // 선택사항
+): DeepTransformContent<...>
+```
+
+---
+
+## Parameters
+
+- `key: DictionaryKeys`
+  - **Description**: 콘텐츠 파일에 선언된 대로 읽을 사전의 키입니다.
+  - **Type**: `DictionaryKeys` — 선언된 모든 사전 키의 합집합입니다.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: 콘텐츠를 해석할 locale이거나, [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)용 selector 객체입니다.
+    - `'fr'` — a locale
+    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
+    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md) (omit for the `default` one)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — a structured variant
+    - Any selector can carry a locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — 설정된 `defaultLocale`으로 기본 설정됩니다.
+
+- `plugins: Plugins[]`
+  - **Description**: 기본 interpreter plugins를 대체하는 커스텀 node transformers입니다. 고급 사용법이므로, 기본 동작을 유지하려면 생략하세요.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: 선언된 타입으로 입력된 사전의 해석된 콘텐츠.
+- **Description**: 사전의 `content` 필드를 반영하는 일반 객체로, 모든 Intlayer 노드가 요청된 로케일에 대한 최종 값으로 해석됩니다.
+
+---
+
+## 사용 예시
+
+### 기본 사용법
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      ko: "안녕하세요",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### 로케일 없이
+
+로케일을 생략하면 [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)에서 선언된 `defaultLocale`로 콘텐츠를 해석합니다.
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // 기본 로케일로 해석됨
+```
+
+### 서버 핸들러 내부
+
+```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
+import { getIntlayer, getLocale } from "intlayer";
+
+export const greetingHandler = async (request: Request) => {
+  const locale = await getLocale({
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+  });
+
+  const { title } = getIntlayer("app", locale);
+
+  return Response.json({ title });
+};
+```
+
+### 선택자가 있는 경우 (컬렉션 및 변형)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// 단일 컬렉션 항목
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// 컬렉션의 모든 항목, 정렬된 배열로
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// 명명된 변형
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## 동작 참고 사항
+
+### Caching
+
+결과는 `key + locale + selector`를 키로 하는 모듈 레벨 캐시에 메모이제이션됩니다. `getIntlayer("app", "fr")`을 반복적으로 호출해도 dictionary는 한 번만 해석되고 그 이후로는 동일한 객체를 반환합니다.
+
+### 누락된 사전
+
+개발 중에 생성된 사전이 없는 키를 요청하면 경고가 한 번 기록되고 안전한 폴백 프록시가 반환됩니다. `content.title`을 읽으면 오류를 던지는 대신 `"app.title"` 문자열이 반환됩니다. 이를 통해 누락된 선언이 수정될 때까지 페이지를 사용할 수 있게 유지됩니다. Intlayer 빌드(또는 dev 서버)를 실행하여 사전이 생성되도록 하세요.
+
+### Bundle size
+
+`getIntlayer`는 **모든** locale을 포함하는 병합된 사전을 읽습니다. 클라이언트 번들에서 [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md)는 필요한 콘텐츠만 배송되도록 호출을 다시 작성합니다. 렌더링 외부에서 콘텐츠를 읽을 때(metadata, loaders, server functions) 단일 locale을 요청 시 로드하려면 [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayerAsync.md)를 대신 사용하세요.
+
+---
+
+## 관련 함수
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayerAsync.md): 단일 locale 청크를 로드하는 비동기 counterpart입니다.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getDictionary.md): 키로 조회되는 대신 직접 전달하는 dictionary 객체를 해석합니다.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useIntlayer.md): provider에서 locale을 읽는 React hook의 동등물입니다.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayer<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  DictionaryRegistryResult<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

package/docs/ko/packages/intlayer/getIntlayerAsync.md

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getIntlayerAsync Function Documentation | intlayer
+description: intlayer package의 getIntlayerAsync 함수를 사용하는 방법을 알아보세요
+keywords:
+  - getIntlayerAsync
+  - dictionary
+  - dynamic import
+  - metadata
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayerAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "초기 문서화"
+author: aymericzip
+---
+
+# Documentation: `intlayer`의 `getIntlayerAsync` 함수
+
+## Description
+
+`getIntlayerAsync` 함수는 키로 하나의 딕셔너리를 선택하고 주어진 로캘에 대한 콘텐츠를 해결하며, **해당 로캘만 로드합니다**.
+
+이는 [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayer.md)의 비동기 대응 함수로, 렌더링 외부에서 딕셔너리가 읽히는 곳 — 라우트 `head` / 메타데이터 빌더, 로더, 서버 함수를 위해 고안되었습니다.
+
+`getIntlayer`가 모든 로캘을 포함하는 병합된 딕셔너리를 가져오는 반면, [빌드 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`)은 이 호출을 `getDictionaryAsync(loaderMap, key, locale)`로 다시 쓰고, `.intlayer/dynamic_dictionaries/`의 로캘별 청크를 가리킵니다. 따라서 번들은 실제로 요청된 로캘만 포함합니다.
+
+이러한 플러그인 없이 — 최적화되지 않은 빌드 — 호출은 동기 딕셔너리 레지스트리를 통해 대신 해결됩니다: 로캘별 분할 없이 동일한 콘텐츠입니다.
+
+**주요 기능:**
+
+- `getIntlayer`와 동일한 타입 지정 키, 선택자 및 반환된 콘텐츠
+- 최적화된 빌드에서 요청된 로캘 청크만 로드
+- 동일한 청크에 대한 동시 호출은 단일 로드를 공유합니다
+- `async` 메타데이터 빌더, 로더 및 서버 함수에서 안전하게 사용 가능
+
+---
+
+## 함수 서명
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // 필수
+  localeOrSelector?: LocalesValues | DictionarySelector, // 선택사항
+  plugins?: Plugins[]                         // 선택사항
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## 매개변수
+
+- `key: DictionaryKeys`
+  - **Description**: 콘텐츠 파일에 선언된 대로 읽을 사전의 키입니다.
+  - **Type**: `DictionaryKeys` — 선언된 모든 사전 키의 합집합입니다.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: 콘텐츠를 해석할 로케일 또는 [동적 사전](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)에 대한 선택자 객체입니다.
+    - `'fr'` — 로케일
+    - `{ item: 2 }` — [컬렉션](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/collections.md) 항목 (`item`을 생략하면 배열로 모든 항목을 얻습니다)
+    - `{ variant: 'black-friday' }` — 명명된 [변형](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md) (`default`를 원할 경우 생략)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — 구조화된 변형
+    - 모든 선택자는 로케일을 포함할 수 있습니다: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — 기본값은 구성된 `defaultLocale`입니다.
+
+- `plugins: Plugins[]`
+  - **Description**: 기본 인터프리터 플러그인을 대체하는 커스텀 노드 변환기입니다. 고급 사용만 해당합니다.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: `Promise<Content>` — 선언에서 입력한 타입으로 지정된 dictionary의 해석된 내용으로 resolve되는 promise입니다.
+
+---
+
+## 사용 예시
+
+### 기본 사용법
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayerAsync } from "intlayer";
+
+const { title } = await getIntlayerAsync("app", "fr"); // "Bonjour"
+```
+
+---
+
+## `getIntlayer` vs `getIntlayerAsync`
+
+|                    | [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Returns            | 컨텐츠                                                                                                          | 컨텐츠의 Promise                                  |
+| Dictionary loaded  | 병합된 사전 (모든 로케일)                                                                                       | 요청된 로케일의 청크만                            |
+| Best suited for    | 렌더링, 동기 코드 경로                                                                                          | 메타데이터, 로더, 서버 함수                       |
+| Requires a plugin? | No                                                                                                              | No — per-locale 분할은 빌드 플러그인이 필요합니다 |
+
+둘 다 동일한 인수를 수용하고 동일한 컨텐츠를 반환합니다: 둘 중 하나에서 다른 하나로 전환하면 **언제**와 **얼마나 많은**이 로드되는지만 변경됩니다.
+
+---
+
+## 관련 함수
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getIntlayer.md): 병합된 딕셔너리를 읽는 동기 동등물.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getDictionaryAsync.md): 빌드 플러그인이 이 호출을 다시 작성하는 하위 수준 함수.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getLocale.md): 들어오는 요청의 로케일을 감지합니다.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayerAsync<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    DictionaryRegistryResult<T, A>,
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

package/docs/ko/packages/intlayer/getLocaleLang.md

@@ -59,7 +59,5 @@ getLocaleLang(Locales.FRENCH); // 출력: "fr"
 
 - **로케일이 제공되지 않은 경우:**
 
-- `locale`가 `undefined`일 때 함수는 빈 문자열을 반환합니다.
-
 - **잘못된 형식의 로케일 문자열:**
   - `locale`이 `language-country` 형식을 따르지 않는 경우(예: `Locales.ENGLISH-US`), 함수는 `'-'` 이전 부분을 안전하게 반환하거나 `'-'`가 없으면 전체 문자열을 반환합니다.