@intlayer/docs 9.1.3 → 9.2.0

package/docs/vi/intlayer_CMS.md

@@ -244,12 +244,176 @@ Lệnh này sẽ tải các từ điển nội dung ban đầu của bạn lên,
 
 Sau đó, bạn sẽ có thể xem và quản lý từ điển của mình trong [Intlayer CMS](https://app.intlayer.org/content).
 
+## Truy cập lập trình với SDK `@intlayer/api`
+
+Ngoài CLI và trình chỉnh sửa trực quan, Intlayer cung cấp một SDK được gõ kiểu trong gói [`@intlayer/api`](https://www.npmjs.com/package/@intlayer/api). Nó cho phép bạn coi CMS như một **cơ sở dữ liệu nội dung headless**: bạn có thể lấy dự án, lấy từ điển và đẩy hoặc cập nhật chúng trực tiếp từ ứng dụng, tập lệnh hoặc CI pipeline của riêng bạn.
+
+SDK xử lý xác thực cho bạn. Miễn là `clientId` và `clientSecret` của bạn có sẵn (trong cấu hình Intlayer hoặc môi trường của bạn), nó sẽ lấy và làm mới token truy cập OAuth2 tự động và ký mọi yêu cầu.
+
+### Cài đặt
+
+```bash packageManager="npm"
+npm install @intlayer/api
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/api
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/api
+```
+
+```bash packageManager="bun"
+bun add @intlayer/api
+```
+
+### Cách hoạt động: authenticator + endpoints
+
+SDK được chia thành **hai import riêng biệt** có mục đích, để giữ bundle của bạn nhỏ gọn:
+
+1. `createIntlayerCMS` — tạo một **authenticator** nhẹ. Nó chỉ chứa thông tin xác thực và mã token được quản lý; nó không biết gì về bất kỳ domain cụ thể nào.
+2. `dictionaryEndpoint`, `projectEndpoint`, … — **endpoint binders** theo từng domain, mỗi cái được import từ đường dẫn con của nó (`@intlayer/api/dictionary`, `@intlayer/api/project`, …). Bạn truyền authenticator vào endpoint mà bạn cần.
+
+Vì mỗi endpoint được import riêng biệt, bundle của bạn chỉ bao gồm những domain mà bạn thực sự sử dụng — import `dictionaryEndpoint` không bao giờ kéo theo project, AI, hoặc bất kỳ domain client nào khác.
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+
+// Cấu hình là tùy chọn: khi bị bỏ qua, thông tin xác thực được đọc từ
+// `@intlayer/config/built`, cái mà phân giải các biến môi trường
+// INTLAYER_CLIENT_ID và INTLAYER_CLIENT_SECRET.
+export const cmsAuthenticator = createIntlayerCMS();
+```
+
+> [!WARNING]
+> Thông tin xác thực CMS (`clientId` / `clientSecret`) cấp quyền **write access** vào nội dung của bạn. Chỉ tạo authenticator trên **phía server** (server actions, route handlers, scripts, CI). Không bao giờ import nó vào code phía client hoặc để lộ thông tin xác thực của bạn cho trình duyệt.
+
+Nếu bạn không muốn dựa vào cấu hình build-time, hãy truyền thông tin xác thực một cách rõ ràng:
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+
+export const cmsAuthenticator = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    // Tùy chọn, cho các backend tự lưu trữ:
+    // backendURL: process.env.INTLAYER_BACKEND_URL,
+  },
+});
+```
+
+> Lấy thông tin xác thực của bạn bằng cách tạo khóa truy cập mới trong [Intlayer Dashboard - Projects](https://app.intlayer.org/projects).
+
+### Lấy các dự án
+
+```typescript fileName="projects.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { projectEndpoint } from "@intlayer/api/project";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// Liệt kê các dự án có thể truy cập với thông tin xác thực của bạn
+const { data: projects } =
+  await projectEndpoint(cmsAuthenticator).getProjects();
+
+// Đọc thông tin chi tiết bản địa hóa tổng hợp của dự án đã chọn
+const { data: insights } =
+  await projectEndpoint(cmsAuthenticator).getProjectInsights();
+```
+
+### Tìm nạp từ điển
+
+```typescript fileName="read-dictionaries.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// Liệt kê mọi từ điển từ xa của dự án
+const { data: dictionaries } =
+  await dictionaryEndpoint(cmsAuthenticator).getDictionaries();
+
+// Hoặc lấy một từ điển duy nhất theo khóa
+const { data: dictionary } = await dictionaryEndpoint(
+  cmsAuthenticator
+).getDictionary("my-first-dictionary-key");
+```
+
+### Đẩy và cập nhật từ điển
+
+Sử dụng CMS như một cơ sở dữ liệu để ghi nội dung trở lại:
+
+```typescript fileName="write-dictionaries.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// Tạo một từ điển mới
+await dictionaryEndpoint(cmsAuthenticator).addDictionary({
+  key: "my-first-dictionary-key",
+  content: { title: "Hello world" },
+});
+
+// Upsert một loạt từ điển (tạo hoặc cập nhật chúng trong một lệnh gọi)
+await dictionaryEndpoint(cmsAuthenticator).pushDictionaries([
+  { key: "home", content: { title: "Home" } },
+  { key: "about", content: { title: "About" } },
+]);
+
+// Cập nhật một từ điển hiện có
+await dictionaryEndpoint(cmsAuthenticator).updateDictionary({
+  id: "<dictionary-id>",
+  key: "home",
+  content: { title: "Updated title" },
+});
+```
+
+> Mẹo: tái sử dụng endpoint đã liên kết để tránh lặp lại:
+>
+> ```typescript codeFormat="typescript"
+> const dictionary = dictionaryEndpoint(cmsAuthenticator);
+> await dictionary.pushDictionaries([myDictionary]);
+> const { data } = await dictionary.getDictionaries();
+> ```
+
+### Trích xuất một phương thức duy nhất
+
+Mỗi phương thức endpoint đã được xác thực và độc lập (nó mang theo xử lý token riêng của mình), vì vậy bạn có thể trích xuất một phương thức và truyền nó xung quanh — ví dụ để inject nó như một dependency:
+
+```typescript fileName="push.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const dictionary = dictionaryEndpoint(createIntlayerCMS());
+
+// Đã được xác thực — tự động làm mới token trên mỗi lần gọi
+export const pushDictionaries = dictionary.pushDictionaries;
+
+// Cách sử dụng
+await pushDictionaries([{ key: "home", content: { title: "Home" } }]);
+```
+
 ## Đồng bộ trực tiếp (Live sync)
 
 Live Sync cho phép ứng dụng của bạn phản ánh các thay đổi nội dung CMS trong thời gian chạy. Không cần xây dựng lại hoặc triển khai lại. Khi được bật, các cập nhật sẽ được truyền đến máy chủ Live Sync để làm mới các từ điển mà ứng dụng của bạn đang đọc.
 
 Để xem hướng dẫn thiết lập đầy đủ (kích hoạt, khởi động máy chủ Live Sync, quy trình phát triển cục bộ và các giới hạn), xem [tài liệu Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/live-sync.md).
 
+## Tự Hosting
+
+Intlayer có thể chạy hoàn toàn trên cơ sở hạ tầng của riêng bạn. Một lệnh duy nhất khởi động toàn bộ stack (dashboard, API, database, object storage, và email) với Docker Compose:
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Để biết hướng dẫn thiết lập hoàn chỉnh, tham khảo biến môi trường, hướng dẫn nâng cấp và các thủ tục sao lưu/khôi phục, hãy xem [Hướng dẫn Tự Hosting](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/self_hosting.md).
+
+---
+
 ## Gỡ lỗi
 
 Nếu bạn gặp bất kỳ vấn đề nào với CMS, hãy kiểm tra các điều sau:

package/docs/vi/intlayer_with_angular_21.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-04-18
 updatedAt: 2026-05-31
-title: "Angular 21 i18n - Hướng dẫn đầy đủ để dịch ứng dụng của bạn"
-description: "Không còn i18next nữa. Hướng dẫn 2026 để xây dựng ứng dụng Angular 21 đa ngôn ngữ (i18n). Dịch với các AI agent và tối ưu hóa kích thước bundle, SEO và hiệu suất."
+title: "Angular 22 i18n - Hướng dẫn đầy đủ để dịch ứng dụng của bạn"
+description: "Không còn i18next nữa. Hướng dẫn 2026 để xây dựng ứng dụng Angular 22 đa ngôn ngữ (i18n). Dịch với các AI agent và tối ưu hóa kích thước bundle, SEO và hiệu suất."
 keywords:
   - Quốc tế hóa
   - Tài liệu
@@ -13,8 +13,8 @@ slugs:
   - doc
   - environment
   - angular
-applicationTemplate: https://github.com/aymericzip/intlayer-angular-21-template
-applicationShowcase: https://intlayer-angular-21-template.vercel.app/
+applicationTemplate: https://github.com/aymericzip/intlayer-angular-22-template
+applicationShowcase: https://intlayer-angular-22-template.vercel.app/
 history:
   - version: 8.9.0
     date: 2026-05-04
@@ -31,7 +31,7 @@ history:
 author: aymericzip
 ---
 
-# Dịch trang web Angular 21 (Vite) của bạn bằng Intlayer | Quốc tế hóa (i18n)
+# Dịch trang web Angular 22 (Vite) của bạn bằng Intlayer | Quốc tế hóa (i18n)
 
 ## Mục lục
 
@@ -94,7 +94,7 @@ Không chỉ là giải pháp i18n, Intlayer còn cung cấp **[trình chỉnh s
   <Tab label="Mã" value="code">
 
 <iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-angular-21-template?file=intlayer.config.ts"
+  src="https://ide.intlayer.org/aymericzip/intlayer-angular-22-template?file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo CodeSandbox - Cách quốc tế hóa ứng dụng của bạn bằng Intlayer"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -105,7 +105,7 @@ Không chỉ là giải pháp i18n, Intlayer còn cung cấp **[trình chỉnh s
   <Tab label="Demo" value="demo">
 
 <iframe
-  src="https://intlayer-angular-21-template.vercel.app/"
+  src="https://intlayer-angular-22-template.vercel.app/"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo - intlayer-angular-template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -115,7 +115,7 @@ Không chỉ là giải pháp i18n, Intlayer còn cung cấp **[trình chỉnh s
   </Tab>
 </Tabs>
 
-Xem [Mẫu Ứng Dụng](https://github.com/aymericzip/intlayer-angular-21-template) trên GitHub.
+Xem [Mẫu Ứng Dụng](https://github.com/aymericzip/intlayer-angular-22-template) trên GitHub.
 
 <Steps>
 
@@ -203,7 +203,7 @@ export default config;
 
 <Step number={3} title="Tích hợp Intlayer vào Cấu hình Angular của bạn">
 
-Để tích hợp Intlayer với Angular CLI, bạn cần sử dụng một builder tùy chỉnh. Hướng dẫn này giả định bạn đang sử dụng Vite/esbuild (mặc định cho các dự án Angular 21).
+Để tích hợp Intlayer với Angular CLI, bạn cần sử dụng một builder tùy chỉnh. Hướng dẫn này giả định bạn đang sử dụng Vite/esbuild (mặc định cho các dự án Angular 22).
 
 Trước tiên, sửa đổi tập tin `angular.json` của bạn để sử dụng builder esbuild tùy chỉnh. Cập nhật cấu hình `build` và `serve`:
 

package/docs/vi/intlayer_with_nextjs_14.md

@@ -44,31 +44,6 @@ author: aymericzip
 
 # Dịch trang web Next.js 14 và App Router của bạn bằng Intlayer | Quốc tế hóa (i18n)
 
-<Tabs defaultTab="code">
-  <Tab label="Mã nguồn" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-next-14-template?file=intlayer.config.ts"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - Cách quốc tế hóa ứng dụng của bạn bằng Intlayer"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-  <Tab label="Bản demo" value="demo">
-
-<iframe
-  src="https://intlayer-next-14-template.vercel.app"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Bản demo - intlayer-next-14-template"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-</Tabs>
-
 ## Mục lục
 
 <TOC/>

package/docs/vi/intlayer_with_react_router_v7_fs_routes.md

@@ -101,7 +101,7 @@ Không chỉ là giải pháp i18n, Intlayer còn cung cấp **[trình chỉnh s
 
 <Tabs defaultTab="video">
   <Tab label="Video" value="video">
-  
+
 <iframe title="How to translate an React Router v7 (File-System Routes) app using Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/dS9L7uJeak4?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
   </Tab>
@@ -189,6 +189,75 @@ export default [
 
 Thiết lập root layout và các layout theo ngôn ngữ cụ thể:
 
+#### Cấu trúc File
+
+```bash
+app/
+├── root.tsx                         # Layout wrapper for locale routes
+└──routes/
+    ├── ($locale)._index.tsx         # Home page (/, /es, etc.)
+    ├── ($locale)._index.content.ts  # Home page content
+    ├── ($locale).about.tsx          # About page (/about, /es/about, etc.)
+    └── ($locale).about.content.ts   # About page content
+```
+
+Các quy ước đặt tên:
+
+- `($locale)` - Optional dynamic segment cho locale parameter
+- `_layout` - Layout route bao bọc các child routes
+- `_index` - Index route (renders tại parent path)
+- `.` (dot) - Separates path segments (e.g., `($locale).about` → `/:locale?/about`)
+
+#### Thành phần Layout
+
+```tsx fileName="app/root.tsx"
+import { getLocaleFromPath } from "intlayer";
+import { IntlayerProvider } from "react-intlayer";
+import {
+  isRouteErrorResponse,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+  useLoaderData,
+} from "react-router";
+
+import type { Route } from "./+types/root";
+
+import "./app.css";
+
+// ... Mã App, links và ErrorBoundary không thay đổi
+
+export async function loader({ request }: Route.LoaderArgs) {
+  const locale = getLocaleFromPath(request.url);
+
+  return { locale };
+}
+
+export function Layout({
+  children,
+}: { children: React.ReactNode } & Route.ComponentProps) {
+  const data = useLoaderData<typeof loader>();
+  const { locale } = data ?? {};
+
+  return (
+    <html lang={locale}>
+      <head>
+        <meta charSet="utf-8" />
+        <meta content="width=device-width, initial-scale=1" name="viewport" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+
 #### Root Layout
 
 ```tsx fileName="app/routes/layout.tsx"
@@ -571,68 +640,6 @@ Ensure your TypeScript configuration includes the autogenerated types:
 
 ---
 
-## Documentation References
-
-- [Intlayer Documentation](https://intlayer.org)
-- [React Router v7 Documentation](https://reactrouter.com/)
-- [React Router fs-routes Documentation](https://reactrouter.com/how-to/file-route-conventions)
-- [useIntlayer hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useIntlayer.md)
-- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useLocale.md)
-- [Content Declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md)
-- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
-
-This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 using file-system based routing for a fully internationalized application with locale-aware routing and TypeScript support.
-
-<Steps>
-
-<Step number={11} title="Thêm middleware">
-
-Bạn cũng có thể sử dụng `intlayerProxy` để thêm routing phía server cho ứng dụng của bạn. Plugin này sẽ tự động phát hiện locale hiện tại dựa trên URL và thiết lập cookie locale phù hợp. Nếu không có locale nào được chỉ định, plugin sẽ xác định locale phù hợp nhất dựa trên ngôn ngữ trình duyệt của người dùng. Nếu không phát hiện được locale nào, nó sẽ chuyển hướng đến locale mặc định.
-
-> Lưu ý rằng để sử dụng `intlayerProxy` trong môi trường production, bạn cần chuyển gói `vite-intlayer` từ `devDependencies` sang `dependencies`.
-
-```typescript {3,7} fileName="vite.config.ts"
-import { reactRouter } from "@react-router/dev/vite";
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    reactRouter(),
-
-    intlayer({
-      proxy: {
-        ignore: (req) => req.url?.startsWith("/api"),
-      },
-    }),
-  ],
-});
-```
-
----
-
-</Step>
-
-</Steps>
-
-## Cấu hình TypeScript
-
-Intlayer sử dụng module augmentation để tận dụng các lợi ích của TypeScript và làm cho codebase của bạn mạnh mẽ hơn.
-
-Đảm bảo cấu hình TypeScript của bạn bao gồm các kiểu được tạo tự động:
-
-```json5 fileName="tsconfig.json"
-{
-  // ... các cấu hình hiện có của bạn
-  include: [
-    // ... các phần include hiện có của bạn
-    ".intlayer/**/*.ts", // Bao gồm các kiểu được tạo tự động
-  ],
-}
-```
-
----
-
 ## Cấu hình Git
 
 Khuyến nghị bỏ qua các tệp được tạo bởi Intlayer. Điều này giúp bạn tránh việc commit chúng vào kho Git của mình.