@intlayer/docs 8.9.4-canary.0 → 8.9.4

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

@@ -0,0 +1,354 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Plugin Sync PO
+description: Sinkronkan kamus Intlayer dengan file Gettext PO. Pertahankan i18n Anda yang sudah ada sambil menggunakan Intlayer untuk mengelola, menerjemahkan, dan menguji pesan Anda.
+keywords:
+  - Intlayer
+  - Sync PO
+  - Gettext
+  - i18n
+  - terjemahan
+slugs:
+  - doc
+  - plugin
+  - sync-po
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 8.9.4
+    date: 2026-05-10
+    changes: "Dokumentasi awal plugin Sync PO"
+---
+
+# Sync PO (jembatan i18n) - Sync PO dengan dukungan ICU / i18next
+
+Gunakan Intlayer sebagai tambahan untuk stack i18n Anda yang sudah ada. Plugin ini menjaga pesan Gettext PO Anda tetap sinkron dengan kamus Intlayer sehingga Anda dapat:
+
+- Mempertahankan alur kerja terjemahan berbasis PO yang sudah ada.
+- Mengelola dan menerjemahkan pesan Anda dengan Intlayer (CLI, CI, penyedia, CMS), tanpa merombak aplikasi Anda.
+- Mengirimkan tutorial dan konten SEO yang menargetkan setiap ekosistem, sambil menyarankan Intlayer sebagai lapisan manajemen PO.
+
+Catatan dan cakupan saat ini:
+
+- Eksternalisasi ke CMS berfungsi untuk terjemahan dan teks klasik.
+- Belum ada dukungan untuk penyisipan, jamak/ICU, atau fitur runtime lanjutan dari pustaka lain di dalam entri PO itu sendiri.
+- Editor visual belum didukung untuk output i18n pihak ketiga.
+
+### Kapan menggunakan plugin ini
+
+- Anda sudah menggunakan file Gettext PO untuk terjemahan Anda.
+- Anda ingin pengisian berbantuan AI, pengujian di CI, dan operasi konten tanpa mengubah runtime rendering Anda.
+
+## Instalasi
+
+```bash
+pnpm add -D @intlayer/sync-po-plugin
+# atau
+npm i -D @intlayer/sync-po-plugin
+```
+
+## Plugin
+
+Paket ini menyediakan dua plugin:
+
+- `loadPO`: Memuat file PO ke dalam kamus Intlayer.
+  - Plugin ini digunakan untuk memuat file PO dari sumber dan akan dimuat ke dalam kamus Intlayer. Ini dapat memindai semua basis kode dan mencari file PO tertentu.
+    Plugin ini dapat digunakan:
+    - jika Anda menggunakan pustaka i18n yang mengharuskan lokasi tertentu untuk file PO Anda dimuat, tetapi Anda ingin menempatkan deklarasi konten di mana pun Anda inginkan dalam basis kode Anda.
+    - Ini juga dapat digunakan jika Anda ingin mengambil pesan Anda dari sumber jarak jauh (misalnya: CMS, API, dll.) dan menyimpan pesan Anda dalam file PO.
+
+  > Di balik layar, plugin ini akan memindai semua basis kode dan mencari file PO tertentu serta memuatnya ke dalam kamus Intlayer.
+  > Perhatikan bahwa plugin ini tidak akan menulis output dan terjemahan kembali ke file PO.
+
+- `syncPO`: Sinkronkan file PO dengan kamus Intlayer.
+  - Plugin ini digunakan untuk menyinkronkan file PO dengan kamus Intlayer. Ini dapat memindai lokasi yang diberikan dan memuat PO yang cocok dengan pola untuk file PO tertentu. Plugin ini berguna jika Anda ingin mendapatkan manfaat Intlayer sambil menggunakan pustaka i18n lain.
+
+## Menggunakan kedua plugin
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO, syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Jaga agar file PO Anda saat ini tetap sinkron dengan kamus Intlayer
+  plugins: [
+    /**
+     * Akan memuat semua file PO di src yang cocok dengan pola {key}.i18n.po
+     */
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Memastikan file PO ini lebih diutamakan daripada file di `./locales/en/${key}.po`
+    }),
+    /**
+     * Akan memuat, dan menulis output dan terjemahan kembali ke file PO di direktori locales
+     */
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin `syncPO`
+
+### Mulai cepat
+
+Tambahkan plugin ke `intlayer.config.ts` Anda dan arahkan ke struktur PO Anda yang sudah ada.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Jaga agar file PO Anda saat ini tetap sinkron dengan kamus Intlayer
+  plugins: [
+    syncPO({
+      // Tata letak per-lokal, per-namespace
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternatif: satu file per lokal:
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncPO({
+      source: ({ locale }) => `./locales/${locale}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+#### Cara kerjanya
+
+- Baca: plugin menemukan file PO dari pembangun `source` Anda dan memuatnya sebagai kamus Intlayer.
+- Tulis: setelah pembangunan dan pengisian, ia menulis PO yang dilokalkan kembali ke jalur yang sama (dengan header Gettext yang tepat).
+- Pengisian otomatis: plugin mendeklarasikan jalur `autoFill` untuk setiap kamus. Menjalankan `intlayer fill` memperbarui hanya terjemahan yang hilang di file PO Anda secara default.
+
+API:
+
+```ts
+syncPO({
+  source: ({ key, locale }) => string, // wajib
+  location?: string, // label opsional, default: "sync-po::path/to/source"
+  priority?: number, // prioritas opsional untuk resolusi konflik, default: 0
+  format?: 'icu' | 'i18next' | 'vue-i18n', // opsional, hanya diperlukan jika nilai msgstr Anda menggunakan sintaks interpolasi tertentu
+});
+```
+
+#### `format` ('icu' | 'i18next' | 'vue-i18n')
+
+File PO selalu berupa file Gettext Portable Object — itu sudah tetap. Opsi ini hanya menjelaskan **sintaks interpolasi** yang digunakan di dalam nilai `msgstr`, sehingga Intlayer dapat mengonversinya ke formatnya sendiri pada saat penguraian (melalui `formatDictionary`) dan kembali saat menulis output.
+
+- `undefined` _(default)_: nilai `msgstr` diperlakukan sebagai string biasa — tidak ada transformasi. Gunakan ini untuk sebagian besar file PO.
+- `'icu'`: nilai `msgstr` menggunakan sintaks pesan ICU (misalnya `{count, plural, one {# item} other {# items}}`).
+- `'i18next'`: nilai `msgstr` menggunakan sintaks interpolasi i18next (misalnya `{{variable}}`).
+- `'vue-i18n'`: nilai `msgstr` menggunakan sintaks Vue I18n.
+
+> Transformasi diterapkan oleh `formatDictionary` dari `@intlayer/chokidar` pada saat pemuatan, dan dibalik dengan `formatDictionaryOutput` pada saat penulisan. Untuk aturan kompleks seperti jamak ICU, kesetiaan bolak-balik tidak dijamin.
+
+**Contoh — file PO berisi interpolasi gaya i18next:**
+
+```ts
+syncPO({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+  format: "i18next",
+}),
+```
+
+### Beberapa sumber PO dan prioritas
+
+Anda dapat menambahkan beberapa plugin `syncPO` untuk menyinkronkan sumber PO yang berbeda. Ini berguna ketika Anda memiliki beberapa sumber terjemahan atau struktur PO yang berbeda dalam proyek Anda.
+
+#### Sistem prioritas
+
+Ketika beberapa plugin menargetkan kunci kamus yang sama, parameter `priority` menentukan plugin mana yang lebih diutamakan:
+
+- Nomor prioritas yang lebih tinggi menang atas yang lebih rendah
+- Prioritas default file `.content` adalah `0`
+- Prioritas default plugin adalah `0`
+- Plugin dengan prioritas yang sama diproses sesuai urutan kemunculannya dalam konfigurasi
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Sumber PO utama (prioritas tertinggi)
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Sumber PO cadangan (prioritas lebih rendah)
+    syncPO({
+      source: ({ locale }) => `./fallback-locales/${locale}.po`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Sumber PO lama (prioritas terendah)
+    syncPO({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.po`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin Load PO
+
+### Mulai cepat
+
+Tambahkan plugin ke `intlayer.config.ts` Anda untuk memasukkan file PO yang ada sebagai kamus Intlayer. Plugin ini bersifat baca-saja (tidak ada penulisan ke disk):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Masukkan pesan PO yang terletak di mana saja di pohon sumber Anda
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      // Muat satu lokal per instansi plugin (default ke defaultLocale konfigurasi)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternatif: tata letak per-lokal, masih baca-saja (hanya lokal yang dipilih yang dimuat):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    loadPO({
+      // Hanya file untuk Locales.FRENCH yang akan dimuat dari pola ini
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### Cara kerjanya
+
+- Temukan: membangun glob dari pembangun `source` Anda dan mengumpulkan file PO yang cocok.
+- Masukkan: memuat setiap file PO sebagai kamus Intlayer dengan `locale` yang disediakan.
+- Baca-saja: tidak menulis atau memformat file output; gunakan `syncPO` jika Anda memerlukan sinkronisasi bolak-balik.
+- Siap pengisian otomatis: menentukan jalur `fill` sehingga `intlayer content fill` dapat mengisi kunci yang hilang.
+
+### API
+
+```ts
+loadPO({
+  // Bangun jalur ke PO Anda. `locale` bersifat opsional jika struktur Anda tidak memiliki segmen lokal
+  source: ({ key, locale }) => string,
+
+  // Lokal target untuk kamus yang dimuat oleh instansi 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
+});
+```
+
+### Perilaku dan konvensi
+
+- Jika mask `source` Anda menyertakan placeholder lokal, hanya file untuk `locale` yang dipilih yang dimasukkan.
+- Jika tidak ada segmen `{key}` di mask Anda, kunci kamus adalah "index".
+- Kunci diturunkan dari jalur file dengan mengganti placeholder `{key}` di pembangun `source` Anda.
+- Plugin hanya menggunakan file yang ditemukan dan tidak membuat lokal atau kunci yang hilang.
+- Jalur `fill` disimpulkan dari `source` Anda dan digunakan untuk memperbarui nilai yang hilang melalui CLI saat Anda memilih untuk ikut serta.
+
+## Resolusi konflik
+
+Ketika kunci terjemahan yang sama ada di beberapa sumber PO:
+
+1. Plugin dengan prioritas tertinggi menentukan nilai akhir
+2. Sumber prioritas lebih rendah digunakan sebagai cadangan untuk kunci yang hilang
+3. Ini memungkinkan Anda untuk mempertahankan terjemahan lama sambil secara bertahap bermigrasi ke struktur baru
+
+## CLI
+
+File PO yang disinkronkan akan dianggap sebagai file `.content` lainnya. Itu berarti, semua perintah intlayer akan tersedia untuk file PO yang disinkronkan. Termasuk:
+
+- `intlayer content test` untuk menguji apakah ada terjemahan yang hilang
+- `intlayer content list` untuk mencantumkan file PO yang disinkronkan
+- `intlayer content fill` untuk mengisi terjemahan yang hilang
+- `intlayer content push` untuk mendorong file PO yang disinkronkan
+- `intlayer content pull` untuk menarik file PO yang disinkronkan
+
+Lihat [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md) untuk detail lebih lanjut.
+
+## Batasan (saat ini)
+
+- Tidak ada dukungan penyisipan atau jamak/ICU saat menargetkan pustaka pihak ketiga.
+- Editor visual belum tersedia untuk runtime non-Intlayer.
+- Hanya sinkronisasi PO; format katalog non-PO 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 diakhiri dengan menyarankan Intlayer untuk mengelola PO.
+- Memperluas audiens yang dapat dituju dari "proyek baru" menjadi "tim mana pun yang sudah menggunakan i18n".

package/docs/it/mcp_server.md

@@ -23,7 +23,7 @@ history:
     changes: "Aggiunta configurazione di Claude Desktop"
   - version: 5.5.12
     date: 2025-07-10
-    changes: "Aggiunto trasporto SSE e server remoto"
+    changes: "Aggiunto trasporto Streamable HTTP e server remoto"
   - version: 5.5.10
     date: 2025-06-29
     changes: "Inizializzazione della cronologia"
@@ -51,12 +51,12 @@ Abilitando il Server MCP di Intlayer nel tuo IDE, sblocchi:
 
   > Visualizza l'elenco completo dei comandi e delle opzioni nella [documentazione CLI di Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/index.md).
 
-## Server locale (stdio) vs Server remoto (SSE)
+## Server locale (stdio) vs Server remoto (Streamable HTTP)
 
 Il server MCP può essere utilizzato in due modi:
 
 - Server locale (stdio)
-- Server remoto (SSE)
+- Server remoto (Streamable HTTP)
 
 ### Server locale (stdio) (consigliato)
 
@@ -64,7 +64,7 @@ Intlayer fornisce un pacchetto NPM che può essere installato localmente sulla t
 
 Questo server è il modo consigliato per utilizzare il server MCP, in quanto integra tutte le funzionalità del server MCP, inclusi gli strumenti CLI.
 
-### Server remoto (SSE)
+### Server remoto (Streamable HTTP)
 
 Il server MCP può essere utilizzato anche da remoto, utilizzando il metodo di trasporto SSE. Questo server è ospitato da Intlayer ed è disponibile all'indirizzo https://mcp.intlayer.org. Questo server è accessibile pubblicamente, senza alcuna autenticazione, ed è gratuito.
 
@@ -97,7 +97,7 @@ bun x intlayer init mcp
 Questo comando permetterà di:
 
 1. Chiederti quale piattaforma stai utilizzando (Cursor, VS Code, Claude Desktop, ecc.).
-2. Chiederti quale metodo di trasporto vuoi utilizzare (Server locale (stdio) o Server remoto (SSE)).
+2. Chiederti quale metodo di trasporto vuoi utilizzare (Server locale (stdio) o Server remoto (Streamable HTTP)).
 3. Aggiornare automaticamente il tuo file di configurazione (ad esempio, `.cursor/mcp.json`, `.vscode/mcp.json` o la configurazione globale di Claude Desktop).
 
 ---
@@ -107,7 +107,7 @@ Questo comando permetterà di:
 1. Apri la tavolozza dei comandi (Ctrl+Shift+P o Cmd+Shift+P).
 2. Digita `Intlayer: Setup AI Agent Skills`
 3. Scegli la piattaforma che utilizzi (es. `VS Code`, `Cursor`, `Windsurf`, `OpenCode`, `Claude Code`, `GitHub Copilot Workspace`, ecc.).
-4. Scegli l'MCP da installare (stdio, SSE)
+4. Scegli l'MCP da installare (stdio, Streamable HTTP)
 5. Premi Invio.
 
 ---
@@ -131,16 +131,16 @@ Nella radice del tuo progetto, aggiungi il seguente file di configurazione `.cur
 }
 ```
 
-### Server remoto (SSE)
+### Server remoto (Streamable HTTP)
 
-Per connettersi a un server MCP Intlayer remoto utilizzando Server-Sent Events (SSE), puoi configurare il tuo client MCP per connettersi al servizio ospitato.
+Per connettersi a un server MCP Intlayer remoto utilizzando Server-Sent Events (Streamable HTTP), puoi configurare il tuo client MCP per connettersi al servizio ospitato.
 
 ```json fileName=".cursor/mcp.json"
 {
   "mcpServers": {
-    "intlayer": {
-      "url": "https://mcp.intlayer.org",
-      "transport": "sse"
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
     }
   }
 }
@@ -172,16 +172,16 @@ Crea un file `.vscode/mcp.json` nella radice del tuo progetto:
 }
 ```
 
-### Server remoto (SSE)
+### Server remoto (Streamable HTTP)
 
-Per connettersi a un server MCP Intlayer remoto utilizzando Server-Sent Events (SSE), puoi configurare il tuo client MCP per connettersi al servizio ospitato.
+Per connettersi a un server MCP Intlayer remoto utilizzando Server-Sent Events (Streamable HTTP), puoi configurare il tuo client MCP per connettersi al servizio ospitato.
 
 ```json fileName=".vscode/mcp.json"
 {
   "servers": {
-    "intlayer": {
-      "url": "https://mcp.intlayer.org",
-      "type": "sse"
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
     }
   }
 }
@@ -191,7 +191,7 @@ Per connettersi a un server MCP Intlayer remoto utilizzando Server-Sent Events (
 
 ## Configurazione in ChatGPT
 
-### Server remoto (SSE)
+### Server remoto (Streamable HTTP)
 
 Segui la [documentazione ufficiale](https://platform.openai.com/docs/mcp#test-and-connect-your-mcp-server) per configurare il server MCP in ChatGPT.
 
@@ -232,6 +232,19 @@ Percorso del file di configurazione:
 }
 ```
 
+### Server remoto (Streamable HTTP)
+
+```json fileName="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
+    }
+  }
+}
+```
+
 ---
 
 ## Utilizzo del Server MCP tramite CLI