@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.3

package/docs/id/dictionary/translation.md

@@ -85,7 +85,10 @@ export default config;
 
 ## Menggunakan Terjemahan dalam Komponen React
 
-Dengan `react-intlayer`, Anda dapat menggunakan terjemahan dalam komponen React. Berikut adalah contohnya:
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+With `react-intlayer`, you can use translations in React components. Here's an example:
 
 ```jsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
@@ -104,7 +107,158 @@ const MyComponent: FC = () => {
 export default MyComponent;
 ```
 
-Komponen ini mengambil terjemahan yang sesuai berdasarkan locale saat ini yang diatur dalam aplikasi Anda.
+This component fetches the corresponding translation based on the current locale set in your application.
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+With `next-intlayer`, you can use translations in React Server Components or Client Components. Here's an example in a Client Component:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+const MyComponent: FC = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+With `vue-intlayer`, you can use translations in Vue components. Here's an example:
+
+```vue fileName="**/*.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const content = useIntlayer("multi_lang");
+</script>
+
+<template>
+  <div>
+    <p>{{ content.welcomeMessage }}</p>
+  </div>
+</template>
+```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+With `svelte-intlayer`, you can use translations in Svelte components. The hook returns a Svelte store. Here's an example:
+
+```svelte fileName="**/*.svelte"
+<script lang="ts">
+import { useIntlayer } from "svelte-intlayer";
+
+const content = useIntlayer("multi_lang");
+</script>
+
+<div>
+  <p>{$content.welcomeMessage}</p>
+</div>
+```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+With `preact-intlayer`, you can use translations in Preact components. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { FC } from "preact";
+import { useIntlayer } from "preact-intlayer";
+
+const MyComponent: FC = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+With `solid-intlayer`, you can use translations in SolidJS components. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { Component } from "solid-js";
+import { useIntlayer } from "solid-intlayer";
+
+const MyComponent: Component = () => {
+  const content = useIntlayer("multi_lang");
+
+  return (
+    <div>
+      <p>{content.welcomeMessage}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+With `angular-intlayer`, you can use translations in Angular components. Here's an example:
+
+```typescript fileName="app.component.ts" codeFormat="typescript"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-my-component",
+  template: `
+    <div>
+      <p>{{ content().welcomeMessage }}</p>
+    </div>
+  `,
+})
+export class MyComponent {
+  content = useIntlayer("multi_lang");
+}
+```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+
+With `vanilla-intlayer`, you can use translations by subscribing to content changes. Here's an example:
+
+```typescript fileName="**/*.ts" codeFormat={["typescript", "esm"]}
+import { installIntlayer, useIntlayer } from "vanilla-intlayer";
+
+installIntlayer();
+
+const content = useIntlayer("multi_lang").onChange((newContent) => {
+  document.getElementById("welcome-message")!.textContent = String(
+    newContent.welcomeMessage
+  );
+});
+
+// Initial render
+document.getElementById("welcome-message")!.textContent = String(
+  content.welcomeMessage
+);
+```
+
+  </Tab>
+</Tabs>
 
 ## Objek Konten Kustom
 

package/docs/id/dynamic_dictionaries/collections.md

@@ -14,7 +14,7 @@ slugs:
   - concept
   - collections
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Rilis fitur kamus koleksi"
 author: aymericzip

package/docs/id/dynamic_dictionaries/dynamic_content.md

@@ -15,7 +15,7 @@ slugs:
   - concept
   - dynamic-records
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Rilis fitur konten dinamis"
 author: aymericzip

package/docs/id/dynamic_dictionaries/index.md

@@ -15,7 +15,7 @@ slugs:
   - concept
   - dynamic-dictionaries
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Rilis fitur kamus dinamis"
 author: aymericzip

package/docs/id/dynamic_dictionaries/variants.md

@@ -15,7 +15,7 @@ slugs:
   - concept
   - variants
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-12
     changes: "Rilis fitur varian kamus"
 author: aymericzip

package/docs/id/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Plugin Sinkronisasi JSON
 description: Sinkronkan kamus Intlayer dengan file JSON i18n pihak ketiga (i18next, next-intl, react-intl, vue-i18n, dan lainnya). Pertahankan i18n Anda yang sudah ada sambil menggunakan Intlayer untuk mengelola, menerjemahkan, dan menguji pesan Anda.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "Menambahkan opsi splitKeys (satu kamus per kunci namespace tingkat atas) untuk tata letak file tunggal next-intl / react-intl"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Menambahkan dukungan format ICU dan i18next"
@@ -62,7 +65,63 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## Mulai cepat
+## Plugins
+
+This package provides two plugins:
+
+- `loadJSON`: Load JSON files into Intlayer dictionaries.
+  - This plugin is used to load JSON files from a source and will be loaded into Intlayer dictionaries. It can scan all the codebase and search for specific JSON files.
+    This plugin can be used
+    - if you use an i18n library that impose a specific location for your JSON to be loaded (ex: `next-intl`, `i18next`, `react-intl`, `vue-i18n`, etc.), but you want to place your content declaration where you want in your code base.
+    - It can also be used if you want to fetch your messages from a remote source (ex: a CMS, a API, etc.) and store your messages in JSON files.
+
+  > Under the hood, this plugin will scan all the codebase and search for specific JSON files and load them into Intlayer dictionaries.
+  > Note that this plugin will not write the output and translations back to the JSON files.
+
+- `syncJSON`: Synchronize JSON files with Intlayer dictionaries.
+  - This plugin is used to synchronize JSON files with Intlayer dictionaries. It can scan the given location and load the JSON that match the pattern for specific JSON files. This plugin is useful if you want to get the benefits of Intlayer while using another i18n library.
+
+## Using both plugins
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Keep your current JSON files in sync with Intlayer dictionaries
+  plugins: [
+    /**
+     * Will load all the JSON files in the src that match the pattern {key}.i18n json
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Ensures these JSON files take precedence over files at `./locales/en/${key}.json`
+      format: "intlayer", // Format of the JSON content
+    }),
+    /**
+     * Will load, and write the output and translations back to the JSON files in the locales directory
+     */
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Quick start
 
 Tambahkan plugin ke `intlayer.config.ts` Anda dan arahkan ke struktur JSON yang sudah ada.
 
@@ -81,6 +140,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // Tata letak per-locale, per-namespace (misalnya, next-intl, i18next dengan namespaces)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +151,27 @@ export default config;
 Alternatif: satu file per locale (umum dengan pengaturan i18next/react-intl):
 
 ```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### Cara kerjanya
+#### Cara kerjanya
 
 - Baca: plugin menemukan file JSON dari pembangun `source` Anda dan memuatnya sebagai kamus Intlayer.
 - Tulis: setelah proses build dan pengisian, plugin menulis kembali JSON yang sudah dilokalkan ke jalur yang sama (dengan newline akhir untuk menghindari masalah format).
@@ -112,6 +185,7 @@ syncJSON({
   location?: string, // label opsional, default: "plugin"
   priority?: number, // prioritas opsional untuk resolusi konflik, default: 0
   format?: 'intlayer' | 'icu' | 'i18next', // formatter opsional, digunakan untuk kompatibilitas runtime Intlayer
+  splitKeys?: boolean, // opsional, membagi satu file menjadi satu kamus per kunci tingkat atas (terdeteksi otomatis)
 });
 ```
 
@@ -136,17 +210,49 @@ syncJSON({
 }),
 ```
 
-## Beberapa sumber JSON dan prioritas
+#### `splitKeys` (boolean)
+
+Mengontrol apakah satu file JSON yang **kunci tingkat pertamanya adalah namespace** harus menjadi satu kamus per kunci tingkat atas, alih-alih satu kamus yang menampung seluruh file.
+
+Ini cocok dengan model namespace dari pustaka seperti `next-intl` dan `react-intl`, di mana satu file `messages/{locale}.json` mengelompokkan beberapa namespace berdasarkan kunci tingkat pertamanya, masing-masing ditangani secara independen (misalnya `useTranslations('Hero')` menyelesaikan ke kamus `Hero`).
+
+- `undefined` (default): **terdeteksi otomatis** — file dibagi ketika pola `source` tidak memiliki segmen `{key}` (satu file menampung setiap namespace), dan disimpan sebagai satu kamus jika tidak (satu file per kunci).
+- `true`: selalu membagi setiap kunci tingkat atas menjadi kamusnya sendiri.
+- `false`: jangan pernah membagi; seluruh file menjadi satu kamus.
+
+Mengingat satu file `messages/{locale}.json`:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // tersirat karena pola tidak memiliki segmen `{key}`
+}),
+```
+
+Ini menghasilkan tiga kamus — `Hero`, `Nav`, dan `About` — sehingga `useTranslations('Hero')` (next-intl) menyelesaikan dengan benar. Saat ditulis kembali, semua namespace disatukan kembali ke dalam file per-locale yang sama.
+
+> Ketika Anda mempertahankan segmen `{key}` eksplisit di `source` Anda (misalnya `./locales/${locale}/${key}.json`), setiap file sudah menjadi satu namespace, sehingga pemisahan dinonaktifkan secara default.
+
+### Multiple JSON sources and priority
 
 Anda dapat menambahkan beberapa plugin `syncJSON` untuk menyinkronkan berbagai sumber JSON. Ini berguna ketika Anda memiliki beberapa pustaka i18n atau struktur JSON yang berbeda dalam proyek Anda.
 
-### Sistem prioritas
+#### Sistem prioritas
 
 Ketika beberapa plugin menargetkan kunci kamus yang sama, parameter `priority` menentukan plugin mana yang diutamakan:
 
 - Angka prioritas yang lebih tinggi menang atas yang lebih rendah
 - Prioritas default untuk file `.content` adalah `0`
-- Prioritas default untuk file konten plugin adalah `-1`
+- Prioritas default untuk file konten plugin adalah `0`
 - Plugin dengan prioritas yang sama diproses sesuai urutan kemunculannya dalam konfigurasi
 
 ```ts fileName="intlayer.config.ts"
@@ -189,73 +295,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Penyelesaian konflik
+## Load JSON plugin
 
-Ketika kunci terjemahan yang sama ada di beberapa sumber JSON:
+### Quick start
 
-1. Plugin dengan prioritas tertinggi menentukan nilai akhir
-2. Sumber dengan prioritas lebih rendah digunakan sebagai cadangan untuk kunci yang hilang
-3. Ini memungkinkan Anda mempertahankan terjemahan legacy sambil secara bertahap bermigrasi ke struktur baru
+Add the plugin to your `intlayer.config.ts` to ingest existing JSON files as Intlayer dictionaries. This plugin is read‑only (no writes to disk):
 
-## Integrasi
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-Berikut adalah pemetaan umum. Biarkan runtime Anda tetap tidak berubah; hanya tambahkan plugin.
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
 
-### i18next
+  plugins: [
+    // Ingest JSON messages located anywhere in your source tree
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Load a single locale per plugin instance (defaults to the config defaultLocale)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-Tata letak file tipikal: `./public/locales/{locale}/{namespace}.json` atau `./locales/{locale}/{namespace}.json`.
+export default config;
+```
+
+Alternative: per‑locale layout, still read‑only (only the selected locale is loaded):
 
 ```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-export default {
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
   plugins: [
-    syncJSON({
-      format: "i18next",
+    loadJSON({
+      // Only files for Locales.FRENCH will be loaded from this pattern
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### How it works
 
-Pesan JSON per-locale (sering `./messages/{locale}.json`) atau per-namespace.
+- Discover: builds a glob from your `source` builder and collects matching JSON files.
+- Ingest: loads each JSON file as an Intlayer dictionary with the provided `locale`.
+- Read‑only: does not write or format output files; use `syncJSON` if you need round‑trip sync.
+- Auto‑fill ready: defines a `fill` pattern so `intlayer content fill` can populate missing keys.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+### API
+
+```ts
+loadJSON({
+  // Bangun jalur ke JSON Anda. `locale` bersifat opsional jika struktur Anda tidak memiliki segmen locale
+  source: ({ key, locale }) => string,
+
+  // Locale target untuk kamus yang dimuat oleh instance plugin ini
+  // Default ke configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Label opsional untuk mengidentifikasi sumber
+  location?: string, // default: "plugin"
+
+  // Prioritas yang digunakan untuk resolusi konflik terhadap sumber lain
+  priority?: number, // default: 0
+
+  // Formatter opsional untuk konten JSON
+  format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // Membagi satu file menjadi satu kamus per kunci tingkat atas (terdeteksi otomatis)
+  splitKeys?: boolean,
+});
 ```
 
-Lihat juga: `docs/id/intlayer_with_next-intl.md`.
+#### `format` ('intlayer' | 'icu' | 'i18next')
 
-### react-intl
+Specifies the formatter to use for the dictionary content when loading JSON files. This allows using different message formatting syntaxes compatible with various i18n libraries.
 
-JSON tunggal per locale adalah umum:
+- `'intlayer'`: The default Intlayer formatter (default).
+- `'icu'`: Uses ICU message formatting (compatible with libraries like react-intl, vue-i18n).
+- `'i18next'`: Uses i18next message formatting (compatible with i18next, next-i18next, Solid-i18next).
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+**Example:**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // Use ICU formatting for compatibility
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-Baik satu file per locale atau per-namespace:
+Perilaku yang sama seperti di [`syncJSON`](#splitkeys-boolean): ketika satu file JSON mengelompokkan beberapa namespace berdasarkan kunci tingkat pertamanya, setiap kunci tingkat atas menjadi kamusnya sendiri.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (default): **terdeteksi otomatis** — dibagi ketika pola `source` tidak memiliki segmen `{key}`, kamus tunggal jika tidak.
+- `true` / `false`: paksa atau nonaktifkan pemisahan.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys diaktifkan otomatis: `Hero`, `Nav`, `About`, … masing-masing menjadi kamus
+}),
 ```
 
+### Behavior and conventions
+
+- If your `source` mask includes a locale placeholder, only files for the selected `locale` are ingested.
+- Jika tidak ada segmen `{key}` dalam mask Anda, setiap kunci tingkat atas dari file menjadi kamusnya sendiri secara default (lihat [`splitKeys`](#splitkeys-boolean)). Atur `splitKeys: false` untuk memuat seluruh file sebagai satu kamus `index`.
+- Keys are derived from file paths by substituting the `{key}` placeholder in your `source` builder.
+- The plugin only uses discovered files and does not fabricate missing locales or keys.
+- The `fill` path is inferred from your `source` and used to update missing values via CLI when you opt‑in.
+
+## Conflict resolution
+
+Ketika kunci terjemahan yang sama ada di beberapa sumber JSON:
+
+1. Plugin dengan prioritas tertinggi menentukan nilai akhir
+2. Sumber dengan prioritas lebih rendah digunakan sebagai cadangan untuk kunci yang hilang
+3. Ini memungkinkan Anda mempertahankan terjemahan legacy sambil secara bertahap bermigrasi ke struktur baru
+
 ## CLI
 
 File JSON yang disinkronkan akan dianggap sebagai file `.content` lainnya. Artinya, semua perintah intlayer akan tersedia untuk file JSON yang disinkronkan. Termasuk: