@intlayer/docs 9.1.3 → 9.3.0

package/docs/id/live-sync.md

@@ -13,6 +13,10 @@ keywords:
   - Intlayer
   - Next.js
   - Vite
+slugs:
+  - doc
+  - concept
+  - live-sync
 history:
   - version: 9.0.0
     date: 2026-07-08

package/docs/id/packages/intlayer/getMultilingualUrls.md

@@ -50,26 +50,12 @@ getMultilingualUrls(
 
 ## Parameter
 
-## Parameter
+### Parameter yang Diperlukan
 
 - `url: string`
-  - **Deskripsi**: String URL asli yang akan diberi prefix locale.
-  - **Tipe**: `string`
-
-- `locales: Locales[]`
-  - **Deskripsi**: Array opsional dari locale yang didukung. Defaultnya adalah locale yang dikonfigurasi dalam proyek.
-  - **Tipe**: `Locales[]`
-  - **Default**: `localesDefault`
-
-- `defaultLocale: Locales`
-  - **Deskripsi**: Locale default untuk aplikasi. Defaultnya adalah locale default yang dikonfigurasi dalam proyek.
-  - **Tipe**: `Locales`
-  - **Default**: `defaultLocaleDefault`
-
-- `prefixDefault: boolean`
-  - **Deskripsi**: Apakah akan menambahkan prefix pada locale default. Defaultnya adalah nilai yang dikonfigurasi dalam proyek.
-  - **Tipe**: `boolean`
-  - **Default**: `prefixDefaultDefault`
+  - **Description**: String URL asli yang akan diawali dengan locale.
+  - **Type**: `string`
+  - **Required**: Yes
 
 ### Parameter Opsional
 

package/docs/id/packages/react-intlayer/useIntlayer.md

@@ -25,9 +25,9 @@ history:
 author: aymericzip
 ---
 
-## Kamus
+# Dokumentasi Hook useIntlayer
 
-Semua kunci kamus harus dideklarasikan dalam file deklarasi konten untuk meningkatkan keamanan tipe dan menghindari kesalahan. Anda dapat menemukan [instruksi pengaturan di sini](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/dictionary/content_file.md).
+Hook `useIntlayer` memungkinkan Anda untuk mengambil konten terlokalisasi dari kamus menggunakan kuncinya. Hook ini didasarkan pada `useDictionary` tetapi secara otomatis menyuntikkan versi yang dioptimalkan dari kamus dari deklarasi yang dihasilkan.
 
 ## Contoh Penggunaan di React
 

package/docs/id/packages/vite-intlayer/exports.md

@@ -48,3 +48,18 @@ import "vite-intlayer";
 | `intlayerProxy`      | Plugin middleware pengembangan untuk menangani deteksi locale dan routing.               | -                                                                                                                      |
 | `intlayerMiddleware` | (**Tidak lagi digunakan**) Alias untuk `intlayerProxy`.                                  | -                                                                                                                      |
 | `intlayerPrune`      | Plugin untuk melakukan tree-shake dan memangkas kamus yang tidak digunakan selama build. | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/packages/vite-intlayer/intlayerPrune.md) |
