@intlayer/docs 7.0.7 → 7.0.8-canary.0

package/docs/vi/packages/express-intlayer/t.md

@@ -0,0 +1,457 @@
+---
+createdAt: 2024-12-02
+updatedAt: 2025-06-29
+title: Tài liệu hàm t | express-intlayer
+description: Xem cách sử dụng hàm t cho gói express-intlayer
+keywords:
+  - t
+  - dịch thuật
+  - Intlayer
+  - Quốc tế hóa
+  - Tài liệu
+  - Express
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - express-intlayer
+  - t
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Khởi tạo lịch sử
+---
+
+# Tài liệu: Hàm `t` trong `express-intlayer`
+
+Hàm `t` trong gói `express-intlayer` là tiện ích cốt lõi để cung cấp các phản hồi được địa phương hóa trong ứng dụng Express của bạn. Nó đơn giản hóa việc quốc tế hóa (i18n) bằng cách chọn nội dung một cách động dựa trên ngôn ngữ ưu tiên của người dùng.
+
+---
+
+## Tổng quan
+
+Hàm `t` được sử dụng để định nghĩa và truy xuất các bản dịch cho một tập hợp ngôn ngữ nhất định. Nó tự động xác định ngôn ngữ phù hợp để trả về dựa trên cài đặt yêu cầu của client, chẳng hạn như header `Accept-Language`. Nếu ngôn ngữ ưu tiên không có sẵn, nó sẽ tự động chuyển về locale mặc định được chỉ định trong cấu hình của bạn một cách mượt mà.
+
+---
+
+## Các tính năng chính
+
+- **Địa phương hóa động**: Tự động chọn bản dịch phù hợp nhất cho client.
+- **Chuyển về locale mặc định**: Chuyển về locale mặc định nếu ngôn ngữ ưu tiên của client không có sẵn, đảm bảo trải nghiệm người dùng liên tục.
+- **Nhẹ và nhanh**: Thiết kế cho các ứng dụng hiệu năng cao, đảm bảo chi phí tài nguyên tối thiểu.
+- **Hỗ trợ Chế độ Nghiêm ngặt**: Thực thi tuân thủ nghiêm ngặt các locale đã khai báo để đảm bảo hành vi đáng tin cậy.
+
+---
+
+## Chữ ký Hàm
+
+```typescript
+t(translations: Record<string, string>): string;
+```
+
+### Tham số
+
+- `translations`: Một đối tượng trong đó các khóa là mã locale (ví dụ: `en`, `fr`, `es-MX`) và các giá trị là các chuỗi đã được dịch tương ứng.
+
+### Trả về
+
+- Một chuỗi đại diện cho nội dung theo ngôn ngữ ưu tiên của client.
+
+---
+
+## Tải Bộ Xử lý Yêu cầu Quốc tế hóa
+
+Để đảm bảo chức năng quốc tế hóa do `express-intlayer` cung cấp hoạt động chính xác, bạn **phải** tải middleware quốc tế hóa ở đầu ứng dụng Express của bạn. Điều này kích hoạt hàm `t` và đảm bảo xử lý đúng việc phát hiện locale và dịch thuật.
+
+Đặt middleware `app.use(intlayer())` **trước bất kỳ route nào** trong ứng dụng của bạn để đảm bảo tất cả các route đều được hưởng lợi từ tính năng quốc tế hóa:
+
+```typescript {7} fileName="src/index.ts" codeFormat="typescript"
+import express, { type Express } from "express";
+import { intlayer } from "express-intlayer";
+
+const app: Express = express();
+
+// Tải bộ xử lý yêu cầu quốc tế hóa
+app.use(intlayer());
+
+// Định nghĩa các route sau khi đã tải middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {7} fileName="src/index.mjs" codeFormat="esm"
+import express from "express";
+import { intlayer } from "express-intlayer";
+
+const app = express();
+
+// Tải bộ xử lý yêu cầu quốc tế hóa
+app.use(intlayer());
+
+// Định nghĩa các route sau khi đã tải middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {7} fileName="src/index.cjs" codeFormat="commonjs"
+const express = require("express");
+const { intlayer } = require("express-intlayer");
+
+const app = express();
+
+// Tải bộ xử lý yêu cầu quốc tế hóa
+app.use(intlayer());
+
+// Định nghĩa các route sau khi đã tải middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+### Tại sao điều này là cần thiết
+
+- **Phát hiện ngôn ngữ**: Middleware `intlayer` xử lý các yêu cầu đến để phát hiện ngôn ngữ ưu tiên của người dùng dựa trên headers, cookies hoặc các phương pháp cấu hình khác.
+- **Ngữ cảnh dịch thuật**: Thiết lập ngữ cảnh cần thiết để hàm `t` hoạt động chính xác, đảm bảo các bản dịch được trả về đúng ngôn ngữ.
+- **Ngăn ngừa lỗi**: Nếu không có middleware này, việc sử dụng hàm `t` sẽ gây ra lỗi thời gian chạy vì thông tin ngôn ngữ cần thiết sẽ không có sẵn.
+
+---
+
+## Ví dụ sử dụng
+
+### Ví dụ cơ bản
+
+Phục vụ nội dung được địa phương hóa bằng các ngôn ngữ khác nhau:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+**Yêu cầu từ phía client:**
+
+- Một client với `Accept-Language: fr` sẽ nhận được `Bienvenue!`.
+- Một client với `Accept-Language: es` sẽ nhận được `¡Bienvenido!`.
+- Một client với `Accept-Language: de` sẽ nhận được `Welcome!` (ngôn ngữ mặc định).
+
+### Xử lý lỗi
+
+Cung cấp thông báo lỗi bằng nhiều ngôn ngữ:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    })
+  );
+});
+```
+
+---
+
+### Sử dụng các biến thể ngôn ngữ
+
+Chỉ định các bản dịch cho các biến thể ngôn ngữ cụ thể:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+    })
+  );
+});
+```
+
+---
+
+## Các Chủ Đề Nâng Cao
+
+### Cơ Chế Dự Phòng (Fallback Mechanism)
+
+Nếu một locale ưu tiên không có sẵn, hàm `t` sẽ tự động chuyển sang locale mặc định được định nghĩa trong cấu hình:
+
+```typescript {5-6} fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+```javascript {5-6} fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript {5-6} fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+Ví dụ:
+
+- Nếu `defaultLocale` là `Locales.CHINESE` và một client yêu cầu `Locales.DUTCH`, bản dịch trả về sẽ mặc định là giá trị của `Locales.CHINESE`.
+- Nếu `defaultLocale` không được định nghĩa, hàm `t` sẽ tự động chuyển sang giá trị của `Locales.ENGLISH`.
+
+---
+
+### Bắt Buộc Chế Độ Strict
+
+Cấu hình hàm `t` để bắt buộc tuân thủ nghiêm ngặt các locale đã khai báo:
+
+| Chế độ      | Hành vi                                                                                |
+| ----------- | -------------------------------------------------------------------------------------- |
+| `strict`    | Tất cả các locale đã khai báo phải có bản dịch. Thiếu locale sẽ gây lỗi.               |
+| `inclusive` | Các locale đã khai báo phải có bản dịch. Thiếu locale sẽ cảnh báo nhưng vẫn chấp nhận. |
+| `loose`     | Bất kỳ locale nào tồn tại đều được chấp nhận, kể cả khi không được khai báo.           |
+
+Ví dụ cấu hình:
+
+```typescript {7} fileName="intlayer.config.ts" codeFormat="typescript"
+import { type IntlayerConfig } from "intlayer";
+
+const config = {
+  // ... Cấu hình hiện có của bạn
+  internationalization: {
+    // ... Cấu hình quốc tế hóa hiện có của bạn
+    strictMode: "strict", // Bắt buộc chế độ nghiêm ngặt
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+```javascript {7} fileName="intlayer.config.mjs" codeFormat="esm"
+import { type IntlayerConfig } from "intlayer";
+
+const config = {
+  // ... Cấu hình hiện có của bạn
+  internationalization: {
+    // ... Cấu hình quốc tế hóa hiện có của bạn
+    strictMode: "strict", // Bắt buộc chế độ nghiêm ngặt
+  },
+};
+
+export default config;
+```
+
+```javascript {7} fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Cấu hình hiện có của bạn
+  internationalization: {
+    // ... Cấu hình quốc tế hóa hiện có của bạn
+    strictMode: "strict", // Bắt buộc chế độ nghiêm ngặt
+  },
+};
+
+module.exports = config;
+```
+
+---
+
+### Tích hợp TypeScript
+
+Hàm `t` an toàn về kiểu khi sử dụng với TypeScript. Định nghĩa một đối tượng bản dịch an toàn về kiểu:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import { type LanguageContent } from "express-intlayer";
+
+const translations: LanguageContent<string> = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  es: "¡Buenos días!",
+};
+
+app.get("/morning", (_req, res) => {
+  res.send(t(translations));
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+import { type LanguageContent } from "express-intlayer";
+
+/** @type {import('express-intlayer').LanguageContent<string>} */
+const translations = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  es: "¡Buenos días!",
+};
+
+app.get("/morning", (_req, res) => {
+  res.send(t(translations));
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+const { type LanguageContent } = require("express-intlayer");
+
+/** @type {import('express-intlayer').LanguageContent<string>} */
+const translations = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  es: "¡Buenos días!",
+};
+
+app.get("/morning", (_req, res) => {
+  res.send(t(translations));
+});
+```
+
+---
+
+### Các lỗi phổ biến và cách khắc phục
+
+| Vấn đề                  | Nguyên nhân                                         | Giải pháp                                                |
+| ----------------------- | --------------------------------------------------- | -------------------------------------------------------- |
+| Hàm `t` không hoạt động | Middleware chưa được tải                            | Đảm bảo `app.use(intlayer())` được thêm trước các route. |
+| Lỗi thiếu bản dịch      | Chế độ Strict được bật nhưng không có đủ các locale | Cung cấp đầy đủ các bản dịch cần thiết.                  |
+
+---
+
+## Mẹo sử dụng hiệu quả
+
+1. **Tập trung quản lý bản dịch**: Sử dụng một module tập trung hoặc các file JSON để quản lý bản dịch nhằm cải thiện khả năng bảo trì.
+2. **Xác thực bản dịch**: Đảm bảo mỗi biến thể ngôn ngữ đều có bản dịch tương ứng để tránh việc fallback không cần thiết.
+3. **Kết hợp với i18n phía frontend**: Đồng bộ hóa với hệ thống quốc tế hóa phía frontend để mang lại trải nghiệm người dùng liền mạch trên toàn ứng dụng.
+4. **Đánh giá hiệu năng**: Kiểm tra thời gian phản hồi của ứng dụng khi thêm bản dịch để đảm bảo ảnh hưởng tối thiểu.
+
+---
+
+## Kết luận
+
+Hàm `t` là một công cụ mạnh mẽ cho việc quốc tế hóa backend. Bằng cách sử dụng hiệu quả, bạn có thể tạo ra một ứng dụng thân thiện với người dùng và bao quát hơn cho đối tượng toàn cầu. Để biết cách sử dụng nâng cao và các tùy chọn cấu hình chi tiết, hãy tham khảo [tài liệu](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md).

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

@@ -0,0 +1,145 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Tài liệu hàm getConfiguration | intlayer
+description: Xem cách sử dụng hàm getConfiguration cho gói intlayer
+keywords:
+  - getConfiguration
+  - dịch thuật
+  - Intlayer
+  - intlayer
+  - Quốc tế hóa
+  - Tài liệu
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getConfiguration
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Khởi tạo lịch sử
+---
+
+# Tài liệu: Hàm `getConfiguration` trong `intlayer`
+
+## Mô tả
+
+Hàm `getConfiguration` lấy toàn bộ cấu hình cho ứng dụng `intlayer` bằng cách trích xuất các biến môi trường. Hàm này cung cấp sự linh hoạt để sử dụng cùng một cấu hình trên cả phía client và server, đảm bảo tính nhất quán trên toàn bộ ứng dụng.
+
+---
+
+## Tham số
+
+Hàm không nhận tham số nào. Thay vào đó, nó sử dụng các biến môi trường để cấu hình.
+
+### Giá trị trả về
+
+- **Kiểu**: `IntlayerConfig`
+- **Mô tả**: Một đối tượng chứa cấu hình đầy đủ cho `intlayer`. Cấu hình bao gồm các phần sau:
+  - `internationalization`: Các thiết lập liên quan đến locale và chế độ strict.
+  - `middleware`: Các thiết lập liên quan đến quản lý URL và cookie.
+  - `content`: Các thiết lập liên quan đến các tệp nội dung, thư mục và mẫu.
+  - `editor`: Các cấu hình riêng biệt cho trình soạn thảo.
+
+Xem thêm [Tài liệu cấu hình Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md) để biết chi tiết.
+
+---
+
+## Ví dụ sử dụng
+
+### Lấy toàn bộ cấu hình
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// Kết quả:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// Kết quả:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const config = getConfiguration();
+console.log(config);
+// Kết quả:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+### Trích xuất `availableLocales` và `defaultLocale`
+
+Phần `internationalization` trong cấu hình cung cấp các thiết lập liên quan đến locale như `locales` (các locale có sẵn) và `defaultLocale` (ngôn ngữ dự phòng).
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Ví dụ kết quả: ["en", "fr", "es"]
+console.log(defaultLocale); // Ví dụ kết quả: "en"
+console.log(cookieName); // Kết quả: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Ví dụ kết quả: ["en", "fr", "es"]
+console.log(defaultLocale); // Ví dụ kết quả: "en"
+console.log(cookieName); // Kết quả: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Ví dụ kết quả: ["en", "fr", "es"]
+console.log(defaultLocale); // Ví dụ kết quả: "en"
+console.log(cookieName); // Kết quả: "INTLAYER_LOCALE"
+```
+
+## Ghi chú
+
+- Đảm bảo rằng tất cả các biến môi trường cần thiết đã được thiết lập chính xác trước khi gọi hàm này. Thiếu biến sẽ gây lỗi trong quá trình khởi tạo.
+- Hàm này có thể được sử dụng cả ở phía client và server, làm cho nó trở thành công cụ linh hoạt để quản lý cấu hình một cách thống nhất.
+
+## Sử dụng trong Ứng dụng
+
+Hàm `getConfiguration` là một tiện ích then chốt để khởi tạo và quản lý cấu hình của một ứng dụng `intlayer`. Bằng cách cung cấp quyền truy cập vào các thiết lập như locales, middleware và thư mục nội dung, nó đảm bảo tính nhất quán và khả năng mở rộng trên các ứng dụng đa ngôn ngữ và dựa trên nội dung.