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, Variants, dan Dynamic Records.

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/next-i18next
• @intlayer/vue-i18n

Sebagai contoh, cukup ubah:

import { useTranslation } from "react-i18next";

menjadi:

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:

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)

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 & Dynamic Records

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

import { t, type Dictionary } from "intlayer";export default {  key: "faq",  content: [    {      question: t({        id: "Apa itu Intlayer?",        en: "What is Intlayer?",        fr: "Qu'est-ce qu'Intlayer ?",      }),      answer: t({        id: "Sebuah toolkit i18n.",        en: "An i18n toolkit.",        fr: "Une boîte à outils i18n.",      }),    },  ],} satisfies Dictionary;

Penggunaan:

// Ambil semua itemconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Ambil satu item berdasarkan indeksconst faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }

2. Variants

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

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:

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

3. Dynamic Records

Definisikan dictionary yang entrinya dimuat secara dinamis pada saat runtime melalui ID kueri:

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

Penggunaan:

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

Dynamic Loading & Optimisasi Ukuran Bundle

Untuk menjaga ukuran bundle tetap sangat kecil, Intlayer v9 mendukung dynamic lazy loading.

Dalam konfigurasi Anda, atur importMode ke 'dynamic' atau 'fetch':

export default {  dictionary: {    importMode: "dynamic", // "static" | "dynamic" | "fetch"  },};

Pada saat build time, @intlayer/swc and @intlayer/babel memindai file Anda dan mengganti panggilan useIntlayer / getIntlayer dengan wrapper yang mendukung tree-shaking (useDictionary / useDictionaryDynamic). Hanya konten yang diperlukan untuk item koleksi, varian, atau locale terpilih yang dimuat, mencegah bundle produksi Anda berisi terjemahan yang tidak digunakan.

Catatan migrasi dari v8

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

• 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, id }. Jika sebelumnya Anda meneruskan string locale secara langsung, Anda masih dapat melakukannya, tetapi menggunakan objek opsi sangat direkomendasikan untuk pemilihan tingkat lanjut.

Tautan berguna

• Panduan Compat Adapter Packages
• Dynamic Dictionaries - Collections, Variants & Dynamic Records
• Referensi Konfigurasi