@intlayer/docs 9.1.3 → 9.3.0

package/docs/vi/formatters.md

@@ -137,45 +137,40 @@ const MyComponent = () => {
 };
 ```
 
-## Intl được lưu trong bộ nhớ đệm
+### Hook `useIntl`
 
-`Intl` được xuất ra là một wrapper mỏng, được lưu trong bộ nhớ đệm quanh `Intl` toàn cục. Nó ghi nhớ các thể hiện của `NumberFormat`, `DateTimeFormat`, `RelativeTimeFormat`, `ListFormat`, `DisplayNames`, `Collator`, và `PluralRules`, giúp tránh việc xây dựng lại cùng một bộ định dạng nhiều lần.
+Hook `useIntl` cung cấp quyền truy cập trực tiếp vào một đối tượng `Intl` được ràng buộc với locale. Điều này hữu ích khi bạn cần toàn bộ API `Intl` (ví dụ: `DisplayNames`, `Collator`, `PluralRules`) với việc tiêm locale tự động.
 
-Vì việc tạo bộ định dạng khá tốn kém, việc lưu trong bộ nhớ đệm này cải thiện hiệu suất mà không làm thay đổi hành vi. Wrapper này cung cấp cùng API như `Intl` gốc, nên cách sử dụng hoàn toàn giống nhau.
-
-- Việc lưu trong bộ nhớ đệm là theo từng tiến trình và hoàn toàn minh bạch với người gọi.
-
-> Nếu `Intl.DisplayNames` không có sẵn trong môi trường, một cảnh báo chỉ dành cho nhà phát triển sẽ được in ra một lần (cân nhắc sử dụng polyfill).
-
-Ví dụ:
+```tsx
+import { useIntl } from "react-intlayer/format";
 
-```ts
-import { Intl } from "intlayer";
+const MyComponent = () => {
+  const intl = useIntl(); // sử dụng locale từ context
 
-// Định dạng số
-const numberFormat = new Intl.NumberFormat("en-GB", {
-  style: "currency",
-  currency: "GBP",
-});
-numberFormat.format(1234.5); // "£1,234.50"
+  // API Intl tiêu chuẩn, nhưng locale được tiêm tự động khi undefined
+  const formatted = new intl.NumberFormat(undefined, {
+    style: "currency",
+    currency: "USD",
+  }).format(123.45);
 
-// Tên hiển thị cho ngôn ngữ, vùng, v.v.
-const displayNames = new Intl.DisplayNames("fr", { type: "language" });
-displayNames.of("en"); // "anglais"
+  // Bạn vẫn có thể ghi đè locale nếu cần
+  const date = new intl.DateTimeFormat("fr-FR").format(new Date());
 
-// Sắp xếp theo thứ tự
-const collator = new Intl.Collator("fr", { sensitivity: "base" });
-collator.compare("é", "e"); // 0 (bằng nhau)
+  // Truy cập các tính năng Intl khác
+  const displayNames = new intl.DisplayNames(undefined, { type: "language" });
+  const languageName = displayNames.of("fr"); // "French" (hoặc được bản địa hóa)
 
-// Quy tắc số nhiều
-const pluralRules = new Intl.PluralRules("fr");
-pluralRules.select(1); // "one"
-pluralRules.select(2); // "other"
+  return (
+    <div>
+      <p>{formatted}</p>
+      <p>{date}</p>
+      <p>{languageName}</p>
+    </div>
+  );
+};
 ```
 
-## Tiện ích Intl bổ sung
-
-Ngoài các trình trợ giúp định dạng, bạn cũng có thể sử dụng trực tiếp wrapper Intl đã được lưu trong bộ nhớ đệm cho các tính năng Intl khác:
+## Vue Formatters
 
 ### `Intl.DisplayNames`
 
