Penulis:
    Dibuat:2024-08-13Terakhir diperbarui:2025-10-14

    Formatters Intlayer

    Daftar Isi

    Ikhtisar

    Intlayer menyediakan serangkaian pembantu ringan yang dibangun di atas API Intl asli, ditambah pembungkus Intl yang di-cache untuk menghindari pembuatan formatter berat berulang kali. Utilitas ini sepenuhnya sadar lokal dan dapat digunakan dari paket utama intlayer.

    React Formatters

    Impor

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

    Jika Anda menggunakan React, hooks juga tersedia; lihat react-intlayer/format.

    Hook yang Tersedia

    Semua hook secara otomatis menggunakan locale dari IntlayerProvider atau IntlayerServerProvider.

    Hook Description Example Output
    useNumber() Format angka dengan pengelompokan "123,456.789"
    useCurrency() Format nilai mata uang "€1,234.50"
    usePercentage() Format persentase "25%"
    useDate() Format tanggal dan waktu "Aug 2, 2025"
    useRelativeTime() Format waktu relatif "in 3 days"
    useUnit() Format nilai dengan satuan "5 kilometers"
    useCompact() Format angka dalam notasi kompak "1.2K"
    useList() Format array sebagai daftar "apple, banana, and orange"
    useIntl() Dapatkan objek Intl terikat locale Akses penuh API Intl

    Contoh Lengkap

    tsx
    import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "react-intlayer/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(Date.now() + 86400000))}</p>      <p>{unit(5, { unit: "kilometer" })}</p>    </div>  );};

    Hook useIntl

    Hook useIntl menyediakan akses langsung ke objek Intl yang terikat pada locale. Ini berguna ketika Anda memerlukan API Intl lengkap (misalnya, DisplayNames, Collator, PluralRules) dengan injeksi locale otomatis.

    tsx
    import { useIntl } from "react-intlayer/format";const MyComponent = () => {  const intl = useIntl(); // menggunakan locale konteks  // API Intl standar, tetapi locale disuntikkan secara otomatis ketika undefined  const formatted = new intl.NumberFormat(undefined, {    style: "currency",    currency: "USD",  }).format(123.45);  // Anda masih dapat menimpa locale jika diperlukan  const date = new intl.DateTimeFormat("fr-FR").format(new Date());  // Akses fitur Intl lainnya  const displayNames = new intl.DisplayNames(undefined, { type: "language" });  const languageName = displayNames.of("fr"); // "French" (atau terlokalisasi)  return (    <div>      <p>{formatted}</p>      <p>{date}</p>      <p>{languageName}</p>    </div>  );};

    Vue Formatters

    Intl.DisplayNames

    Untuk nama yang dilokalkan dari bahasa, wilayah, mata uang, dan skrip:

    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"

    Composables yang Tersedia

    Semua composables mengembalikan computed refs yang secara otomatis menggunakan locale dari IntlayerProvider yang diinjeksi.

    Composable Deskripsi Contoh Output
    useNumber() Format angka dengan pengelompokan "123,456.789"
    useCurrency() Format nilai mata uang "€1,234.50"
    usePercentage() Format persentase "25%"
    useDate() Format tanggal dan waktu "Aug 2, 2025"
    useRelativeTime() Format waktu relatif "in 3 days"
    useUnit() Format nilai dengan unit "5 kilometers"
    useCompact() Format angka dalam notasi kompak "1.2K"
    useList() Format array sebagai daftar "apple, banana, and orange"
    useIntl() Dapatkan objek Intl terikat locale Akses API Intl lengkap

    Contoh Lengkap

    vue
    <script setup>import {  useNumber,  useCurrency,  useDate,  usePercentage,  useCompact,  useList,  useRelativeTime,  useUnit,} from "vue-intlayer/format";const number = useNumber();const currency = useCurrency();const date = useDate();const percentage = usePercentage();const compact = useCompact();const list = useList();const relativeTime = useRelativeTime();const unit = useUnit();</script><template>  <div>    <p>{{ number.value(123456.789) }}</p>    <p>{{ currency.value(1234.5, { currency: "EUR" }) }}</p>    <p>{{ date.value(new Date(), "short") }}</p>    <p>{{ percentage.value(0.25) }}</p>    <p>{{ compact.value(1200) }}</p>    <p>{{ list.value(["apple", "banana", "orange"]) }}</p>    <p>{{ relativeTime.value(new Date(), new Date(Date.now() + 86400000)) }}</p>    <p>{{ unit.value(5, { unit: "kilometer" }) }}</p>  </div></template>

    Intl.Collator

    Untuk perbandingan dan pengurutan string yang sadar lokal:

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

    Vanilla JS / Node.js Formatters

    Untuk konteks non-framework, impor formatter langsung dari intlayer. Perhatikan bahwa Anda harus melewatkan locale secara manual.

    Intl.PluralRules

    Untuk menentukan bentuk jamak dalam berbagai locale:

    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"

    Fungsi Formatter

    number(value, options?)

    Memformat nilai numerik menggunakan pengelompokan dan desimal yang menyadari lokal.

    • 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?)

    Memformat angka sebagai string persentase. Nilai lebih besar dari 1 dinormalisasi (misalnya, 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?)

    Memformat nilai sebagai mata uang yang dilokalisasi. Default ke 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?)

    Memformat nilai tanggal/waktu.

    • date: Date | string | number
    • optionsOrPreset: Intl.DateTimeFormatOptions & { locale?: LocalesValues } atau preset: "short" | "long" | "dateOnly" | "timeOnly" | "full"
    ts
    date(new Date(), "short"); // misalnya, "08/02/25, 14:30"date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"

    relativeTime(from, to?, options?)

    Memformat waktu relatif antara dua momen.

    • from: Date | string | number
    • to: Date | string | number (default ke 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" }); // "dalam 3 hari"const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 jam yang lalu"

    units(value, options?)

    Memformat nilai numerik dengan unit.

    • 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?)

    Memformat angka menggunakan notasi kompak.

    • value: number | string
    • options: Intl.NumberFormatOptions & { locale?: LocalesValues }
    ts
    compact(1200); // "1.2K"compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"

    list(values, options?)

    Memformat array menjadi string list yang terlokalisasi.

    • 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 yang diekspor dari intlayer adalah wrapper yang di-cache di sekitar Intl global. Ini memoizes instance formatter (NumberFormat, DateTimeFormat, dll.) untuk menghindari pengulangan konstruksinya, meningkatkan performance.

    ts
    import { Intl } from "intlayer";// Pemformatan angkaconst numberFormat = new Intl.NumberFormat("en-GB", {  style: "currency",  currency: "GBP",});numberFormat.format(1234.5); // "£1,234.50"// Nama tampilan untuk bahasa, region, dll.const displayNames = new Intl.DisplayNames("fr", { type: "language" });displayNames.of("en"); // "anglais"// Collation untuk pengurutanconst collator = new Intl.Collator("fr", { sensitivity: "base" });collator.compare("é", "e"); // 0 (equal)// Aturan pluralconst pluralRules = new Intl.PluralRules("fr");pluralRules.select(1); // "one"pluralRules.select(2); // "other"

    Fitur Intl Tambahan

    Intl.DisplayNames

    Untuk nama-nama terlokalisasi dari bahasa, region, mata uang, dan skrip:

    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

    Untuk perbandingan dan pengurutan string yang peka terhadap 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

    Untuk menentukan bentuk plural dalam lokal yang berbeda:

    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"

    Utilitas Locale

    getLocaleName(displayLocale, targetLocale?)

    Mendapatkan nama yang dilokalkan dari sebuah locale dalam locale lain:

    ts
    import { getLocaleName } from "intlayer";getLocaleName("fr", "en"); // "French"getLocaleName("en", "fr"); // "anglais"getLocaleName("de", "es"); // "alemán"
    • displayLocale: Locale yang ingin didapatkan namanya
    • targetLocale: Locale untuk menampilkan nama (default-nya adalah displayLocale)

    getLocaleLang(locale?)

    Mengambil kode bahasa dari string locale:

    ts
    import { getLocaleLang } from "intlayer";getLocaleLang("en-US"); // "en"getLocaleLang("fr-CA"); // "fr"getLocaleLang("de"); // "de"
    • locale: Locale yang akan diambil bahasanya (default-nya adalah locale saat ini)

    getLocaleFromPath(inputUrl)

    Mengambil segmen locale dari URL atau pathname:

    ts
    import { getLocaleFromPath } from "intlayer";getLocaleFromPath("/en/dashboard"); // "en"getLocaleFromPath("/fr/dashboard"); // "fr"getLocaleFromPath("/dashboard"); // "en" (locale default)getLocaleFromPath("https://example.com/es/about"); // "es"
    • inputUrl: String URL lengkap atau pathname yang akan diproses
    • returns: Locale yang terdeteksi atau locale default jika tidak ditemukan locale

    getPathWithoutLocale(inputUrl, locales?)

    Menghapus segmen locale dari URL atau pathname:

    ts
    import { getPathWithoutLocale } from "intlayer";getPathWithoutLocale("/en/dashboard"); // "/dashboard"getPathWithoutLocale("/fr/dashboard"); // "/dashboard"getPathWithoutLocale("https://example.com/en/about"); // "https://example.com/about"
    • inputUrl: String URL lengkap atau pathname yang akan diproses
    • locales: Array opsional dari locale yang didukung (default-nya adalah locale yang dikonfigurasi)
    • returns: URL tanpa segmen locale

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

    Menghasilkan URL yang dilokalkan untuk locale saat ini:

    ts
    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 asli yang akan dilokalkan
    • currentLocale: Locale saat ini
    • locales: Array opsional dari locale yang didukung (default ke locale yang dikonfigurasi)
    • defaultLocale: Locale default opsional (default ke locale default yang dikonfigurasi)
    • prefixDefault: Apakah akan menambahkan prefix untuk locale default (default ke nilai yang dikonfigurasi)

    getHTMLTextDir(locale?)

    Mengembalikan arah teks untuk sebuah locale:

    ts
    import { getHTMLTextDir } from "intlayer";getHTMLTextDir("en-US"); // "ltr"getHTMLTextDir("ar"); // "rtl"getHTMLTextDir("he"); // "rtl"
    • locale: Locale untuk mendapatkan arah teks (default ke locale saat ini)
    • returns: "ltr", "rtl", atau "auto"

    Utilitas Penanganan Konten

    getContent(node, nodeProps, locale?)

    Mengubah node konten dengan semua plugin yang tersedia (terjemahan, enumerasi, penyisipan, dll.):

    ts
    import { getContent } from "intlayer";const content = getContent(  contentNode,  { dictionaryKey: "common", dictionaryPath: "/path/to/dict" },  "fr");
    • node: Node konten yang akan diubah
    • nodeProps: Properti untuk konteks transformasi
    • locale: Locale opsional (default ke locale default yang dikonfigurasi)

    getTranslation(languageContent, locale?, fallback?)

    Mengambil konten untuk locale tertentu dari objek konten bahasa:

    ts
    import { getTranslation } from "intlayer";const content = getTranslation(  {    en: "Hello",    fr: "Bonjour",    de: "Hallo",  },  "fr",  true); // "Bonjour"
    • languageContent: Objek yang memetakan locale ke konten
    • locale: Locale target (default ke locale default yang dikonfigurasi)
    • fallback: Apakah akan kembali ke locale default (default true)

    getIntlayer(dictionaryKey, locale?, plugins?)

    Mengambil dan mengubah konten dari kamus berdasarkan kunci:

    ts
    import { getIntlayer } from "intlayer";const content = getIntlayer("common", "fr");const nestedContent = getIntlayer("common", "fr", customPlugins);
    • dictionaryKey: Kunci dari kamus yang akan diambil
    • locale: Locale opsional (default ke locale default yang dikonfigurasi)
    • plugins: Array opsional dari plugin transformasi kustom

    Catatan

    • Semua helper menerima input string; secara internal akan dikonversi menjadi angka atau tanggal.
    • Locale default adalah internationalization.defaultLocale yang telah Anda konfigurasi jika tidak disediakan.
    • Utilitas ini adalah pembungkus tipis; untuk pemformatan lanjutan, gunakan opsi standar Intl.
    Mengapa Intlayer?