+
+### Utilitas
+
+| Export                       | Deskripsi                                                                                                 | Dokumentasi Terkait                                                                                                    |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createIntlayerProxyHandler` | Mengembalikan middleware Node.js `(req, res, next)` yang framework-agnostic dengan logika locale-routing. | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/packages/vite-intlayer/intlayerProxy.md) |
+
+### Tipe
+
+| Export                       | Deskripsi                                                                                                            |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | Opsi yang diterima oleh `intlayer()`. Memperluas `GetConfigurationOptions` dengan `compatCallers` dan `proxy`.       |
+| `IntlayerProxyPluginOptions` | Opsi yang diterima oleh `intlayerProxy()` dan `createIntlayerProxyHandler()`. Mencakup `ignore` dan `configOptions`. |
+| `IntlayerCompilerOptions`    | Opsi yang diterima oleh `intlayerCompiler()`. Mencakup `configOptions` dan `compilerConfig`.                         |
+| `CompatCallerConfig`         | Re-export dari `@intlayer/babel`. Menjelaskan pola compat-adapter caller untuk analisis penggunaan field.            |

package/docs/id/packages/vite-intlayer/intlayer.md

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## Deskripsi
+## Opsi
 
-Plugin melakukan tugas-tugas berikut:
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` extends `GetConfigurationOptions` (lihat `@intlayer/config`) dengan field tambahan berikut:
+
+| Opsi            | Tipe                            | Default     | Deskripsi                                                                                                                                           |
+| --------------- | ------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | Pola caller tambahan untuk package compat-adapter (misalnya `@intlayer/react-i18next`). Diteruskan ke field-usage analyser pada saat build.         |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | Opsi yang diteruskan ke bundled locale-routing proxy. Gunakan `ignore` untuk mengecualikan path tertentu (misalnya API routes) dari locale routing. |
+
+Semua opsi lainnya (`override`, `configFile`, …) diteruskan langsung ke `getConfiguration()`.
+
+### Contoh
+
+#### Abaikan rute API dari routing lokal
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+#### Dengan jalur file konfigurasi kustom
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### Dengan pemanggil compat-adapter
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## Apa yang dilakukan plugin ini
+
+### 1. Persiapan Kamus
+
+Sebelum build dimulai (dan sekali per jam dalam dev), `intlayer` memanggil `prepareIntlayer` untuk mengompilasi semua file `.content.ts` menjadi kamus JSON yang dioptimalkan disimpan di `.intlayer/`.
+
+### 2. Alias modul
+
+Plugin menambahkan Vite resolve aliases sehingga `import { myDict } from 'intlayer/dictionaries/my-dict'` mengarah ke file JSON yang sudah dikompilasi di disk. SSR builds menggunakan `ssr.noExternal` untuk memastikan semua paket `@intlayer/*` dibundle dengan aliases yang diterapkan.
+
+### 3. Dev-server watcher
+
+Dalam mode pengembangan, sebuah `chokidar` watcher dimulai. Ketika file `.content.ts` berubah, kamus-kamus dikompilasi ulang dan HMR Vite menyebarkan pembaruan ke browser.
+
+### 4. Bundled locale-routing proxy (v9+)
+
+Sejak Intlayer v9 middleware `intlayerProxy` didaftarkan secara otomatis di dalam `intlayer()`. Ini menangani:
+
+- Deteksi locale dari prefiks URL, cookies, dan header `Accept-Language`.
+- 301 redirects ketika locale yang terdeteksi tidak cocok dengan URL saat ini.
+- Internal URL rewrites sehingga framework melihat parameter rute `[locale]` yang benar.
+
+Proxy dikendalikan oleh `routing.enableProxy` (default `true`) dalam konfigurasi Intlayer Anda. Untuk menonaktifkannya sepenuhnya:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+Untuk menyesuaikan perilaku proxy tanpa panggilan `intlayerProxy()` terpisah, teruskan opsi `proxy` ke plugin utama:
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+Lihat [dokumentasi intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/packages/vite-intlayer/intlayerProxy.md) untuk referensi perilaku routing lengkap.
+
+### 5. Bundled compiler (v9+)
+
+Ketika `compiler.enabled` adalah `true` **dan** `compiler.output` diatur dalam konfigurasi Intlayer Anda, `intlayer()` mendaftarkan `intlayerCompiler` secara otomatis. Compiler mengekstrak deklarasi konten inline yang ditulis langsung di dalam file komponen dan menulis konten tersebut ke dalam kamus saat transform time. Lihat [dokumentasi intlayerCompiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/packages/vite-intlayer/intlayerCompiler.md).
+
+### 6. Optimisasi Build
+
+Selama build produksi, plugin menambahkan:
+
+- **intlayerOptimize** – transformasi Babel yang menulis ulang `useIntlayer('key')` → `useDictionary(hash)` dan menyuntikkan impor JSON langsung.
+- **intlayerPrune** – menghapus bidang konten yang tidak digunakan dari JSON kamus.
+- **intlayerMinify** – mengompresi JSON kamus dan secara opsional mengubah nama bidang.
+
+Ini tidak aktif dalam mode pengembangan.
+
+## Alias yang Sudah Usang
 
-1. **Menyiapkan Kamus**: Mengompilasi kamus ke dalam berkas yang dioptimalkan saat proses build atau dev dimulai.
-2. **Mode Watch**: Dalam mode pengembangan, memantau perubahan pada berkas kamus dan mengompilasinya kembali secara otomatis.
-3. **Alias**: Menyediakan alias untuk mengakses kamus di aplikasi Anda.
-4. **Tree-shaking**: Mendukung tree-shaking untuk terjemahan yang tidak digunakan melalui plugin `intlayerPrune`.
+| Ekspor yang Sudah Usang | Pengganti  |
+| ----------------------- | ---------- |
+| `intlayerPlugin`        | `intlayer` |
+| `intLayerPlugin`        | `intlayer` |

package/docs/id/packages/vite-intlayer/intlayerPrune.md

@@ -30,16 +30,89 @@ Plugin Vite `intlayerPrune` digunakan untuk melakukan tree-shaking dan memangkas
 
 ## Penggunaan
 
+### Sebagai bagian dari `intlayer()` (direkomendasikan)
+
+Aktifkan pruning melalui konfigurasi Intlayer Anda dan plugin utama menangani semuanya:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // mengaktifkan pruning dan minify
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### Standalone
+
+Jika Anda menyusun stack plugin secara manual, `intlayerPrune` dan `intlayerMinify` berbagi objek `PruneContext` yang harus dibuat sekali dan dilewatkan ke keduanya:
+
 ```ts
-// vite.config.ts (konfigurasi Vite)
+// vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // opsional, membaca dari konteks yang sama
+  ],
 });
 ```
 
-## Deskripsi
+## Cara Kerjanya
+
+### 1. Analisis Penggunaan (buildStart)
+
+Selama `buildStart`, plugin `intlayerOptimize` (juga bagian dari `intlayer()`) memindai setiap file sumber komponen yang tercantum dalam `build.filesList`. Untuk setiap panggilan `useIntlayer('key')` atau `getIntlayer('key')`, plugin ini mencatat dengan tepat bidang mana yang diakses, misalnya:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// mencatat: myDict → { title, description }
+```
+
+Ini membangun `pruneContext.fieldUsageMap` sebelum panggilan `transform` apa pun dijalankan.
+
+### 2. JSON pruning (transform, enforce: 'pre')
+
+Ketika Vite memproses file JSON kamus yang telah dikompilasi, `intlayerPrune` mencegat sebelum konversi JSON → ESM bawaan Vite. Ini membaca peta penggunaan field dari `pruneContext` dan menghapus setiap field konten yang tidak ada dalam set penggunaan yang tercatat.
+
+Dua bentuk konten didukung:
+
+- **Static dictionaries** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Field dipangkas per-locale di dalam `translation`.
+- **Dynamic (per-locale) dictionaries** — flat `{ fieldA: ..., fieldB: ... }`. Field dipangkas di tingkat atas.
+
+### 3. Kasus Edge Cases
+
+Jika struktur konten kamus tidak dapat dikenali (misalnya, bentuk nested yang tidak biasa), kamus tersebut ditambahkan ke `pruneContext.dictionariesWithEdgeCases` dan **dibiarkan tanpa diubah**. Peringatan dicatat. `intlayerMinify` juga melewati kamus-kamus ini.
+
+### 4. Field-rename map
+
+Ketika pruning berhasil, `intlayerPrune` juga menulis `pruneContext.dictionaryKeyToFieldRenameMap` — sebuah pemetaan dari nama field asli ke alias pendek. `intlayerMinify` membaca peta ini untuk mengubah nama field dalam output JSON, dan Babel rename pass milik `intlayerOptimize` memperbarui akses properti dalam file sumber sesuai dengan itu.
+
+## Kondisi Aktivasi
+
+`intlayerPrune` aktif **hanya** ketika semua kondisi berikut terpenuhi:
+
+1. Perintah Vite adalah `build`.
+2. `build.optimize` adalah `true` (atau `undefined`, yang secara default adalah `true` untuk build).
+3. `build.purge` adalah `true` dalam konfigurasi Intlayer Anda.
 
-Plugin ini menganalisis kode sumber Anda untuk mengidentifikasi kunci kamus mana yang benar-benar digunakan. Setelah itu, plugin akan menghapus konten yang tidak terpakai dari file kamus yang dibundel. Ini sangat berguna untuk proyek besar dengan banyak kamus di mana hanya sebagian yang digunakan pada halaman atau komponen tertentu.
+Secara otomatis **dinonaktifkan** ketika `editor.enabled` adalah `true` karena editor memerlukan konten kamus lengkap.

package/docs/id/releases/v9.md

@@ -362,6 +362,18 @@ await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
 
 ---
 
+## Self-Hosting
+
+Intlayer v9 menyediakan dukungan first-class untuk menjalankan instance Intlayer Anda sendiri dengan satu perintah. Tidak ada akun Intlayer Cloud yang diperlukan.
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Installer mengunduh `docker-compose.yml` dan `.env`, auto-generate secret yang diperlukan, dan menjalankan `docker compose up -d`. Semuanya — dashboard, API, database, object storage, dan transactional email — berjalan secara lokal dalam container.
+
+---
+
 ## Catatan migrasi dari v8
 
 Jika Anda memperbarui dari v8, perhatikan bahwa v9 tidak menyertakan breaking changes (perubahan yang merusak). Namun berikut adalah perubahan utamanya:

package/docs/id/self_hosting.md

@@ -62,6 +62,32 @@ Chromium (digunakan untuk pembuatan screenshot Puppeteer) dibundel di dalam imag
 
 ---
 
+## Mulai Cepat
+
+Pull dan jalankan image yang dipublikasikan, dengan menyediakan kredensial dan secrets MongoDB Atlas Anda:
+
+```sh
+docker run -d --name intlayer \
+  -p 3000:3000 \
+  -p 3100:3100 \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v intlayer-data:/data \
+  -e DB_ID="<atlas-user>" \
+  -e DB_MDP="<atlas-password>" \
+  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
+  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \
+  -e RESEND_API_KEY="<your-resend-key>" \
+  aymericzip/intlayer-selfhost
+```
+
+Kemudian buka **http://localhost:3000**.
+
+> Dashboard disajikan di `localhost`. Lihat [Batasan](#batasan) — domain kustom tidak didukung oleh image yang dipublikasikan.
+
+---
+
 ## Memulai Cepat
 
 ```sh
