Bộ định dạng Intlayer

Mục lục

Tổng quan

Intlayer cung cấp một bộ helper nhẹ xây dựng trên các API Intl gốc, cùng với một wrapper Intl được lưu trong bộ nhớ đệm để tránh việc tạo lại các bộ định dạng nặng nhiều lần. Các tiện ích này hoàn toàn nhận biết locale và có thể được sử dụng từ package chính intlayer.

Import

import {
  Intl,
  number,
  percentage,
  currency,
  date,
  relativeTime,
  units,
  compact,
  list,
  getLocaleName,
  getLocaleLang,
  getLocaleFromPath,
  getPathWithoutLocale,
  getLocalizedUrl,
  getHTMLTextDir,
  getContent,
  getTranslation,
  getIntlayer,
} from "intlayer";

Nếu bạn sử dụng React, các hook cũng có sẵn; xem react-intlayer/format.

Intl được lưu trong bộ nhớ đệm

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.

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ụ:

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"

// 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"

// Sắp xếp theo thứ tự
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"

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:

Intl.DisplayNames

Dùng để lấy tên địa phương hóa của ngôn ngữ, vùng, tiền tệ và bảng chữ cái:

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

Dùng để so sánh và sắp xếp chuỗi theo ngữ cảnh địa phương:

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

Dùng để xác định các dạng số nhiều trong các locale khác nhau:

import { Intl } from "intlayer";

const pluralRules = new Intl.PluralRules("ar");
pluralRules.select(0); // "zero" // số không
pluralRules.select(1); // "one" // số một
pluralRules.select(2); // "two" // số hai
pluralRules.select(3); // "few" // số ít
pluralRules.select(11); // "many" // số nhiều

Tiện ích Locale

getLocaleName(displayLocale, targetLocale?)

Lấy tên địa phương hóa của một locale trong một locale khác:

import { getLocaleName } from "intlayer";

getLocaleName("fr", "en"); // "French" // tiếng Pháp
getLocaleName("en", "fr"); // "anglais" // tiếng Anh
getLocaleName("de", "es"); // "alemán" // tiếng Đức

• displayLocale: Locale cần lấy tên
• targetLocale: Locale để hiển thị tên (mặc định là displayLocale)

getLocaleLang(locale?)

Trích xuất mã ngôn ngữ từ một chuỗi locale:

import { getLocaleLang } from "intlayer";

getLocaleLang("en-US"); // "en"
getLocaleLang("fr-CA"); // "fr"
getLocaleLang("de"); // "de"

• locale: Locale để trích xuất ngôn ngữ (mặc định là locale hiện tại)

getLocaleFromPath(inputUrl)

Trích xuất phần locale từ một URL hoặc pathname:

import { getLocaleFromPath } from "intlayer";

getLocaleFromPath("/en/dashboard"); // "en"
getLocaleFromPath("/fr/dashboard"); // "fr"
getLocaleFromPath("/dashboard"); // "en" (locale mặc định)
getLocaleFromPath("https://example.com/es/about"); // "es"

• inputUrl: Chuỗi URL đầy đủ hoặc đường dẫn cần xử lý
• returns: Locale được phát hiện hoặc locale mặc định nếu không tìm thấy locale nào

getPathWithoutLocale(inputUrl, locales?)

Loại bỏ phần locale khỏi URL hoặc đường dẫn:

import { getPathWithoutLocale } from "intlayer";

getPathWithoutLocale("/en/dashboard"); // "/dashboard"
getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
getPathWithoutLocale("https://example.com/en/about"); // "https://example.com/about"

• inputUrl: Chuỗi URL đầy đủ hoặc đường dẫn cần xử lý
• locales: Mảng tùy chọn các locale được hỗ trợ (mặc định là các locale đã cấu hình)
• returns: URL không có phần locale

getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)

Tạo URL có địa phương hóa cho locale hiện tại:

import { getLocalizedUrl } from "intlayer";

getLocalizedUrl("/about", "fr", ["en", "fr"], "en", false); // "/fr/about"
getLocalizedUrl("/about", "en", ["en", "fr"], "en", false); // "/about"
getLocalizedUrl("https://example.com/about", "fr", ["en", "fr"], "en", true); // "https://example.com/fr/about"

• url: URL gốc cần địa phương hóa
• currentLocale: Locale hiện tại
• locales: Mảng tùy chọn các locale được hỗ trợ (mặc định là các locale đã cấu hình)
• defaultLocale: Locale mặc định tùy chọn (mặc định là locale mặc định đã cấu hình)
• prefixDefault: Có thêm tiền tố locale mặc định hay không (mặc định theo giá trị đã cấu hình)

getHTMLTextDir(locale?)

Trả về hướng văn bản cho một locale:

import { getHTMLTextDir } from "intlayer";

getHTMLTextDir("en-US"); // "ltr"
getHTMLTextDir("ar"); // "rtl"
getHTMLTextDir("he"); // "rtl"

• locale: Locale để lấy hướng văn bản (mặc định là locale hiện tại)
• returns: "ltr", "rtl", hoặc "auto"

Tiện ích Xử lý Nội dung

getContent(node, nodeProps, locale?)

Chuyển đổi một node nội dung với tất cả các plugin có sẵn (dịch thuật, đánh số, chèn, v.v.):

import { getContent } from "intlayer";

const content = getContent(
  contentNode,
  { dictionaryKey: "common", dictionaryPath: "/path/to/dict" },
  "fr"
);

• node: Node nội dung cần chuyển đổi
• nodeProps: Thuộc tính cho ngữ cảnh chuyển đổi
• locale: Locale tùy chọn (mặc định là locale mặc định đã cấu hình)

getTranslation(languageContent, locale?, fallback?)

Trích xuất nội dung cho một locale cụ thể từ một đối tượng nội dung ngôn ngữ:

import { getTranslation } from "intlayer";

const content = getTranslation(
  {
    en: "Hello",
    fr: "Bonjour",
    de: "Hallo",
  },
  "fr",
  true
); // "Bonjour"

• languageContent: Đối tượng ánh xạ các locale tới nội dung
• 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)

getIntlayer(dictionaryKey, locale?, plugins?)

Lấy và chuyển đổi nội dung từ một từ điển theo key:

import { getIntlayer } from "intlayer";

const content = getIntlayer("common", "fr");
const nestedContent = getIntlayer("common", "fr", customPlugins);

• dictionaryKey: Khóa của từ điển để truy xuất
• 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ụ:

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ụ:

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ụ:

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ụ:

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ụ:

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ụ:

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ụ:

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ụ:

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ụ:

// 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:

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):

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:

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