Intlayer v7 Baru - Apa yang Baru?

Selamat datang di Intlayer v7! Rilis besar ini memperkenalkan peningkatan signifikan dalam performa, keamanan tipe, dan pengalaman pengembang. Berikut adalah sorotan utama, dengan catatan migrasi dan contoh praktis.

Daftar isi

Sorotan

• Strategi caching untuk build yang lebih cepat
• Peningkatan pembuatan tipe TypeScript dengan tipe spesifik locale
• Optimasi bundel: Locale sebagai string bukan enum
• Mode routing baru: prefix-no-default, prefix-all, no-prefix, search-params
• Penyimpanan locale sesuai GDPR dengan localStorage sebagai default
• Konfigurasi penyimpanan yang fleksibel: cookies, localStorage, sessionStorage, atau kombinasi
• Ukuran paket Visual Editor 30% lebih kecil
• Opsi konfigurasi middleware yang ditingkatkan
• Perilaku perintah fill yang diperbarui untuk manajemen konten yang lebih baik
• Stabilitas yang ditingkatkan dengan pembaruan lengkap file deklarasi konten
• Manajemen retry cerdas untuk akurasi terjemahan
• Paralelisasi untuk pemrosesan terjemahan yang lebih cepat
• Pemecahan chunk cerdas untuk menangani file besar dalam batas konteks AI

Performa: Caching untuk build yang lebih cepat

Alih-alih membangun ulang deklarasi konten dengan esbuild pada setiap build, v7 menerapkan strategi caching yang mempercepat proses build.

npx intlayer build

Sistem caching baru:

• Menyimpan deklarasi konten yang sudah dikompilasi untuk menghindari pemrosesan berulang
• Mendeteksi perubahan dan hanya membangun ulang file yang dimodifikasi
• Secara signifikan mengurangi waktu build untuk proyek besar

TypeScript: Pembuatan tipe spesifik locale

Tipe TypeScript sekarang dibuat per locale, memberikan tipe yang lebih kuat dan menghilangkan tipe union di seluruh locale.

Perilaku v6:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Perilaku v7:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

Manfaat:

• Autocomplete yang lebih tepat di IDE Anda
• Keamanan tipe yang lebih baik tanpa polusi tipe lintas locale
• Performa yang ditingkatkan dengan mengurangi kompleksitas tipe

Optimasi bundle: Locale sebagai string

Tipe Locales tidak lagi berupa enum, yang berarti sekarang sepenuhnya tree-shakeable dan tidak akan membengkakkan bundle Anda dengan ribuan catatan locale yang tidak digunakan.

v6:

import { Locales } from "intlayer";// Enum yang mencakup semua locale -> tidak tree-shakeableconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// Tipe string -> sepenuhnya tree-shakeableconst locale: Locale = Locales.ENGLISH;

Karena Locales tidak lagi berupa enum, Anda harus mengubah tipe dari Locales menjadi Locale untuk mendapatkan locale sebagai tipe.

Lihat detail implementasi untuk informasi lebih lanjut.

Mode routing baru untuk fleksibilitas lebih besar

v7 memperkenalkan konfigurasi routing.mode yang terpadu yang menggantikan opsi prefixDefault dan noPrefix sebelumnya, menawarkan kontrol yang lebih rinci atas struktur URL.

Mode routing yang tersedia

• prefix-no-default (default): Locale default tidak memiliki prefix, locale lain memiliki prefix
  • /dashboard (en) atau /fr/dashboard (fr)
• prefix-all: Semua locale memiliki prefix
  • /en/dashboard (en) atau /fr/dashboard (fr)
• no-prefix: Tidak ada prefix locale di URL (locale ditangani melalui penyimpanan/header)
  • /dashboard untuk semua locale
• search-params: Locale diteruskan sebagai parameter query
  • /dashboard?locale=en atau /dashboard?locale=fr

Konfigurasi dasar

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // default  },};

Kepatuhan GDPR: penyimpanan localStorage / cookies