@@ -97,9 +123,18 @@ Port internal (mongo, redis) tidak terekspos ke host secara default.
 
 ---
 
-## Variabel Lingkungan
+## Variabel lingkungan
 
-Installer menghasilkan `.env` yang siap pakai. Tabel di bawah ini menjelaskan setiap variabel.
+### Diperlukan
+
+| Variable               | Example                      | Description                                                                                                                                  |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas user                                                                                                                           |
+| `DB_MDP`               | _(your password)_            | MongoDB Atlas password                                                                                                                       |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas cluster host (used in the `mongodb+srv://` URI)                                                                                |
+| `BETTER_AUTH_SECRET`   | _(generated)_                | 32-byte secret for session signing                                                                                                           |
+| `S3_SECRET_ACCESS_KEY` | _(generated)_                | Secret for the bundled MinIO                                                                                                                 |
+| `RESEND_API_KEY`       | _(your key)_                 | Transactional email via Resend. Required for first-run setup unless you configure a global SMTP mailer (see [Global mailer](#global-mailer)) |
 
 ### Wajib (dibuat secara otomatis atau diminta)
 
@@ -141,6 +176,26 @@ Installer menghasilkan `.env` yang siap pakai. Tabel di bawah ini menjelaskan se
 
 ---
 
+### Global mailer
+
+Secara default, semua email transaksional dikirim melalui Resend menggunakan `RESEND_API_KEY`. Deployment yang self-hosted dapat mengarahkan **setiap** email — termasuk email non-organisasi seperti reset password dan magic links — melalui global mailer yang dikonfigurasi dengan environment variables.
+
+Atur `MAIL_PROVIDER` untuk mengaktifkannya. Ketika tidak diatur, mailer Resend default digunakan.
+
+| Variable             | Example                        | Description                                                                            |
+| -------------------- | ------------------------------ | -------------------------------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Global transport: `smtp` atau `resend`. Biarkan tidak diatur untuk menggunakan default |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Sender header. Menerima alamat bare atau format `Name <email>`                         |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host (diperlukan ketika `MAIL_PROVIDER=smtp`)                                     |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (default ke `587`)                                                           |
+| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. Atur `true` untuk port `465`                                             |
+| `MAIL_SMTP_USER`     | _(user anda)_                  | SMTP username (opsional; abaikan untuk unauthenticated relays)                         |
+| `MAIL_SMTP_PASSWORD` | _(password anda)_              | SMTP password                                                                          |
+
+> Precedence: mailer milik organisasi sendiri (dikonfigurasi dari dashboard **Organization**) mengambil prioritas atas global mailer, yang pada gilirannya mengambil prioritas atas kunci Resend default.
+
+---
+
 ## Menghubungkan proyek Intlayer Anda
 
 Setelah stack berjalan, arahkan proyek Anda ke backend dan dashboard yang di-self-host, bukan ke `intlayer.org`.
@@ -259,47 +314,11 @@ docker run --rm \
 
 ---
 
-## Menggunakan reverse proxy (Nginx / Caddy)
+## Keterbatasan
 
-Untuk deployment produksi, letakkan reverse proxy di depan kontainer aplikasi dan backend daripada mengeksposnya secara langsung.
-
-### Contoh Nginx
-
-```nginx
-server {
-    listen 80;
-    server_name cms.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-
-server {
-    listen 80;
-    server_name api.example.com;
-
-    location / {
-        proxy_pass http://localhost:3100;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-Perbarui variabel `.env` berikut agar sesuai dengan domain publik Anda:
-
-```sh
-BACKEND_URL=https://api.example.com
-APP_URL=https://cms.example.com
-DOMAIN=example.com
-VITE_BACKEND_URL=https://api.example.com
-VITE_DOMAIN=example.com
-```
-
-> Variabel `VITE_*` tertanam dalam image dashboard pada waktu build. Jika Anda mengubahnya setelah image dibuat, Anda perlu membangun ulang image `app` (`docker compose build app`) atau menggunakan injeksi konfigurasi runtime.
+- **MongoDB harus external (Atlas).** Backend terhubung hanya melalui `mongodb+srv://` (dibangun dari `DB_ID` / `DB_MDP` / `DB_CLUSTER`), jadi plain `mongodb://host:27017` — termasuk `mongod` bundled container sendiri — tidak dapat digunakan. Sediakan cluster MongoDB Atlas.
+- **Tidak ada custom domain.** Semua URL `VITE_*` yang dihadapi browser di-inline ke dalam app pada saat build, dan image yang dipublikasikan dilengkapi dengan nilai `localhost`. Dashboard harus diakses di `http://localhost:3000`; melayaninya di domain publik memerlukan rebuilding image dengan target URLs yang tertanam dan tidak didukung out of the box.
+- **Email memerlukan mailer yang berfungsi.** Setup first-run menerapkan verifikasi email, jadi baik `RESEND_API_KEY` atau [global SMTP mailer](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) harus dikonfigurasi. Setelah admin pertama masuk, setiap organisasi juga dapat mengonfigurasi SMTP atau Resend mailer-nya sendiri dari dashboard.
 
 ---
 
@@ -324,14 +343,6 @@ docker compose build app
 docker compose up -d app
 ```
 
-### Email tidak terkirim
-
-Secara default, semua email keluar ditangkap oleh Mailpit. Buka `http://localhost:8025` untuk melihat pesan yang terkirim. Untuk mengirim email sungguhan, setel `MAIL_PROVIDER=resend` dan `RESEND_API_KEY=<your-key>` di `.env`, lalu restart backend:
-
-```sh
-docker compose restart backend
-```
-
 ### Bucket MinIO hilang
 
 Jika layanan one-shot `minio-init` tidak berjalan (atau berjalan sebelum MinIO siap), buat bucket secara manual: