@intlayer/docs 9.4.0-canary.0 → 9.4.0

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

@@ -0,0 +1,155 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Tài liệu hàm getDictionary | intlayer
+description: Xem cách sử dụng hàm getDictionary cho package intlayer
+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: "Initial documentation"
+author: aymericzip
+---
+
+# Tài liệu: Hàm `getDictionary` trong `intlayer`
+
+## Mô tả
+
+Hàm `getDictionary` giải thích một dictionary **object mà bạn tự truyền vào** và trả về nội dung đã được giải quyết cho một locale nhất định. Nó duyệt qua nội dung trong một lần duy nhất và áp dụng từng plugin interpreter khi cần thiết, giải quyết các bản dịch `t()`, enumerations, conditions, insertions, nesting, markdown, HTML và file nodes.
+
+Không giống như [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayer.md), cái mà tìm kiếm một dictionary theo key trong registry được tạo, `getDictionary` nhận chính dictionary đó. Điều đó làm cho nó trở thành công cụ phù hợp cho nội dung được xây dựng tại runtime, được lấy từ một API hoặc CMS, hoặc được khai báo inline trong một test.
+
+**Các tính năng chính:**
+
+- Hoạt động với bất kỳ object nào tuân theo cấu trúc dictionary (`{ key, content }`)
+- Cũng chấp nhận một qualified dictionary group (collections, variants) cùng với một selector
+- Hoàn toàn có kiểu: object được trả về phản ánh `content` mà bạn đã truyền vào
+- Chấp nhận các custom interpreter plugins
+
+---
+
+## Function Signature
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Bắt buộc
+  localeOrSelector?: LocalesValues | DictionarySelector, // Tùy chọn
+  plugins?: Plugins[]                                // Tùy chọn
+): DeepTransformContent<...>
+```
+
+---
+
+## Tham số
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Description**: Từ điển (hoặc nhóm từ điển đủ điều kiện) để diễn giải.
+  - **Type**: `Dictionary | QualifiedDictionaryGroup`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Locale để diễn giải nội dung, hoặc một object selector (`{ item }`, `{ variant }`, tùy chọn với `locale`). Xem [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — mặc định là `defaultLocale` đã cấu hình.
+
+- `plugins: Plugins[]`
+  - **Description**: Một mảng các node transformers xác định cách các node được nhận dạng được diễn giải. Nếu bỏ qua, bộ plugin interpreter mặc định sẽ được sử dụng.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Kết quả trả về
+
+- **Loại**: Nội dung đã được diễn giải của từ điển.
+- **Mô tả**: `content` bạn đã truyền, với mọi nút Intlayer được phân giải cho ngôn ngữ được yêu cầu. Đối với một nhóm bộ sưu tập mà không có bộ chọn `item`, một mảng các mục đã được diễn giải theo thứ tự được trả về; `null` được trả về khi bộ chọn không nhắm đến gì.
+
+---
+
+## Ví dụ Sử dụng
+
+### Sử dụng Cơ Bản
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        vi: "Xin chào",
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "vi"
+);
+
+console.log(content.greeting); // "Xin chào"
+```
+
+### Diễn giải nội dung được tìm nạp tại thời gian chạy
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### Với một selector
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// Một qualified dictionary group được resolve thành một single entry…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …hoặc thành một ordered array khi không có `item` được cung cấp
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Các Hàm Liên Quan
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayer.md): Cách diễn giải tương tự, nhưng từ điển được tìm kiếm theo khóa trong registry được tạo ra.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getDictionaryAsync.md): Đối tác cho các bản đồ loader theo từng ngôn ngữ.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/react-intlayer/useDictionary.md): Hook React tương đương, đọc ngôn ngữ từ provider.
+
+---
+
+## 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/vi/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Tài liệu Hàm getDictionaryAsync | intlayer
+description: Xem cách sử dụng hàm getDictionaryAsync cho package intlayer
+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: "Tài liệu ban đầu"
+author: aymericzip
+---
+
+# Documentation: Hàm `getDictionaryAsync` trong `intlayer`
+
+## Mô tả
+
+Hàm `getDictionaryAsync` tải một **single locale chunk** của một từ điển và trả về nội dung được giải thích của nó.
+
+Đây là phần đối ứng của [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getDictionary.md) cho các loader maps theo locale được phát ra trong `.intlayer/dynamic_dictionaries/`: thay vì nhận một từ điển chứa mọi locale, nó nhận loader map và chỉ chờ đợi chunk mà locale được yêu cầu cần.
+
+> Trong mã ứng dụng, bạn thường gọi [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayerAsync.md), không phải hàm này. Các [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/bundle_optimization.md) viết lại mọi lệnh gọi `getIntlayerAsync('key', locale)` thành `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` được export cho các custom loaders và cho các công cụ xây dựng loader maps của riêng chúng.
+
+**Các tính năng chính:**
+
+- Tải chỉ locale chunk được yêu cầu
+- Hỗ trợ loader maps đơn giản (`locale → loader`) và có đủ điều kiện (`locale → qualifierId → loader`)
+- Khử trùng các lần tải đồng thời của cùng một chunk và cache nội dung đã giải quyết
+- Các tải thất bại được xóa khỏi cache để một lệnh gọi sau có thể thử lại chunk
+
+---
+
+## Chữ Ký Hàm
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Bắt buộc
+  key: string,                                           // Bắt buộc
+  localeOrSelector?: LocalesValues | DictionarySelector, // Tùy chọn
+  plugins?: Plugins[]                                    // Tùy chọn
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Tham số
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: Bản đồ loader cho từng locale. Bản đồ thông thường liên kết một locale với một loader; bản đồ được xác định (được sử dụng bởi collections và variants) liên kết một locale với một qualifier id, sau đó là một loader. Đối với bản đồ được xác định, chỉ các chunk mà selector nhắm tới được tải.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: Khóa từ điển, được sử dụng để đặt tên không gian cho bộ nhớ đệm chunk.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Locale để diễn giải nội dung với, hoặc một đối tượng selector (`{ item }`, `{ variant }`, tùy chọn với `locale`). Xem [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — mặc định là `defaultLocale` đã cấu hình.
+
+- `plugins: Plugins[]`
+  - **Description**: Node transformers. Mặc định là bộ interpreter cơ sở.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: `Promise<Content>` — a promise resolving to the interpreted content of the loaded chunk.
+- **Description**: Resolves to `null` when the map emits no chunk for the requested locale nor for any of its fallbacks, mirroring how a missing qualified coordinate resolves.
+
+---
+
+## Ví dụ sử dụng
+
+### Với một generated loader map
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### Với một custom loader map
+
+```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");
+```
+
+### Với một selector trên một qualified map
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Các Ghi Chú về Hành Vi
+
+### Caching và deduplication
+
+Bộ nhớ cache lưu trữ **promise** của mỗi bộ ba `key + locale + selector`, vì vậy các lệnh gọi đồng thời cho cùng một chunk chờ một lần tải duy nhất. Một lần tải bị từ chối sẽ bị loại khỏi bộ nhớ cache, vì vậy một chunk lỗi sẽ được thử lại trong lần gọi tiếp theo thay vì phát lại cùng một lỗi mãi mãi.
+
+### Dự phòng Locale
+
+Một plain loader map được duyệt dọc theo cùng một chuỗi dự phòng như ở chế độ đồng bộ: locale được yêu cầu trước tiên, sau đó là các dự phòng của nó, sau đó là `null` nếu không có chunk nào được phát ra.
+
+---
+
+## Các Hàm Liên Quan
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayerAsync.md): Hàm mà các ứng dụng gọi; build plugins viết lại nó thành `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getDictionary.md): Đối tác đồng bộ lấy một từ điển đầy đủ.
+- [Dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md): Các bộ sưu tập và biến thể, cũng như các bản đồ loader mà chúng tạo ra.
+
+---
+
+## 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/vi/packages/intlayer/getEnumeration.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 Hàm `getEnumeration` lấy nội dung tương ứng với một số lượng cụ thể dựa trên các điều kiện đã được định nghĩa trước trong một đối tượng liệt kê. Các điều kiện được định nghĩa dưới dạng các khóa, và thứ tự ưu tiên của chúng được xác định theo thứ tự trong đối tượng.
 
+Để biết thêm chi tiết về cách khai báo enumerations, xem [tài liệu Enumeration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dictionary/enumeration.md).
+
 ## Tham số
 
 - `enumerationContent: QuantityContent<Content>`

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

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Tài liệu Hàm getIntlayer | intlayer
+description: Xem cách sử dụng hàm getIntlayer cho gói intlayer
+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
+---
+
+# Tài liệu: Hàm `getIntlayer` trong `intlayer`
+
+## Mô tả
+
+Hàm `getIntlayer` chọn một từ điển theo khóa của nó và trả về nội dung được diễn giải cho một locale nhất định. Đây là phiên bản độc lập với framework tương ứng với hook `useIntlayer`: cùng nội dung, cùng selectors, nhưng có thể sử dụng ở bất kỳ đâu mà React context không khả dụng — các script Node, server functions, route loaders, metadata builders, Express/Fastify handlers, tests.
+
+Nó đọc các từ điển được tạo bởi Intlayer trong `.intlayer/`, vì vậy argument `key` được gõ và tự động hoàn thành từ các khai báo nội dung của bạn, và đối tượng được trả về được gõ đầy đủ đến từng leaf.
+
+**Các tính năng chính:**
+
+- Các khóa từ điển được gõ và nội dung được trả về được gõ
+- Diễn giải mọi nút nội dung (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Chấp nhận một locale hoặc một đối tượng selector (collections, variants)
+- Kết quả được ghi nhớ mỗi `key + locale + selector`
+- Quay lại một proxy an toàn trong quá trình phát triển khi một từ điển bị thiếu, thay vì gặp lỗi
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Bắt buộc
+  localeOrSelector?: LocalesValues | DictionarySelector, // Tùy chọn
+  plugins?: Plugins[]                         // Tùy chọn
+): DeepTransformContent<...>
+```
+
+---
+
+## Tham số
+
+- `key: DictionaryKeys`
+  - **Description**: Khóa của từ điển cần đọc, được khai báo trong các tệp nội dung của bạn.
+  - **Type**: `DictionaryKeys` — một union của mọi khóa từ điển được khai báo.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Locale để diễn giải nội dung với, hoặc một object selector cho [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md).
+    - `'fr'` — một locale
+    - `{ item: 2 }` — một mục [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/collections.md) (bỏ qua `item` để lấy mọi mục dưới dạng mảng)
+    - `{ variant: 'black-friday' }` — một [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/variants.md) được đặt tên (bỏ qua để lấy variant `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — một variant có cấu trúc
+    - Bất kỳ selector nào cũng có thể mang theo một locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — mặc định là `defaultLocale` được cấu hình.
+
+- `plugins: Plugins[]`
+  - **Description**: Các node transformers tùy chỉnh thay thế các plugins interpreter cơ bản. Chỉ dùng cho các trường hợp nâng cao; bỏ qua để giữ hành vi mặc định.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: Nội dung được diễn giải của từ điển, được gõ từ khai báo của bạn.
+- **Description**: Một plain object phản ánh trường `content` của từ điển của bạn, trong đó mỗi nút Intlayer đã được giải quyết thành giá trị cuối cùng cho ngôn ngữ được yêu cầu.
+
+---
+
+## Ví dụ sử dụng
+
+### Cách Sử Dụng Cơ Bản
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      vi: "Xin chào",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "fr"); // "Bonjour"
+```
+
+### Không có locale
+
+Bỏ qua locale sẽ diễn giải nội dung với `defaultLocale` được khai báo trong [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md) của bạn.
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Diễn giải với locale mặc định
+```
+
+### Bên trong một server handler
+
+```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 });
+};
+```
+
+### With a selector (collections and variants)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// Một item của collection
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Mọi item của collection, dưới dạng một mảng có thứ tự
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// Một variant được đặt tên
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Ghi chú về Hành vi
+
+### Caching
+
+Kết quả được memoized trong một module-level cache được khóa bằng `key + locale + selector`. Gọi `getIntlayer("app", "fr")` nhiều lần sẽ chỉ diễn dịch dictionary một lần và trả về cùng một object sau đó.
+
+### Từ điển bị thiếu
+
+Trong quá trình phát triển, yêu cầu một khóa không có từ điển được tạo sẽ ghi lại một cảnh báo một lần và trả về một proxy dự phòng an toàn: đọc `content.title` sẽ trả về chuỗi `"app.title"` thay vì ném lỗi. Điều này giữ cho trang có thể sử dụng được trong khi khai báo bị thiếu được sửa chữa. Chạy bản dựng Intlayer (hoặc máy chủ dev) để từ điển được tạo.
+
+### Kích thước Bundle
+
+`getIntlayer` đọc từ từ điển hợp nhất, chứa **mọi** locale. Trong client bundles, các [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/bundle_optimization.md) viết lại cuộc gọi để chỉ nội dung cần thiết được gửi đi. Khi bạn đọc nội dung bên ngoài rendering (metadata, loaders, server functions) và muốn một locale duy nhất được tải theo yêu cầu, hãy sử dụng [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayerAsync.md) thay thế.
+
+---
+
+## Các Hàm Liên Quan
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayerAsync.md): Phiên bản async tải một chunk locale duy nhất.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getDictionary.md): Diễn giải một đối tượng dictionary mà bạn truyền vào, thay vì tìm kiếm theo khóa.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/react-intlayer/useIntlayer.md): Hook React tương đương, đọc locale từ provider.
+
+---
+
+## 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/vi/packages/intlayer/getIntlayerAsync.md

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: getIntlayerAsync Function Documentation | intlayer
+description: See how to use the getIntlayerAsync function for intlayer package
+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: "Initial documentation"
+author: aymericzip
+---
+
+# Tài liệu: Hàm `getIntlayerAsync` trong `intlayer`
+
+## Mô tả
+
+Hàm `getIntlayerAsync` chọn một từ điển theo khóa của nó và giải quyết nội dung của nó cho một locale nhất định, **chỉ tải locale đó**.
+
+Nó là phiên bản không đồng bộ của [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayer.md), được sử dụng cho các trường hợp từ điển được đọc bên ngoài quá trình render — route `head` / metadata builders, loaders, server functions.
+
+Nếu như `getIntlayer` kéo trong từ điển đã hợp nhất chứa mọi locale, các [build plugins](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) sẽ viết lại cuộc gọi này thành `getDictionaryAsync(loaderMap, key, locale)`, chỉ vào các chunks theo locale trong `.intlayer/dynamic_dictionaries/`. Bundle do đó chỉ bao giờ cũng mang lại locale thực sự được yêu cầu.
+
+Nếu không có các plugins này — một build chưa được tối ưu hóa — cuộc gọi sẽ được giải quyết thông qua registry từ điển đồng bộ thay thế: cùng nội dung, nhưng không có sự phân chia theo locale.
+
+**Các tính năng chính:**
+
+- Các khóa, selector và nội dung được trả về giống như `getIntlayer`
+- Chỉ tải chunk locale được yêu cầu trong các build được tối ưu hóa
+- Các cuộc gọi đồng thời cho cùng một chunk chia sẻ một lần tải
+- An toàn để sử dụng trong `async` metadata builders, loaders và server functions
+
+---
+
+## Function Signature
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Bắt buộc
+  localeOrSelector?: LocalesValues | DictionarySelector, // Tùy chọn
+  plugins?: Plugins[]                         // Tùy chọn
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Tham số
+
+- `key: DictionaryKeys`
+  - **Description**: Khóa của từ điển cần đọc, như được khai báo trong các tệp nội dung của bạn.
+  - **Type**: `DictionaryKeys` — một union của mọi khóa từ điển được khai báo.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: Locale để giải thích nội dung với, hoặc một đối tượng selector cho [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md).
+    - `'fr'` — một locale
+    - `{ item: 2 }` — một mục [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/collections.md) (bỏ qua `item` để lấy mọi mục dưới dạng mảng)
+    - `{ variant: 'black-friday' }` — một [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/variants.md) có tên (bỏ qua để lấy `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — một variant có cấu trúc
+    - Bất kỳ selector nào cũng có thể mang theo một locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — mặc định là `defaultLocale` được cấu hình.
+
+- `plugins: Plugins[]`
+  - **Description**: Các node transformers tùy chỉnh thay thế các plugin interpreter cơ bản. Chỉ sử dụng nâng cao.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Returns
+
+- **Type**: `Promise<Content>` — a promise resolving to the interpreted content of the dictionary, typed from your declaration.
+
+---
+
+## Ví dụ Sử dụng
+
+### Cách sử dụng cơ bản
+
+```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/vi/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                          |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| Returns            | Nội dung                                                                                                        | Một promise của nội dung                    |
+| Dictionary loaded  | Từ điển được hợp nhất (tất cả các locale)                                                                       | Chunk của locale được yêu cầu duy nhất      |
+| Best suited for    | Rendering, các đường mã đồng bộ                                                                                 | Metadata, loaders, server functions         |
+| Requires a plugin? | No                                                                                                              | No — per-locale split cần các build plugins |
+
+Cả hai chấp nhận các đối số giống nhau và trả về nội dung giống nhau: chuyển đổi từ cái này sang cái khác chỉ thay đổi **khi** và **bao nhiêu** được tải.
+
+---
+
+## Các Hàm Liên Quan
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getIntlayer.md): Tương đương đồng bộ đọc từ điển đã hợp nhất.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getDictionaryAsync.md): Hàm cấp thấp hơn mà các build plugins viết lại cuộc gọi này thành.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getLocale.md): Phát hiện locale của một yêu cầu đến.
+
+---
+
+## 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>
+  >
+>;
+```