Penulis:
    Dibuat:2026-06-14Terakhir diperbarui:2026-06-29

    Intlayer v9 Baru - Apa yang baru?

    Selamat datang di Intlayer v9! Rilis besar ini menandai tonggak sejarah besar dalam menyederhanakan jalur migrasi ke Intlayer dengan Compat Adapter Packages untuk pustaka i18n utama (react-i18next, next-intl, vue-i18n, dll.) dan menambahkan dukungan untuk struktur konten yang kaya: Collections dan Variants.

    Daftar Isi

    Compat Adapter Packages

    Migrasi ke Intlayer dari pustaka i18n populer kini lebih mudah dari sebelumnya. Kami telah membuat lima paket kompatibilitas (compat packages) yang mengekspos API publik yang persis sama dengan pustaka i18n standar tetapi mendelegasikan semua pekerjaan penerjemahan ke Intlayer pada saat runtime.

    Mengekspos API Publik yang Sama dengan Strict Typing

    Dengan mengganti impor, Anda mendapatkan semua manfaat Intlayer (termasuk type safety pada saat compile-time terhadap dictionary Anda yang sebenarnya) dengan perubahan kode yang minimal:

    • @intlayer/i18next
    • @intlayer/react-i18next
    • @intlayer/next-intl
    • @intlayer/react-intl
    • @intlayer/next-i18next
    • @intlayer/vue-i18n
    • @intlayer/lingui

    Sebagai contoh, cukup ubah:

    ts
    import { useTranslation } from "react-i18next";

    menjadi:

    ts
    import { useTranslation } from "@intlayer/react-i18next";

    Key Anda sekarang akan bertipe ketat (strictly typed) terhadap dictionary Intlayer Anda, menawarkan auto-completion dot-path lengkap di IDE Anda!

    Plugin Alias Bundler (Vite, Next.js, Turbopack)

    Untuk memungkinkan migrasi tanpa menulis ulang semua pernyataan impor Anda secara manual, setiap paket compat adapter menyertakan plugin bundler kustom (Vite atau Next.js) di bawah subpath /plugin.

    Plugin ini secara otomatis menulis ulang impor yang ada (misalnya react-i18next atau next-intl) ke padanannya di @intlayer/* pada saat build time.

    Contoh Next.js (Webpack / Turbopack)

    Alih-alih withIntlayer, bungkus konfigurasi Next.js Anda dengan plugin kompatibilitas:

    next.config.ts
    import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

    Contoh Vite (React, Vue, Solid, Svelte)

    vite.config.ts
    import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

    Mutualized Runtime Resolver

    Semua compat adapter sekarang merutekan resolusi terjemahan melalui satu parser runtime yang sangat dioptimalkan: @intlayer/core/messageFormat.

    • Interpolate Message: Menyelesaikan {{var}} standar (whitespace & dot-path), argumen berformat ICU ({v, number, percent} dll.), dan templat {var} polos.
    • Message Node Resolver: Menyelesaikan node bersarang: insert(), plural() (aturan jamak CLDR), enu() (enumerasi), gender(), tag HTML, array, dan node fungsi yang dapat dipanggil (callable function nodes).
    • Tokenized Tag Parser: Mendukung tag XML/HTML inline dan tag bernomor (misalnya, <1>children</1>) untuk mendukung rendering rich-text secara langsung (out of the box).

    Spesifikasi Fitur: Collections & Variants

    Intlayer v9 berkembang melampaui objek key-value statis, memungkinkan dictionary untuk mendeklarasikan struktur tata letak dinamis yang sepenuhnya bertipe (fully typed) dari ujung ke ujung (end-to-end).

    1. Collections

    Definisikan daftar item terurut yang dikelola CMS (misalnya FAQ, produk, atau daftar blog):

    faq.1.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;
    faq.2.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

    Penggunaan:

    ts
    // Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

    2. Variants

    Sajikan pengujian A/B (A/B tests), header musiman, feature flags, atau landing page kustom:

    Varian string (misal, pengujian A/B)

    hero.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ id: "Selamat datang", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      id: "Belanja sekarang",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

    Penggunaan:

    ts
    const banner = useIntlayer("hero-banner", { variant: "black_friday" });

    Varian objek (misal, Dynamic Records)

    product.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    id: "prod_123",    category: "books",  },  content: {    title: t({ id: "Clean Code", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

    Penggunaan:

    ts
    // Memuat hanya item yang diminta secara dinamis (memerlukan Suspense)const product = useIntlayer("product-copy", {  variant: { id: "prod_123", category: "books" },});

    Vite Plugin: Bundled Compiler & Proxy

    Plugin Vite intlayer() sekarang menggabungkan compiler dan locale-routing proxy secara langsung, sehingga sebagian besar proyek hanya memerlukan satu plugin di vite.config.ts:

    vite.config.ts
    import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});
    • Compiler: Diaktifkan secara otomatis ketika compiler.enabled diatur ke true dan jalur compiler.output dikonfigurasi. Anda tidak lagi perlu mendaftarkan intlayerCompiler() secara terpisah.
    • Proxy: Diaktifkan secara otomatis berdasarkan opsi routing.enableProxy yang baru (true secara default). Ini menghubungkan middleware deteksi locale / redirect / rewrite dalam pengembangan, preview, dan SSR produksi. Anda tidak lagi perlu mendaftarkan intlayerProxy() secara terpisah.

    Opsi routing.enableProxy

    Opsi baru routing.enableProxy mengontrol apakah proxy locale-routing dipasang. Defaultnya adalah true. Nonaktifkan ketika Anda ingin menangani locale routing sendiri:

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // Default: true  },};export default config;

    Plugin standalone intlayerCompiler() dan intlayerProxy() tetap diekspor untuk setup lanjutan. Mendaftarkan mereka bersama dengan intlayer() aman — setiap plugin menghilangkan duplikat dirinya sendiri dan hanya berjalan sekali.

    Compiler dinonaktifkan secara default

    Mulai dari Intlayer v9, compiler dinonaktifkan secara default (compiler.enabled sekarang default-nya false). Untuk mengaktifkan ekstraksi file .content.ts Anda pada saat build, atur compiler.enabled: true di konfigurasi Anda:

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // Default: false — diperlukan untuk mengaktifkan compiler sejak v9    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

    Ketika compiler dinonaktifkan, Intlayer melewati langkah ekstraksi saat build dan mengandalkan dictionary yang sudah Anda deklarasikan. Aktifkan hanya ketika Anda ingin plugin bundler (@intlayer/swc, @intlayer/babel, atau plugin Vite intlayer()) mengekstrak konten secara otomatis.

    React Native: impor paket tunggal

    Dalam aplikasi React Native atau Expo, Anda tidak perlu lagi beralih antara react-intlayer dan react-native-intlayer. Paket react-native-intlayer sekarang mengekspor ulang seluruh API react-intlayer (hooks, utilitas, dan subjalur /format, /html, dan /markdown), dan IntlayerProvider-nya secara otomatis menerapkan polyfill React Native.

    Impor semuanya dari paket tunggal react-native-intlayer:

    tsx
    import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";
    bash
    npm install intlayer react-native-intlayer
    Mengimpor dari react-intlayer tetap berfungsi, tetapi react-native-intlayer sekarang adalah titik masuk tunggal yang direkomendasikan untuk React Native — provider-nya menyediakan polyfill yang tidak dimiliki oleh provider react-intlayer yang berorientasi web.

    SDK CMS: gunakan Intlayer sebagai basis data konten headless

    Intlayer v9 menyertakan SDK yang bersih dan mengautentikasi sendiri di @intlayer/api untuk berinteraksi dengan CMS secara terprogram — mengambil proyek, mengambil kamus, serta mengirim atau memperbaruinya dari server, skrip, atau CI Anda sendiri. Autentikasi (OAuth2 client_credentials) ditangani dan disegarkan untuk Anda.

    SDK dibagi menjadi dua impor terpisah sehingga bundel Anda hanya menyertakan domain yang benar-benar Anda gunakan:

    1. createIntlayerCMS — sebuah autentikator ringan yang menyimpan kredensial dan token yang dikelola (tanpa menyertakan klien domain).
    2. dictionaryEndpoint, projectEndpoint, … — pengikat endpoint per domain, masing-masing diimpor dari subpath-nya sendiri.
    cms.ts
    import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// Konfigurasi bersifat opsional: kredensial kembali ke INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET yang diselesaikan oleh `@intlayer/config/built`.const cms = createIntlayerCMS();// Bacaconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// Tulis — gunakan CMS seperti basis dataawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
    Keamanan: kredensial CMS memberikan akses tulis ke konten Anda. Selalu buat autentikator hanya di sisi server — jangan pernah mengirim clientId / clientSecret ke browser.

    Catatan migrasi dari v8

    Jika Anda memperbarui dari v8, perhatikan bahwa v9 tidak menyertakan breaking changes (perubahan yang merusak). Namun berikut adalah perubahan utamanya:

    • Compiler dinonaktifkan secara default: compiler.enabled sekarang default-nya false. Jika Anda mengandalkan ekstraksi file .content.ts saat build, atur compiler.enabled: true di intlayer.config.ts Anda.
    • Locales & Dialects: Jika menggunakan dependensi i18n eksternal, tambahkan plugin compat adapter masing-masing dalam konfigurasi atau pengaturan bundler Anda untuk menulis ulang impor secara otomatis.
    • Custom Selectors: Saat memanggil useIntlayer, parameter kedua sekarang dicadangkan untuk objek opsi yang berisi { locale, item, variant }. Jika sebelumnya Anda meneruskan string locale secara langsung, Anda masih dapat melakukannya, tetapi menggunakan objek opsi sangat direkomendasikan untuk pemilihan tingkat lanjut.

    Tautan berguna

    Language Server Protocol
    v8