@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

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

@@ -0,0 +1,173 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Tài liệu hàm comparePaths | intlayer
+description: Xem cách sử dụng hàm comparePaths cho gói intlayer
+keywords:
+  - comparePaths
+  - normalizePath
+  - liên kết đang hoạt động (active link)
+  - điều hướng (navigation)
+  - Intlayer
+  - intlayer
+  - Quốc tế hóa (Internationalization)
+  - Tài liệu (Documentation)
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - comparePaths
+history:
+  - version: 9.0.0
+    date: 2026-06-22
+    changes: "Tài liệu ban đầu"
+author: aymericzip
+---
+
+# Tài liệu: Hàm `comparePaths` trong `intlayer`
+
+## Mô tả
+
+Hàm `comparePaths` so sánh hai URL hoặc đường dẫn để kiểm tra sự trùng khớp trong khi bỏ qua phần locale, giao thức/host, chuỗi truy vấn (query string), hash và các dấu gạch chéo ở cuối (trailing slashes). Đây là cách được khuyến nghị để xác định xem một liên kết điều hướng có trỏ đến trang hiện tại hay không — ví dụ: để làm nổi bật liên kết đang hoạt động — mà không cần phải tự viết logic chuẩn hóa riêng (dễ bị lỗi).
+
+Về mặt nội bộ, nó sử dụng lại [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPathWithoutLocale.md) để loại bỏ phần locale, do đó nó tôn trọng chế độ định tuyến và các locales đã được định cấu hình của bạn.
+
+Gói cũng xuất ra một hàm hỗ trợ cơ bản là [`normalizePath`](#normalizepath), nó trả về đường dẫn chuẩn, không phụ thuộc vào locale được sử dụng cho mục đích so sánh.
+
+**Các tính năng chính:**
+
+- So sánh không phụ thuộc locale (`/vi/about` khớp với `/about`)
+- Hoạt động với cả URL tuyệt đối và đường dẫn tương đối
+- Bỏ qua chuỗi truy vấn, hash và các dấu gạch chéo ở cuối
+- Cho phép bỏ qua dấu gạch chéo ở đầu và giá trị rỗng (được chuẩn hóa thành `/`)
+- Nhẹ nhàng — được xây dựng trên `getPathWithoutLocale`
+
+---
+
+## Chữ ký hàm (Function Signature)
+
+```typescript
+comparePaths(
+  pathname: string,  // Bắt buộc
+  href: string,      // Bắt buộc
+  locales?: Locales[] // Không bắt buộc
+): boolean
+
+normalizePath(
+  inputUrl: string,   // Bắt buộc
+  locales?: Locales[] // Không bắt buộc
+): string
+```
+
+---
+
+## Tham số
+
+- `pathname: string`
+  - **Mô tả**: Chuỗi URL hoặc đường dẫn đầu tiên để so sánh (thường là đường dẫn hiện tại).
+  - **Loại**: `string`
+  - **Bắt buộc**: Có
+
+- `href: string`
+  - **Mô tả**: Chuỗi URL hoặc đường dẫn thứ hai để so sánh (thường là `href` của một liên kết điều hướng).
+  - **Loại**: `string`
+  - **Bắt buộc**: Có
+
+- `locales: Locales[]`
+  - **Mô tả**: Mảng tùy chọn chứa các locales được hỗ trợ. Mặc định là các locales đã được định cấu hình trong dự án.
+  - **Loại**: `Locales[]`
+  - **Bắt buộc**: Không (Tùy chọn)
+
+### Kết quả trả về
+
+- **Loại**: `boolean`
+- **Mô tả**: `true` khi cả hai đầu vào đều phân giải về cùng một đường dẫn không phụ thuộc locale, ngược lại trả về `false`.
+
+---
+
+## Ví dụ sử dụng
+
+### Sử dụng cơ bản
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { comparePaths } from "intlayer";
+
+comparePaths("/ru/path", "/path"); // true
+comparePaths("/ru/path/", "/path"); // true
+comparePaths("/ru/path", "/path/"); // true
+comparePaths("/ru/", "/"); // true
+comparePaths("/ru", "/"); // true
+comparePaths("ru/path", "/path"); // true
+comparePaths("", "/"); // true
+comparePaths("/ru", ""); // true
+comparePaths("/ru/path", "/other"); // false
+```
+
+### URL tuyệt đối và tương đối
+
+```typescript
+import { comparePaths } from "intlayer";
+
+comparePaths("https://example.com/ru/path", "/path"); // true
+```
+
+### Làm nổi bật liên kết điều hướng đang hoạt động
+
+```tsx
+import { comparePaths } from "intlayer";
+import { useLocation } from "react-router";
+
+const NavLink = ({ href, children }) => {
+  const { pathname } = useLocation();
+  const isActive = comparePaths(pathname, href);
+
+  return (
+    <a href={href} aria-current={isActive ? "page" : undefined}>
+      {children}
+    </a>
+  );
+};
+```
+
+---
+
+## normalizePath
+
+`normalizePath` trả về đường dẫn chuẩn, không phụ thuộc locale được sử dụng bởi `comparePaths`. Nó loại bỏ phần locale, giao thức/host, chuỗi truy vấn và hash, đảm bảo chỉ có một dấu gạch chéo ở đầu, loại bỏ bất kỳ dấu gạch chéo ở cuối (ngoại trừ root) và dùng `/` thay thế cho các giá trị rỗng.
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { normalizePath } from "intlayer";
+
+normalizePath("/ru/path"); // "/path"
+normalizePath("/ru/path/"); // "/path"
+normalizePath("ru/path"); // "/path"
+normalizePath("/ru/"); // "/"
+normalizePath("/ru"); // "/"
+normalizePath(""); // "/"
+normalizePath("https://example.com/ru/path"); // "/path"
+```
+
+---
+
+## Các hàm liên quan
+
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPathWithoutLocale.md): Loại bỏ phần locale khỏi một URL hoặc đường dẫn.
+- [`getPrefix`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPrefix.md): Xác định tiền tố URL cho một locale cụ thể.
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getLocalizedUrl.md): Tạo ra một URL đã được bản địa hóa cho một locale cụ thể.
+
+---
+
+## TypeScript
+
+```typescript
+function normalizePath(inputUrl: string, locales?: Locales[]): string;
+
+function comparePaths(
+  pathname: string,
+  href: string,
+  locales?: Locales[]
+): boolean;
+```

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