@@ -281,6 +276,189 @@ pluralRules.select(3); // "few" // số ít
 pluralRules.select(11); // "many" // số nhiều
 ```
 
+### Các Hàm Định Dạng
+
+#### `number(value, options?)`
+
+Định dạng một giá trị số sử dụng nhóm và thập phân nhận biết địa phương.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+```ts
+number(123456.789); // "123,456.789" (in en-US)
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+#### `percentage(value, options?)`
+
+Định dạng một số dưới dạng chuỗi phần trăm. Các giá trị lớn hơn 1 được chuẩn hóa (ví dụ: `25` → `25%`, `0.25` → `25%`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+```ts
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
+```
+
+#### `currency(value, options?)`
+
+Định dạng một giá trị dưới dạng tiền tệ được bản địa hóa. Mặc định là `USD`.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Common: `currency`, `currencyDisplay` (`"symbol" | "code" | "name"`)
+
+```ts
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
+```
+
+#### `date(date, optionsOrPreset?)`
+
+Định dạng một giá trị ngày/giờ.
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` hoặc preset: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+```ts
+date(new Date(), "short"); // ví dụ: "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+#### `relativeTime(from, to?, options?)`
+
+Định dạng thời gian tương đối giữa hai thời điểm.
+
+- **from**: `Date | string | number`
+- **to**: `Date | string | number` (mặc định là `new Date()`)
+- **options**: `{ locale?, unit?, numeric?, style? }`
+
+```ts
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+```
+
+#### `units(value, options?)`
+
+Định dạng một giá trị số với một đơn vị.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Common: `unit` (e.g., `"kilometer"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
+
+```ts
+units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"
+```
+
+#### `compact(value, options?)`
+
+Định dạng một số sử dụng ký hiệu compact.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+```ts
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
+```
+
+#### `list(values, options?)`
+
+Định dạng một mảng thành một chuỗi danh sách đã được bản địa hóa.
+
+- **values**: `(string | number)[]`
+- **options**: `Intl.ListFormatOptions & { locale?: LocalesValues }`
+  - Common: `type` (`"conjunction" | "disjunction" | "unit"`), `style` (`"long" | "short" | "narrow"`)
+
+```ts
+list(["apple", "banana", "orange"]); // "apple, banana, and orange"
+list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"
+```
+
+## Cached Intl
+
+`Intl` được xuất từ `intlayer` là một wrapper được lưu trong bộ nhớ cache xung quanh `Intl` toàn cục. Nó memoizes các instance formatter (`NumberFormat`, `DateTimeFormat`, v.v.) để tránh việc xây dựng lại chúng liên tục, cải thiện hiệu suất.
+
+```ts
+import { Intl } from "intlayer";
+
+// Định dạng số
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+
+// Hiển thị tên cho các ngôn ngữ, khu vực, v.v.
+const displayNames = new Intl.DisplayNames("fr", { type: "language" });
+displayNames.of("en"); // "anglais"
+
+// Collation để sắp xếp
+const collator = new Intl.Collator("fr", { sensitivity: "base" });
+collator.compare("é", "e"); // 0 (bằng nhau)
+
+// Quy tắc số nhiều
+const pluralRules = new Intl.PluralRules("fr");
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "other"
+```
+
+### Các Tính Năng Intl Bổ Sung
+
+#### `Intl.DisplayNames`
+
+Để có được tên được bản địa hóa của các ngôn ngữ, khu vực, tiền tệ và chữ viết:
+
+```ts
+import { Intl } from "intlayer";
+
+const languageNames = new Intl.DisplayNames("en", { type: "language" });
+languageNames.of("fr"); // "French"
+
+const regionNames = new Intl.DisplayNames("fr", { type: "region" });
+regionNames.of("US"); // "États-Unis"
+```
+
+#### `Intl.Collator`
+
+Để so sánh và sắp xếp chuỗi ký tự theo locale:
+
+```ts
+import { Intl } from "intlayer";
+
+const collator = new Intl.Collator("de", {
+  sensitivity: "base",
+  numeric: true,
+});
+
+const words = ["äpfel", "zebra", "100", "20"];
+words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]
+```
+
+#### `Intl.PluralRules`
+
+Để xác định các dạng số nhiều trong các locale khác nhau:
+
+```ts
+import { Intl } from "intlayer";
+
+const pluralRules = new Intl.PluralRules("ar");
+pluralRules.select(0); // "zero"
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "two"
+pluralRules.select(3); // "few"
+pluralRules.select(11); // "many"
+```
+
 ## Tiện ích Locale
 
 ### `getLocaleName(displayLocale, targetLocale?)`
@@ -419,8 +597,6 @@ const content = getTranslation(
 - **locale**: Locale mục tiêu (mặc định là locale cấu hình sẵn)
 - **fallback**: Có fallback về locale mặc định hay không (mặc định là true)
 
-### Các tính năng Intl bổ sung
-
 ### `getIntlayer(dictionaryKey, locale?, plugins?)`
 
 Lấy và chuyển đổi nội dung từ một từ điển theo key:
@@ -436,283 +612,6 @@ const nestedContent = getIntlayer("common", "fr", customPlugins);
 - **locale**: Locale tùy chọn (mặc định là locale cấu hình sẵn)
 - **plugins**: Mảng tùy chọn các plugin chuyển đổi tùy chỉnh
 
-## Bộ định dạng
-
-Tất cả các helper dưới đây được xuất khẩu từ `intlayer`.
-
-### `number(value, options?)`
-
-Định dạng một giá trị số sử dụng nhóm và phần thập phân theo locale.
-
-- **value**: `number | string`
-- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
-
-Ví dụ:
-
-```ts
-import { number } from "intlayer";
-
-number(123456.789); // "123,456.789" (trong en-US)
-number("1000000", { locale: "fr" }); // "1 000 000"
-number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
-```
-
-### `percentage(value, options?)`
-
-Định dạng một số thành chuỗi phần trăm.
-
-Hành vi: các giá trị lớn hơn 1 được hiểu là phần trăm nguyên và được chuẩn hóa (ví dụ, `25` → `25%`, `0.25` → `25%`).
-
-- **value**: `number | string`
-- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
-
-Ví dụ:
-
-```ts
-import { percentage } from "intlayer";
-
-percentage(0.25); // "25%"
-percentage(25); // "25%"
-percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
-```
-
-### `currency(value, options?)`
-
-Định dạng một giá trị dưới dạng tiền tệ theo locale. Mặc định là `USD` với hai chữ số thập phân.
-
-- **value**: `number | string`
-- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
-  - Các trường phổ biến: `currency` (ví dụ, `"EUR"`), `currencyDisplay` (`"symbol" | "code" | "name"`)
-
-Ví dụ:
-
-```ts
-import { currency } from "intlayer";
-
-currency(1234.5, { currency: "EUR" }); // "€1,234.50"
-currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
-```
-
-### `date(date, optionsOrPreset?)`
-
-Định dạng giá trị ngày/giờ với `Intl.DateTimeFormat`.
-
-- **date**: `Date | string | number`
-- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` hoặc một trong các preset:
-  - Preset: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
-
-Ví dụ:
-
-```ts
-import { date } from "intlayer";
-
-date(new Date(), "short"); // ví dụ, "08/02/25, 14:30"
-date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
-```
-
-### `relativeTime(from, to = new Date(), options?)`
-
-Định dạng thời gian tương đối giữa hai thời điểm với `Intl.RelativeTimeFormat`.
-
-- Truyền "now" làm đối số đầu tiên và mục tiêu làm đối số thứ hai để có cách diễn đạt tự nhiên.
-- **from**: `Date | string | number`
-- **to**: `Date | string | number` (mặc định là `new Date()`)
-- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
-  - Mặc định `unit` là `"second"`.
-
-Ví dụ:
-
-```ts
-import { relativeTime } from "intlayer";
-
-const now = new Date();
-const in3Days = new Date(now.getTime() + 3 * 864e5);
-relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
-
-const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
-relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
-```
-
-### `units(value, options?)`
-
-Định dạng một giá trị số thành chuỗi đơn vị được địa phương hóa sử dụng `Intl.NumberFormat` với `style: 'unit'`.
-
-- **value**: `number | string`
-- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
-  - Các trường phổ biến: `unit` (ví dụ, `"kilometer"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
-  - Mặc định: `unit: 'day'`, `unitDisplay: 'short'`, `useGrouping: false`
-
-Ví dụ:
-
-```ts
-import { units } from "intlayer";
-
-units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
-units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (phụ thuộc vào locale)
-```
-
-### `compact(value, options?)`
-
-Định dạng một số sử dụng ký hiệu rút gọn (ví dụ, `1.2K`, `1M`).
-
-- **value**: `number | string`
-- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }` (sử dụng `notation: 'compact'` bên trong)
-
-Ví dụ:
-
-```ts
-import { compact } from "intlayer";
-
-compact(1200); // "1.2K"
-compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
-```
-
-### `list(values, options?)`
-
-Định dạng một mảng các giá trị thành chuỗi danh sách được địa phương hóa sử dụng `Intl.ListFormat`.
-
-- **values**: `(string | number)[]`
-- **options**: `Intl.ListFormatOptions & { locale?: LocalesValues }`
-  - Các trường phổ biến: `type` (`"conjunction" | "disjunction" | "unit"`), `style` (`"long" | "short" | "narrow"`)
-  - Mặc định: `type: 'conjunction'`, `style: 'long'`
-
-Ví dụ:
-
-```ts
-import { list } from "intlayer";
-
-list(["apple", "banana", "orange"]); // "apple, banana, and orange"
-list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"
-list([1, 2, 3], { type: "unit" }); // "1, 2, 3"
-```
-
-## Ghi chú
-
-- Tất cả các helper chấp nhận đầu vào kiểu `string`; chúng sẽ được ép kiểu nội bộ thành số hoặc ngày tháng.
-- Locale mặc định là `internationalization.defaultLocale` mà bạn đã cấu hình nếu không được cung cấp.
-- Các tiện ích này là các wrapper mỏng; để định dạng nâng cao, hãy truyền các tùy chọn tiêu chuẩn của `Intl`.
-
-## Điểm vào và tái xuất (`@index.ts`)
-
-Các bộ định dạng nằm trong package core và được tái xuất từ các package cấp cao hơn để giữ cho việc import thuận tiện trên các runtime khác nhau:
-
-Ví dụ:
-
-```ts
-// Mã ứng dụng (khuyến nghị)
-import {
-  number,
-  currency,
-  date,
-  relativeTime,
-  units,
-  compact,
-  list,
-  Intl,
-  getLocaleName,
-  getLocaleLang,
-  getLocaleFromPath,
-  getPathWithoutLocale,
-  getLocalizedUrl,
-  getHTMLTextDir,
-  getContent,
-  getTranslation,
-  getIntlayer,
-} from "intlayer";
-```
-
-### React
-
-Các thành phần client:
-
-```tsx
-import {
-  useNumber,
-  useCurrency,
-  useDate,
-  usePercentage,
-  useCompact,
-  useList,
-  useRelativeTime,
-  useUnit,
-} from "react-intlayer/format";
-// hoặc trong các ứng dụng Preact
-// "preact-intlayer/format";
-// hoặc trong các ứng dụng Next.js
-// "next-intlayer/client/format";
-
-const MyComponent = () => {
-  const number = useNumber();
-  const currency = useCurrency();
-  const date = useDate();
-  const percentage = usePercentage();
-  const compact = useCompact();
-  const list = useList();
-  const relativeTime = useRelativeTime();
-  const unit = useUnit();
-
-  return (
-    <div>
-      <p>{number(123456.789)}</p>
-      <p>{currency(1234.5, { currency: "EUR" })}</p>
-      <p>{date(new Date(), "short")}</p>
-      <p>{percentage(0.25)}</p>
-      <p>{compact(1200)}</p>
-      <p>{list(["apple", "banana", "orange"])}</p>
-      <p>{relativeTime(new Date(), new Date() + 1000)}</p>
-      <p>{unit(123456.789, { unit: "kilometer" })}</p>
-    </div>
-  );
-};
-```
-
-Các thành phần server (hoặc runtime React Server):
-
-```ts
-import {
-  useNumber,
-  useCurrency,
-  useDate,
-  usePercentage,
-  useCompact,
-  useList,
-  useRelativeTime,
-  useUnit,
-} from "react-intlayer/server/format";
-// hoặc trong các ứng dụng Next.js
-import {
-  useNumber,
-  useCurrency,
-  useDate,
-  usePercentage,
-  useCompact,
-  useList,
-  useRelativeTime,
-  useUnit,
-} from "next-intlayer/server/format";
-```
-
-> Các hook đó sẽ lấy locale từ `IntlayerProvider` hoặc `IntlayerServerProvider`
-
-### Vue
-
-Các component phía client:
-
-```ts
-import {
-  useNumber,
-  useCurrency,
-  useDate,
-  usePercentage,
-  useCompact,
-  useList,
-  useRelativeTime,
-  useUnit,
-} from "vue-intlayer/format";
-```
-
-> Các composable đó sẽ lấy locale từ `IntlayerProvider` được inject vào
-
 ## Ghi chú
 
 - Tất cả các helper chấp nhận `string` inputs; chúng được chuyển đổi nội bộ thành numbers hoặc dates.