v7 memprioritaskan privasi pengguna dengan menggunakan localStorage sebagai mekanisme penyimpanan default menggantikan cookies. Perubahan ini membantu kepatuhan GDPR dengan menghindari kebutuhan persetujuan cookie untuk preferensi locale.

Opsi konfigurasi penyimpanan

Field routing.storage baru juga tersedia selain opsi middleware.cookieName dan middleware.serverSetCookie sebelumnya, menawarkan konfigurasi penyimpanan yang fleksibel:

// Nonaktifkan penyimpananstorage: false// Jenis penyimpanan sederhanastorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie dengan atribut khususstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage dengan kunci khususstorage: {  type: 'localStorage',  name: 'custom-locale'}// Beberapa jenis penyimpanan untuk redundansistorage: ['cookie', 'localStorage']

Contoh konfigurasi yang sesuai GDPR

Untuk aplikasi produksi yang perlu menyeimbangkan fungsionalitas dengan kepatuhan GDPR:

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default",    storage: [      {        type: "localStorage", // Penyimpanan utama (tidak memerlukan persetujuan)        name: "user-locale",      },      {        type: "cookie", // Penyimpanan cookie opsional (memerlukan persetujuan)        name: "user-locale",        secure: true,        sameSite: "strict",        httpOnly: false,      },    ],  },};

Aktifkan / nonaktifkan penyimpanan cookie

Contoh menggunakan React / Next.js:

Dapat didefinisikan secara global:

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Dapat menimpanya secara lokal untuk setiap hook:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Catatan: Cookie diaktifkan secara default. Catatan: Periksa persyaratan cookie GDPR untuk kasus penggunaan spesifik Anda.

Visual Editor: Paket 30% lebih kecil

Paket Visual Editor telah dioptimalkan menjadi 30% lebih kecil dibandingkan versi sebelumnya, berkat:

• Peningkatan performa editor kode
• Penghapusan dependensi yang tidak perlu pada paket inti Intlayer
• Tree-shaking dan pengemasan modul yang lebih baik

Ini menghasilkan waktu unduh yang lebih cepat dan peningkatan performa runtime untuk aplikasi Anda.

Pemformatan Kode Otomatis: konfigurasi formatCommand

v7 memperkenalkan opsi formatCommand dalam konfigurasi editor, memungkinkan Anda untuk secara otomatis memformat file konten ketika ditulis oleh Intlayer. Ini memastikan gaya kode dan pemformatan yang konsisten di seluruh file deklarasi konten Anda.

Jika tidak diatur, Intlayer akan mencoba mendeteksi perintah format secara otomatis. Dengan mencoba menyelesaikan perintah berikut: prettier, biome, eslint.

Konfigurasi

Opsi formatCommand menerima template string di mana {{file}} akan diganti dengan path file yang sebenarnya:

export default {  content: {    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',  },};

Pemformat yang Didukung

Anda dapat menggunakan pemformat kode apa pun yang menerima jalur file sebagai argumen:

Menggunakan Biome:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Menggunakan Prettier:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Menggunakan ESLint:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Menggunakan pemformat bawaan Bun:

formatCommand: 'bun format "{{file}}"';

Manfaat

• Pemformatan konsisten: Semua file konten diformat secara otomatis sesuai dengan panduan gaya proyek Anda
• Pengalaman pengembang: Tidak perlu memformat file secara manual setelah Intlayer menulisnya
• Konsistensi tim: Memastikan semua anggota tim memiliki pemformatan yang sama diterapkan pada file konten
• Integrasi CI/CD: File konten mempertahankan pemformatan konsisten dalam alur kerja otomatis

Cara kerjanya

Ketika Intlayer menulis atau memperbarui file deklarasi konten (.content.ts, .content.js, dll.), ia secara otomatis menjalankan perintah format yang ditentukan pada file tersebut. Placeholder {{file}} diganti dengan jalur file aktual, dan perintah dijalankan di direktori dasar proyek.

Konfigurasi Dictionary: Organisasi dan struktur yang lebih baik

v7 memperkenalkan bagian konfigurasi dictionary yang baru dan dedicated yang menyediakan organisasi yang lebih baik untuk pengaturan terkait dictionary dan manajemen konten yang ditingkatkan.

Struktur konfigurasi dictionary baru

Properti fill telah dipindahkan dari bagian content ke bagian dictionary yang baru, memberikan pemisahan kepedulian yang lebih jelas:

konfigurasi v6:

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

konfigurasi v7:

export default {  content: {    contentDir: ["src"],  },  dictionary: {    fill: "./{{fileName}}.content.json",  },};

Manfaat struktur baru

• Organisasi yang lebih jelas: Pengaturan khusus kamus sekarang dikelompokkan bersama
• Pemisahan tanggung jawab yang lebih baik: Penemuan konten vs. operasi kamus dipisahkan dengan jelas
• Kemudahan pemeliharaan yang ditingkatkan: Lebih mudah untuk memahami dan memodifikasi konfigurasi terkait kamus
• Ekstensibilitas di masa depan: Bagian kamus dapat mengakomodasi pengaturan khusus kamus tambahan
• Manajemen kamus yang komprehensif: Mencakup properti seperti title, live, priority, tags, version, dan description untuk membuat dan mengelola kamus baru

Penggunaan Konfigurasi

Konfigurasi kamus melayani dua tujuan utama:

1. Nilai Default: Tentukan nilai default saat membuat file deklarasi konten
2. Perilaku Fallback: Sediakan nilai fallback ketika field spesifik tidak didefinisikan, memungkinkan Anda mendefinisikan perilaku operasi kamus secara global

Bagian kamus mencakup properti komprehensif untuk manajemen kamus:

• fill: Perilaku auto-fill untuk pembuatan konten
• title: Judul default untuk kamus baru
• live: Konfigurasi sinkronisasi langsung untuk pembaruan real-time
• priority: Pengaturan prioritas untuk resolusi kamus
• tags: Tag default untuk organisasi konten
• version: Manajemen versi untuk pembaruan kamus
• description: Deskripsi default untuk konten baru

Untuk informasi lebih lanjut tentang file deklarasi konten dan bagaimana nilai konfigurasi diterapkan, lihat Dokumentasi File Konten.

Perintah Fill: Perilaku diperbarui untuk manajemen konten yang lebih baik

v7 memperkenalkan perilaku yang ditingkatkan untuk perintah fill, memberikan manajemen konten yang lebih dapat diprediksi dan fleksibel:

Perilaku fill baru

• fill: true - Menulis ulang file saat ini dengan konten terisi untuk semua locale
• fill: "path/to/file" - Mengisi file yang ditentukan tanpa memodifikasi file saat ini
• fill: false - Menonaktifkan auto-fill sepenuhnya

Dukungan yang ditingkatkan untuk struktur konten kompleks

Perintah fill sekarang mendukung struktur deklarasi konten yang kompleks, termasuk:

• Objek tersusun: Deklarasi konten yang merujuk objek lain
• Konten terdestrukturisasi: Konten yang menggunakan pola destrukturisasi
• Referensi bersarang: Objek yang saling memanggil dalam hierarki kompleks
• Struktur konten dinamis: Konten dengan properti kondisional atau terhitung

Manfaat

• Niat yang lebih jelas: Perilaku sekarang lebih eksplisit tentang apa yang dimodifikasi
• Pemisahan yang lebih baik: File konten dapat disimpan terpisah dari terjemahan yang sudah diisi
• Alur kerja yang ditingkatkan: Pengembang memiliki kontrol lebih besar atas tempat penyimpanan terjemahan
• Dukungan struktur kompleks: Menangani arsitektur konten yang rumit dengan banyak objek yang saling terhubung

Contoh penggunaan

// Menulis ulang file saat ini dengan semua localeconst content = {  key: "example",  fill: true, // Menulis ulang file ini  content: {    title: "Hello World",  },};// Mengisi file terpisah tanpa memodifikasi file saat iniconst content = {  key: "example",  fill: "./translations.json", // Membuat/memperbarui translations.json  content: {    title: "Hello World",  },};// Menonaktifkan auto-fillconst content = {  key: "example",  fill: false, // Tidak ada auto-fill  content: {    title: "Hello World",  },};// Struktur konten kompleks dengan objek yang disusunconst sharedContent = {  buttons: {    save: "Simpan",    cancel: "Batal",  },};const content = {  key: "complex-example",  fill: true,  content: {    // Referensi ke objek lain    sharedContent,    // Konten yang di-destrukturisasi    ...sharedContent,    // Referensi bersarang    sections: [      {        ...sharedContent.buttons,        header: "Bagian 1",      },    ],  },};

Stabilitas dan manajemen terjemahan yang ditingkatkan

v7 memperkenalkan beberapa peningkatan untuk membuat terjemahan konten lebih andal dan efisien:

Pembaruan lengkap file deklarasi konten

Sistem sekarang memperbarui file .content.{ts,js,cjs,mjs} secara penuh, bukan pembaruan parsial, memastikan:

• Integritas data: Penulisan ulang file secara lengkap mencegah pembaruan parsial yang dapat merusak konten
• Konsistensi: Semua lokal diperbarui secara atomik, menjaga sinkronisasi
• Keandalan: Mengurangi risiko file konten yang tidak lengkap atau rusak

Manajemen pengulangan cerdas

Mekanisme pengulangan baru mencegah pengiriman konten dalam format yang salah, dan menghindari kegagalan seluruh proses pengisian jika satu permintaan gagal.

Paralelisasi untuk pemrosesan lebih cepat

Operasi terjemahan sekarang dijalankan dalam antrean agar dapat berjalan secara paralel. Ini secara signifikan mempercepat proses.

Pemecahan cerdas untuk file besar

Strategi pemecahan lanjutan menangani file konten besar tanpa melebihi jendela konteks AI:

Contoh alur kerja

// File konten besar secara otomatis dipecahconst content = {  key: "large-documentation",  fill: true,  content: {    // Konten besar secara otomatis dibagi untuk pemrosesan AI    introduction: "..." // lebih dari 5000 karakter    sections: [      // Beberapa bagian besar    ]  }};

Sistem secara otomatis:

1. Menganalisis ukuran dan struktur konten
2. Membagi konten dengan tepat
3. Memproses bagian secara paralel
4. Memvalidasi dan mencoba ulang jika diperlukan
5. Membangun kembali file lengkap

Catatan migrasi dari v6

Konfigurasi yang dihapus

• middleware.cookieName: Digantikan oleh routing.storage
• middleware.serverSetCookie: Digantikan oleh routing.storage
• middleware.prefixDefault: Digantikan oleh routing.mode
• middleware.noPrefix: Digantikan oleh routing.mode

Konfigurasi baru

• editor.formatCommand: Opsi baru untuk pemformatan kode otomatis pada file konten

Pemetaan migrasi

Pemetaan konfigurasi

Contoh migrasi

Sebelum (v6):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Sesudah (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // atau 'cookie' jika Anda membutuhkan penyimpanan cookie    headerName: "x-intlayer-locale",    basePath: "",  },};

Pemetaan konten kamus

Contoh migrasi

Sebelum (v6):

const content = {  key: "example",  autoFill: true, // Menulis ulang file ini  content: {    title: "Hello World",  },};

Setelah (v7):

const content = {  key: "example",  fill: true, // Menulis ulang file ini  content: {    title: "Hello World",  },};

Catatan migrasi dari v5 ke v6

Periksa catatan migrasi dari v5 ke v6 untuk informasi lebih lanjut.

Tautan berguna

• Referensi Konfigurasi
• Dokumentasi Middleware
• Tipe TypeScript
• Panduan Cookie GDPR