@@ -14,6 +14,9 @@ slugs:
   - intlayer
   - exports
 history:
+  - version: 9.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích comparePaths"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Hợp nhất tài liệu cho tất cả các exports"
@@ -119,6 +122,8 @@ import "intlayer";
 | `getMultilingualUrls`  | `Function` | Tạo các URL cho tất cả các locale được hỗ trợ.                          | [getMultilingualUrls](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getMultilingualUrls.md)   |
 | `getPathWithoutLocale` | `Function` | Xóa tiền tố locale khỏi đường dẫn.                                      | [getPathWithoutLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPathWithoutLocale.md) |
 | `getPrefix`            | `Function` | Lấy tiền tố locale từ đường dẫn.                                        | [getPrefix](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPrefix.md)                       |
+| `comparePaths`         | `Function` | So sánh hai đường dẫn mà bỏ qua locale.                                 | [comparePaths](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/comparePaths.md)                 |
+| `normalizePath`        | `Function` | Chuẩn hóa một đường dẫn thành đường dẫn không có locale.                | [comparePaths](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/comparePaths.md)                 |
 | `getHTMLTextDir`       | `Function` | Lấy hướng văn bản (LTR/RTL).                                            | [getHTMLTextDir](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getHTMLTextDir.md)             |
 | `validatePrefix`       | `Function` | Xác thực một tiền tố locale.                                            | [validatePrefix](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/validatePrefix.md)             |
 

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

@@ -144,6 +144,31 @@ getLocalizedUrl(
 // Kết quả: "/about" cho locale mặc định (tiếng Anh)
 ```
 
+### Advanced Usage (With Optional Parameters)
+
+You can override the default configuration by providing the optional `options` parameter:
+
+### Relative URLs (All Options Specified)
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getLocalizedUrl, Locales } from "intlayer";
+
+// Cung cấp tất cả các tham số tùy chọn một cách rõ ràng
+getLocalizedUrl("/about", Locales.FRENCH, {
+  locales: [Locales.ENGLISH, Locales.FRENCH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Output: "/fr/about" cho locale tiếng Pháp
+
+getLocalizedUrl("/about", Locales.ENGLISH, {
+  locales: [Locales.ENGLISH, Locales.FRENCH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Output: "/about" cho locale mặc định (English)
+```
+
 ### Ghi đè cấu hình một phần
 
 Bạn cũng có thể chỉ cung cấp một số tham số tùy chọn. Hàm sẽ sử dụng cấu hình dự án của bạn cho bất kỳ tham số nào bạn không chỉ định:

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

@@ -33,6 +33,23 @@ Hàm `getMultilingualUrls` tạo ra một ánh xạ các URL đa ngôn ngữ b
 
 ---
 
+## Chữ Ký Hàm
+
+```typescript
+getMultilingualUrls(
+  url: string,                   // Bắt buộc
+  options?: {                    // Tùy chọn
+    locales?: Locales[];
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): StrictModeLocaleMap<string>
+```
+
+---
+
+## Tham số
+
 ## Tham số
 
 - `url: string`
@@ -54,6 +71,33 @@ Hàm `getMultilingualUrls` tạo ra một ánh xạ các URL đa ngôn ngữ b
   - **Kiểu**: `boolean`
   - **Mặc định**: `prefixDefaultDefault`
 
+### Tham số tùy chọn
+
+- `options?: object`
+  - **Description**: Đối tượng cấu hình cho hành vi địa phương hóa URL.
+  - **Type**: `object`
+  - **Required**: No (Tùy chọn)
+
+  - `options.locales?: Locales[]`
+    - **Description**: Mảng các locale được hỗ trợ. Nếu không được cung cấp, sẽ sử dụng các locale được cấu hình từ cấu hình dự án của bạn.
+    - **Type**: `Locales[]`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md#middleware)
+
+  - `options.defaultLocale?: Locales`
+    - **Description**: Locale mặc định cho ứng dụng. Nếu không được cung cấp, sẽ sử dụng locale mặc định được cấu hình từ cấu hình dự án của bạn.
+    - **Type**: `Locales`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Description**: Chế độ định tuyến URL cho xử lý locale. Nếu không được cung cấp, sẽ sử dụng chế độ được cấu hình từ cấu hình dự án của bạn.
+    - **Type**: `'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+    - **Default**: [`Project Configuration`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md#middleware)
+    - **Modes**:
+      - `prefix-no-default`: Không có tiền tố cho locale mặc định, có tiền tố cho tất cả các locale khác
+      - `prefix-all`: Tiền tố cho tất cả các locale bao gồm cả locale mặc định
+      - `no-prefix`: Không có tiền tố locale trong URL
+      - `search-params`: Sử dụng query parameters cho locale (ví dụ: `?locale=fr`)
+
 ### Trả về
 
 - **Kiểu**: `IConfigLocales<string>`
@@ -63,6 +107,20 @@ Hàm `getMultilingualUrls` tạo ra một ánh xạ các URL đa ngôn ngữ b
 
 ## Ví dụ sử dụng
 
+### Cách sử dụng cơ bản (Sử dụng cấu hình dự án)
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getMultilingualUrls, Locales } from "intlayer";
+
+// Sử dụng cấu hình dự án của bạn cho locales, defaultLocale và mode
+getMultilingualUrls("/dashboard");
+// Output (giả sử cấu hình dự án có en, fr với mode 'prefix-no-default'):
+// {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard"
+// }
+```
+
 ### URL tương đối
 
 ```typescript codeFormat={["typescript", "esm", "commonjs"]}
@@ -97,6 +155,60 @@ getMultilingualUrls(
 
 ---
 
+### Các Chế Độ Định Tuyến Khác Nhau
+
+```typescript
+// prefix-no-default: Không có tiền tố cho ngôn ngữ mặc định
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// Output: {
+//   en: "/dashboard",
+//   fr: "/fr/dashboard",
+//   es: "/es/dashboard"
+// }
+
+// prefix-all: Tiền tố cho tất cả các ngôn ngữ
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// Output: {
+//   en: "/en/dashboard",
+//   fr: "/fr/dashboard",
+//   es: "/es/dashboard"
+// }
+
+// no-prefix: Không có tiền tố ngôn ngữ trong URL
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "no-prefix",
+});
+// Output: {
+//   en: "/dashboard",
+//   fr: "/dashboard",
+//   es: "/dashboard"
+// }
+
+// search-params: Ngôn ngữ làm tham số truy vấn
+getMultilingualUrls("/dashboard", {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.ENGLISH,
+  mode: "search-params",
+});
+// Output: {
+//   en: "/dashboard?locale=en",
+//   fr: "/dashboard?locale=fr",
+//   es: "/dashboard?locale=es"
+// }
+```
+
+---
+
 ## Các trường hợp đặc biệt
 
 - **Không có đoạn ngôn ngữ:**

package/docs/vi/packages/next-intlayer/exports.md

@@ -15,6 +15,9 @@ slugs:
   - next-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích usePathname"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Hợp nhất tài liệu cho tất cả các exports"
@@ -95,6 +98,7 @@ Tái xuất hầu hết các hooks từ `react-intlayer`.
 | `useDictionaryAsync`   | Hook xử lý các dictionary bất đồng bộ. Nhận một map dictionary dựa trên Promise và resolve nó cho locale hiện tại.              | -                                                                                                                       |
 | `useDictionaryDynamic` | Hook xử lý các dictionary động được load theo key. Sử dụng React Suspense nội bộ để quản lý trạng thái tải.                     | -                                                                                                                       |
 | `useLocale`            | Hook phía client để lấy locale hiện tại và một hàm để thiết lập nó. Được cải tiến cho Next.js App Router với hỗ trợ điều hướng. | [useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/react-intlayer/useLocale.md)         |
+| `usePathname`          | Trả về pathname hiện tại đã được loại bỏ tiền tố locale và loại bỏ các tham số truy vấn liên quan đến locale.                   | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/next-intlayer/usePathname.md)      |
 | `useRewriteURL`        | Hook phía client để quản lý URL rewrites. Tự động cập nhật URL nếu tồn tại quy tắc rewrite bản địa hóa gọn gàng hơn.            | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/next-intlayer/useRewriteURL.md)  |
 | `useLocalePageRouter`  | Hook dành cho Next.js Page Router để quản lý locale. Xử lý chuyển hướng và tải lại trang khi thay đổi locale.                   | -                                                                                                                       |
 | `useI18n`              | Hook cung cấp hàm dịch `t()` để truy cập nội dung lồng nhau theo khóa. Mô phỏng mô hình i18next/next-intl.                      | [useI18n](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/react-intlayer/useI18n.md)             |

package/docs/vi/packages/next-intlayer/usePathname.md

@@ -0,0 +1,136 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Tài liệu về Hook usePathname | next-intlayer
+description: Tìm hiểu cách sử dụng hook usePathname cho gói next-intlayer
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích usePathname"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Tích hợp Next.js: Tài liệu Hook `usePathname`
+
+Hook `usePathname` trả về đường dẫn (pathname) Next.js hiện tại đã loại bỏ phân đoạn vùng miền (locale segment). Điều này rất hữu ích để xây dựng tính năng điều hướng nhận thức vùng miền (locale-aware) — ví dụ: để xác định xem mục điều hướng nào đang hoạt động — mà không cần phải loại bỏ tiền tố locale theo cách thủ công.
+
+## Nhập `usePathname` trong Next.js
+
+```typescript
+import { usePathname } from "next-intlayer";
+```
+
+## Tổng quan
+
+`usePathname` bọc hàm `usePathname()` tích hợp của Next.js từ `next/navigation`, bổ sung thêm bất kỳ tham số tìm kiếm (search params) nào và loại bỏ tiền tố vùng miền thông qua `getPathWithoutLocale`. Nó kích hoạt một quá trình render lại mỗi khi có điều hướng ở phía máy khách. Hook này chỉ có sẵn bên trong Client Components (yêu cầu `"use client"`).
+
+## Cách sử dụng
+
+```tsx fileName="src/components/NavItem.tsx" codeFormat={["typescript", "esm"]}
+"use client";
+
+import type { FC } from "react";
+import { usePathname } from "next-intlayer";
+
+type NavItemProps = {
+  href: string;
+  label: string;
+};
+
+const NavItem: FC<NavItemProps> = ({ href, label }) => {
+  const pathname = usePathname();
+  const isActive = pathname === href;
+
+  return (
+    <a href={href} aria-current={isActive ? "page" : undefined}>
+      {label}
+    </a>
+  );
+};
+
+export default NavItem;
+```
+
+## Giá trị trả về
+
+| Kiểu     | Mô tả                                                                                                                 |
+| -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `string` | Tên đường dẫn hiện tại đã loại bỏ tiền tố locale và loại bỏ các tham số truy vấn (query params) liên quan đến locale. |
+
+## Hành vi
+
+- **Xóa Locale**: Xóa phân đoạn locale ban đầu (ví dụ: `/vi/dashboard` → `/dashboard`).
+- **Xóa Search Param**: Đồng thời loại bỏ tham số truy vấn `?locale=...` khi sử dụng chế độ định tuyến dựa trên tham số tìm kiếm.
+- **Tính phản ứng (Reactive)**: Cập nhật tự động trên mọi lần điều hướng phía máy khách thông qua Next.js App Router.
+- **An toàn với SSR**: Trả về đường dẫn từ máy chủ trong lần render đầu tiên, sau đó đồng bộ hóa tham số tìm kiếm trên máy khách.
+
+## So sánh với `useLocale`
+
+Hàm `useLocale` của `next-intlayer` đã tiết lộ `pathWithoutLocale` dưới dạng một phần của giá trị trả về của nó. Bạn có thể sử dụng `usePathname` khi bạn chỉ cần lấy đường dẫn và không cần chức năng chuyển đổi locale.
+
+```tsx codeFormat={["typescript", "esm"]}
+// Khi bạn cần cả trạng thái locale và đường dẫn:
+import { useLocale } from "next-intlayer";
+const { locale, pathWithoutLocale } = useLocale();
+
+// Khi bạn chỉ cần lấy đường dẫn:
+import { usePathname } from "next-intlayer";
+const pathname = usePathname();
+```
+
+## Ví dụ
+
+```tsx fileName="src/components/Sidebar.tsx" codeFormat={["typescript", "esm"]}
+"use client";
+
+import type { FC } from "react";
+import { usePathname } from "next-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "Bảng điều khiển" },
+  { href: "/settings", label: "Cài đặt" },
+];
+
+const Sidebar: FC = () => {
+  const pathname = usePathname();
+
+  return (
+    <nav>
+      {links.map(({ href, label }) => (
+        <a
+          key={href}
+          href={href}
+          style={{ fontWeight: pathname === href ? "bold" : "normal" }}
+        >
+          {label}
+        </a>
+      ))}
+    </nav>
+  );
+};
+
+export default Sidebar;
+```
+
+## Liên kết liên quan
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/next-intlayer/useLocale.md) — locale hiện tại + bộ chuyển đổi locale (cũng phơi bày `pathWithoutLocale`)
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPathWithoutLocale.md) — tiện ích cơ bản được sử dụng bởi hook này

package/docs/vi/packages/preact-intlayer/exports.md

@@ -14,6 +14,9 @@ slugs:
   - preact-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích usePathname"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Hợp nhất tài liệu cho tất cả các export"
@@ -40,12 +43,13 @@ npm install preact-intlayer
 
 ### Hooks
 
-| Hook            | Mô tả                                                                                                   | Tài liệu liên quan                                                                                     |
-| --------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `useIntlayer`   | Dựa trên `useDictionary`, nhưng chèn một phiên bản tối ưu hóa của từ điển từ khai báo được sinh ra.     | -                                                                                                      |
-| `useDictionary` | Xử lý các đối tượng có dạng từ điển (key, content). Nó xử lý các bản dịch `t()`, các enumerations, v.v. | -                                                                                                      |
-| `useLocale`     | Trả về locale hiện tại và một hàm để thiết lập nó.                                                      | -                                                                                                      |
-| `t`             | Lấy nội dung dựa trên locale hiện tại.                                                                  | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dictionary/translation.md) |
+| Hook            | Mô tả                                                                                                                                | Tài liệu liên quan                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`   | Dựa trên `useDictionary`, nhưng chèn một phiên bản tối ưu hóa của từ điển từ khai báo được sinh ra.                                  | -                                                                                                                    |
+| `useDictionary` | Xử lý các đối tượng có dạng từ điển (key, content). Nó xử lý các bản dịch `t()`, các enumerations, v.v.                              | -                                                                                                                    |
+| `useLocale`     | Trả về locale hiện tại và một hàm để thiết lập nó.                                                                                   | -                                                                                                                    |
+| `usePathname`   | Hook trả về đường dẫn hiện tại (pathname) với phần locale đã bị loại bỏ. Phản hồi tự động với điều hướng trình duyệt qua `popstate`. | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/preact-intlayer/usePathname.md) |
+| `t`             | Lấy nội dung dựa trên locale hiện tại.                                                                                               | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dictionary/translation.md)               |
 
 ### Thành phần
 

package/docs/vi/packages/preact-intlayer/usePathname.md

@@ -0,0 +1,117 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: Tài liệu về usePathname Hook | preact-intlayer
+description: Xem cách sử dụng usePathname hook cho gói preact-intlayer
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Quốc tế hóa
+  - Tài liệu
+  - Preact
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - preact-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Thêm tiện ích usePathname"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Khởi tạo lịch sử"
+author: aymericzip
+---
+
+# Tích hợp Preact: Tài liệu về `usePathname` Hook
+
+`usePathname` hook trả về pathname (đường dẫn) trình duyệt hiện tại với phân đoạn locale đã được loại bỏ. Điều này rất hữu ích để xây dựng các điều hướng nhận biết locale — ví dụ: xác định mục điều hướng nào đang hoạt động — mà không cần phải loại bỏ thủ công tiền tố locale.
+
+## Nhập `usePathname` trong Preact
+
+```typescript
+import { usePathname } from "preact-intlayer";
+```
+
+## Tổng quan
+
+`usePathname` đọc `window.location.pathname`, loại bỏ tiền tố locale thông qua `getPathWithoutLocale`, và kết xuất lại (re-renders) component bất cứ khi nào trình duyệt kích hoạt sự kiện `popstate` (điều hướng quay lại/tiến tới). Trong quá trình Server-Side Rendering (SSR), nó sẽ trả về một chuỗi rỗng.
+
+## Cách sử dụng
+
+```tsx fileName="src/components/NavItem.tsx"
+import type { FunctionComponent } from "preact";
+import { usePathname } from "preact-intlayer";
+
+type NavItemProps = {
+  href: string;
+  label: string;
+};
+
+const NavItem: FunctionComponent<NavItemProps> = ({ href, label }) => {
+  const pathname = usePathname();
+  const isActive = pathname === href;
+
+  return (
+    <a href={href} aria-current={isActive ? "page" : undefined}>
+      {label}
+    </a>
+  );
+};
+
+export default NavItem;
+```
+
+## Giá trị trả về
+
+| Kiểu dữ liệu | Mô tả                                                                                                     |
+| ------------ | --------------------------------------------------------------------------------------------------------- |
+| `string`     | Pathname hiện tại không có tiền tố locale. Trả về chuỗi rỗng trong quá trình Server-Side Rendering (SSR). |
+
+## Hành vi
+
+- **Loại bỏ locale (Locale stripping)**: Xóa phân đoạn locale ở đầu URL (ví dụ: `/vi/dashboard` → `/dashboard`).
+- **Phản ứng tự động (Reactive)**: Cập nhật tự động dựa trên các sự kiện `popstate` (khi điều hướng tiến / lùi trên trình duyệt).
+- **An toàn với SSR (SSR-safe)**: Trả về `""` khi `window` không có sẵn.
+- **Dọn dẹp (Cleanup)**: Trình lắng nghe `popstate` được loại bỏ tự động khi component bị ngắt kết nối (unmount).
+
+## Ví dụ
+
+```tsx fileName="src/components/Sidebar.tsx"
+import type { FunctionComponent } from "preact";
+import { usePathname } from "preact-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "Bảng điều khiển" },
+  { href: "/settings", label: "Cài đặt" },
+];
+
+const Sidebar: FunctionComponent = () => {
+  const pathname = usePathname();
+
+  return (
+    <nav>
+      {links.map(({ href, label }) => (
+        <a
+          key={href}
+          href={href}
+          style={{ fontWeight: pathname === href ? "bold" : "normal" }}
+        >
+          {label}
+        </a>
+      ))}
+    </nav>
+  );
+};
+
+export default Sidebar;
+```
+
+## Các mục liên quan
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/preact-intlayer/exports.md) — locale hiện tại + bộ chuyển đổi locale
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/intlayer/getPathWithoutLocale.md) — tiện ích nền tảng được sử dụng bởi hook này