@intlayer/docs 7.0.4-canary.0 → 7.0.4

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

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+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:
+  - Intlayer
+  - Sinkronisasi JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - terjemahan
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: Dokumentasi awal plugin Sinkronisasi JSON
+---
+
+# Sinkronisasi JSON (jembatan i18n)
+
+Gunakan Intlayer sebagai tambahan pada tumpukan i18n Anda yang sudah ada. Plugin ini menjaga pesan JSON Anda tetap sinkron dengan kamus Intlayer sehingga Anda dapat:
+
+- Mempertahankan i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n, dll.
+- Mengelola dan menerjemahkan pesan Anda dengan Intlayer (CLI, CI, penyedia, CMS), tanpa perlu merombak aplikasi Anda.
+- Mengirimkan tutorial dan konten SEO yang menargetkan setiap ekosistem, sambil menyarankan Intlayer sebagai lapisan pengelolaan JSON.
+
+Catatan dan cakupan saat ini:
+
+- Eksternalisasi ke CMS berfungsi untuk terjemahan dan teks klasik.
+- Belum mendukung penyisipan, bentuk jamak/ICU, atau fitur runtime lanjutan dari pustaka lain.
+- Editor visual belum didukung untuk output i18n pihak ketiga.
+
+### Kapan menggunakan plugin ini
+
+- Anda sudah menggunakan perpustakaan i18n dan menyimpan pesan dalam file JSON.
+- Anda menginginkan pengisian berbantuan AI, pengujian di CI, dan operasi konten tanpa mengubah runtime rendering Anda.
+
+## Instalasi
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# atau
+npm i -D @intlayer/sync-json-plugin
+```
+
+## Mulai cepat
+
+Tambahkan plugin ke `intlayer.config.ts` Anda dan arahkan ke struktur JSON yang sudah ada.
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Jaga file JSON Anda saat ini tetap sinkron dengan kamus Intlayer
+  plugins: [
+    syncJSON({
+      // Tata letak per-locale, per-namespace (misalnya, next-intl, i18next dengan namespaces)
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+});
+```
+
+Alternatif: satu file per locale (umum dengan pengaturan i18next/react-intl):
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### 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).
+- Auto‑fill: plugin mendeklarasikan jalur `autoFill` untuk setiap kamus. Menjalankan `intlayer fill` secara default hanya memperbarui terjemahan yang hilang dalam file JSON Anda.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // wajib
+  location?: string, // label opsional, default: "plugin"
+  priority?: number, // prioritas opsional untuk resolusi konflik, default: 0
+});
+```
+
+## Beberapa sumber JSON dan prioritas
+
+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
+
+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`
+- Plugin dengan prioritas yang sama diproses sesuai urutan kemunculannya dalam konfigurasi
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Sumber JSON utama (prioritas tertinggi)
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Sumber JSON cadangan (prioritas lebih rendah)
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Sumber JSON Legacy (prioritas terendah)
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### Penyelesaian konflik
+
+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
+
+## Integrasi
+
+Berikut adalah pemetaan umum. Biarkan runtime Anda tetap tidak berubah; hanya tambahkan plugin.
+
+### i18next
+
+Tata letak file tipikal: `./public/locales/{locale}/{namespace}.json` atau `./locales/{locale}/{namespace}.json`.
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+};
+```
+
+### next-intl
+
+Pesan JSON per-locale (sering `./messages/{locale}.json`) atau per-namespace.
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
+  }),
+];
+```
+
+Lihat juga: `docs/id/intlayer_with_next-intl.md`.
+
+### react-intl
+
+JSON tunggal per locale adalah umum:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### vue-i18n
+
+Baik satu file per locale atau per-namespace:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
+  }),
+];
+```
+
+## CLI
+
+File JSON yang disinkronkan akan dianggap sebagai file `.content` lainnya. Artinya, semua perintah intlayer akan tersedia untuk file JSON yang disinkronkan. Termasuk:
+
+- `intlayer content test` untuk menguji apakah ada terjemahan yang hilang
+- `intlayer content list` untuk mendaftar file JSON yang disinkronkan
+- `intlayer content fill` untuk mengisi terjemahan yang hilang
+- `intlayer content push` untuk mengirim file JSON yang disinkronkan
+- `intlayer content pull` untuk menarik file JSON yang disinkronkan
+
+Lihat [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_cli.md) untuk detail lebih lanjut.
+
+## Keterbatasan (saat ini)
+
+- Tidak ada dukungan penyisipan atau bentuk jamak/ICU saat menargetkan pustaka pihak ketiga.
+- Editor visual belum tersedia untuk runtime non-Intlayer.
+- Sinkronisasi hanya untuk JSON; format katalog non-JSON tidak didukung.
+
+## Mengapa ini penting
+
+- Kami dapat merekomendasikan solusi i18n yang sudah mapan dan memposisikan Intlayer sebagai tambahan.
+- Kami memanfaatkan SEO/kata kunci mereka dengan tutorial yang berakhir dengan menyarankan Intlayer untuk mengelola JSON.
+- Memperluas audiens yang dapat dijangkau dari “proyek baru” menjadi “tim mana pun yang sudah menggunakan i18n”.

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

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+title: Plugin Sync JSON
+description: Sincronizza i dizionari Intlayer con file JSON i18n di terze parti (i18next, next-intl, react-intl, vue-i18n e altri). Mantieni il tuo i18n esistente mentre usi Intlayer per gestire, tradurre e testare i tuoi messaggi.
+keywords:
+  - Intlayer
+  - Sync JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - traduzioni
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: Documentazione iniziale del plugin Sync JSON
+---
+
+# Sync JSON (ponti i18n)
+
+Usa Intlayer come componente aggiuntivo al tuo stack i18n esistente. Questo plugin mantiene i tuoi messaggi JSON sincronizzati con i dizionari Intlayer così puoi:
+
+- Mantenere i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n, ecc.
+- Gestire e tradurre i tuoi messaggi con Intlayer (CLI, CI, provider, CMS), senza rifattorizzare la tua app.
+- Pubblicare tutorial e contenuti SEO mirati a ogni ecosistema, suggerendo Intlayer come livello di gestione JSON.
+
+Note e ambito attuale:
+
+- L’esternalizzazione verso il CMS funziona per traduzioni e testo classico.
+- Non è ancora supportato l’uso di inserimenti, plurali/ICU o funzionalità runtime avanzate di altre librerie.
+- L’editor visuale non è ancora supportato per output i18n di terze parti.
+
+### Quando usare questo plugin
+
+- Usi già una libreria i18n e memorizzi i messaggi in file JSON.
+- Vuoi un completamento assistito da AI, test in CI e operazioni sui contenuti senza modificare il runtime di rendering.
+
+## Installazione
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# oppure
+npm i -D @intlayer/sync-json-plugin
+```
+
+## Avvio rapido
+
+Aggiungi il plugin al tuo `intlayer.config.ts` e indirizzalo alla tua struttura JSON esistente.
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Mantieni i tuoi file JSON attuali sincronizzati con i dizionari Intlayer
+  plugins: [
+    syncJSON({
+      // Layout per locale, per namespace (es. next-intl, i18next con namespaces)
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+});
+```
+
+Alternativa: file singolo per locale (comune con configurazioni i18next/react-intl):
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### Come funziona
+
+- Lettura: il plugin individua i file JSON dal tuo builder `source` e li carica come dizionari Intlayer.
+- Scrittura: dopo le build e i riempimenti, scrive i JSON localizzati negli stessi percorsi (con una newline finale per evitare problemi di formattazione).
+- Auto‑fill: il plugin dichiara un percorso `autoFill` per ogni dizionario. Eseguendo `intlayer fill` aggiorna solo le traduzioni mancanti nei tuoi file JSON per impostazione predefinita.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // richiesto
+  location?: string, // etichetta opzionale, predefinito: "plugin"
+  priority?: number, // priorità opzionale per la risoluzione dei conflitti, predefinito: 0
+});
+```
+
+## Più sorgenti JSON e priorità
+
+Puoi aggiungere più plugin `syncJSON` per sincronizzare diverse sorgenti JSON. Questo è utile quando hai più librerie i18n o diverse strutture JSON nel tuo progetto.
+
+### Sistema di priorità
+
+Quando più plugin puntano alla stessa chiave del dizionario, il parametro `priority` determina quale plugin ha la precedenza:
+
+- I numeri di priorità più alti prevalgono su quelli più bassi
+- La priorità predefinita dei file `.content` è `0`
+- La priorità predefinita dei file di contenuto dei plugin è `-1`
+- I plugin con la stessa priorità vengono elaborati nell'ordine in cui appaiono nella configurazione
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Sorgente JSON primaria (priorità più alta)
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Sorgente JSON di fallback (priorità più bassa)
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Sorgente JSON legacy (priorità più bassa)
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### Risoluzione dei conflitti
+
+Quando la stessa chiave di traduzione esiste in più sorgenti JSON:
+
+1. Il plugin con la priorità più alta determina il valore finale
+2. Le sorgenti con priorità inferiore vengono usate come fallback per le chiavi mancanti
+3. Questo permette di mantenere le traduzioni legacy mentre si migra gradualmente verso nuove strutture
+
+## Integrazioni
+
+Di seguito sono riportate le mappature comuni. Mantieni il tuo runtime intatto; aggiungi solo il plugin.
+
+### i18next
+
+Layout tipico dei file: `./public/locales/{locale}/{namespace}.json` o `./locales/{locale}/{namespace}.json`.
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+};
+```
+
+### next-intl
+
+Messaggi JSON per locale (spesso `./messages/{locale}.json`) o per namespace.
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
+  }),
+];
+```
+
+Vedi anche: `docs/it/intlayer_with_next-intl.md`.
+
+### react-intl
+
+È comune un singolo JSON per locale:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### vue-i18n
+
+Può essere un singolo file per locale o per namespace:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
+  }),
+];
+```
+
+## CLI
+
+I file JSON sincronizzati saranno considerati come altri file `.content`. Ciò significa che tutti i comandi di intlayer saranno disponibili per i file JSON sincronizzati. Inclusi:
+
+- `intlayer content test` per verificare se ci sono traduzioni mancanti
+- `intlayer content list` per elencare i file JSON sincronizzati
+- `intlayer content fill` per completare le traduzioni mancanti
+- `intlayer content push` per inviare i file JSON sincronizzati
+- `intlayer content pull` per scaricare i file JSON sincronizzati
+
+Vedi [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_cli.md) per maggiori dettagli.
+
+## Limitazioni (attuali)
+
+- Nessun supporto per inserimenti o plurali/ICU quando si utilizzano librerie di terze parti.
+- L'editor visuale non è ancora disponibile per runtime non Intlayer.
+- Sincronizzazione solo di file JSON; i formati di catalogo non JSON non sono supportati.
+
+## Perché è importante
+
+- Possiamo raccomandare soluzioni i18n consolidate e posizionare Intlayer come un componente aggiuntivo.
+- Sfruttiamo la loro SEO/parole chiave con tutorial che terminano suggerendo Intlayer per gestire JSON.
+- Espande il pubblico indirizzabile da “nuovi progetti” a “qualsiasi team che utilizza già i18n”.