@intlayer/docs 7.0.0-canary.1 → 7.0.0-canary.3

package/docs/id/releases/v7.md

@@ -0,0 +1,503 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Intlayer v7 Baru - Apa yang Baru?
+description: Temukan apa yang baru di Intlayer v7. Peningkatan besar dalam performa, pengalaman pengembang, dan fitur baru untuk meningkatkan alur kerja internasionalisasi Anda.
+keywords:
+  - Intlayer
+  - Lokalisasi
+  - Pengembangan
+  - Performa
+  - Pengalaman Pengembang
+  - Fitur
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# 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.
+
+## 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.
+
+```bash
+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:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Perilaku v7:**
+
+```tsx
+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:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum yang mencakup semua locale -> tidak tree-shakeable
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Tipe string -> sepenuhnya tree-shakeable
+
+const 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](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) 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
+
+```typescript
+// intlayer.config.ts
+export 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:
+
+```typescript
+// Nonaktifkan penyimpanan
+storage: false
+
+// Jenis penyimpanan sederhana
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie dengan atribut khusus
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage dengan kunci khusus
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Beberapa jenis penyimpanan untuk redundansi
+storage: ['cookie', 'localStorage']
+```
+
+### Contoh konfigurasi yang sesuai GDPR
+
+Untuk aplikasi produksi yang perlu menyeimbangkan fungsionalitas dengan kepatuhan GDPR:
+
+```typescript
+// intlayer.config.ts
+export 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:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Dapat menimpanya secara lokal untuk setiap hook:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Catatan:** Cookie diaktifkan secara default.
+**Catatan:** Periksa [persyaratan cookie GDPR](https://gdpr.eu/cookies/) 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.
+
+---
+
+## 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
+
+```typescript
+// Menulis ulang file saat ini dengan semua locale
+const content = {
+  key: "example",
+  fill: true, // Menulis ulang file ini
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Mengisi file terpisah tanpa memodifikasi file saat ini
+const content = {
+  key: "example",
+  fill: "./translations.json", // Membuat/memperbarui translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Menonaktifkan auto-fill
+const content = {
+  key: "example",
+  fill: false, // Tidak ada auto-fill
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Struktur konten kompleks dengan objek yang disusun
+const 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
+
+```typescript
+// File konten besar secara otomatis dipecah
+const 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`
+
+### Pemetaan migrasi
+
+#### Pemetaan konfigurasi
+
+| Konfigurasi v6             | Konfigurasi v7                                         |
+| -------------------------- | ------------------------------------------------------ |
+| `autoFill: xxx`            | `fill: xxx`                                            |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                            |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                   |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                    |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`       |
+| `serverSetCookie: 'never'` | `storage: false` atau hapus cookie dari array storage` |
+
+#### Contoh migrasi
+
+**Sebelum (v6):**
+
+````typescript
+export default {
+#### Pemetaan konfigurasi
+
+| Konfigurasi v6            | Konfigurasi v7                                      |
+| ------------------------- | -------------------------------------------------- |
+| `autoFill: xxx`           | `fill: xxx`                                        |
+| `prefixDefault: false`    | `mode: 'prefix-no-default'`                        |
+| `prefixDefault: true`     | `mode: 'prefix-all'`                               |
+| `noPrefix: true`          | `mode: 'no-prefix'`                                |
+| `cookieName: 'my-locale'` | `storage: { type: 'cookie', name: 'my-locale' }`  |
+| `serverSetCookie: 'never'`| `storage: false` atau hapus cookie dari array storage` |
+
+#### Contoh migrasi
+
+**Sebelum (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+````
+
+**Sesudah (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // atau 'cookie' jika Anda membutuhkan penyimpanan cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Pemetaan konten kamus
+
+| Konten kamus v6 | Konten kamus v7 |
+| --------------- | --------------- |
+| `autoFill: xxx` | `fill: xxx`     |
+
+#### Contoh migrasi
+
+**Sebelum (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Menulis ulang file ini
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+**Setelah (v7):**
+
+```typescript
+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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/releases/v6.md) untuk informasi lebih lanjut.
+
+---
+
+## Tautan berguna
+
+- [Referensi Konfigurasi](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/configuration.md)
+- [Dokumentasi Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/packages/next-intlayer/index.md)
+- [Tipe TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Panduan Cookie GDPR](https://gdpr.eu/cookies/)