@intlayer/docs 8.9.4-canary.0 → 8.9.4

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

@@ -0,0 +1,354 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Plugin Sync PO
+description: Sincronizza i dizionari Intlayer con i file Gettext PO. Mantieni la tua i18n esistente utilizzando Intlayer per gestire, tradurre e testare i tuoi messaggi.
+keywords:
+  - Intlayer
+  - Sync PO
+  - Gettext
+  - i18n
+  - traduzioni
+slugs:
+  - doc
+  - plugin
+  - sync-po
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 8.9.4
+    date: 2026-05-10
+    changes: "Documentazione iniziale del plugin Sync PO"
+---
+
+# Sync PO (ponti i18n) - Sync PO con supporto ICU / i18next
+
+Usa Intlayer come componente aggiuntivo per il tuo stack i18n esistente. Questo plugin mantiene i tuoi messaggi Gettext PO sincronizzati con i dizionari Intlayer in modo da poter:
+
+- Mantenere il tuo attuale workflow di traduzione basato su PO.
+- Gestire e tradurre i tuoi messaggi con Intlayer (CLI, CI, provider, CMS), senza rifattorizzare la tua app.
+- Distribuire tutorial e contenuti SEO mirati a ciascun ecosistema, suggerendo Intlayer come livello di gestione PO.
+
+Note e ambito attuale:
+
+- L'esternalizzazione al CMS funziona per le traduzioni e il testo classico.
+- Non c'è ancora supporto per inserimenti, plurali/ICU o funzionalità avanzate di runtime di altre librerie all'interno delle voci PO stesse.
+- L'editor visuale non è ancora supportato per gli output i18n di terze parti.
+
+### Quando usare questo plugin
+
+- Usi già i file Gettext PO per le tue traduzioni.
+- Desideri il riempimento assistito da IA, i test in CI e le operazioni sui contenuti senza modificare il runtime di rendering.
+
+## Installazione
+
+```bash
+pnpm add -D @intlayer/sync-po-plugin
+# oppure
+npm i -D @intlayer/sync-po-plugin
+```
+
+## Plugin
+
+Questo pacchetto fornisce due plugin:
+
+- `loadPO`: Carica i file PO nei dizionari Intlayer.
+  - Questo plugin viene utilizzato per caricare file PO da una sorgente e verranno inseriti nei dizionari Intlayer. Può scansionare l'intera base di codice e cercare file PO specifici.
+    Questo plugin può essere utilizzato:
+    - se utilizzi una libreria i18n che impone una posizione specifica per il caricamento dei tuoi file PO, ma vuoi posizionare la tua dichiarazione di contenuto dove preferisci nella tua base di codice.
+    - Può essere utilizzato anche se vuoi recuperare i tuoi messaggi da una sorgente remota (es: un CMS, un'API, ecc.) e memorizzare i tuoi messaggi in file PO.
+
+  > Sotto il cofano, questo plugin scansionerà tutta la base di codice, cercherà file PO specifici e li caricherà nei dizionari Intlayer.
+  > Nota che questo plugin non scriverà l'output e le traduzioni nei file PO.
+
+- `syncPO`: Sincronizza i file PO con i dizionari Intlayer.
+  - Questo plugin viene utilizzato per sincronizzare i file PO con i dizionari Intlayer. Può scansionare la posizione specificata e caricare i PO che corrispondono al pattern per file PO specifici. Questo plugin è utile se vuoi ottenere i vantaggi di Intlayer utilizzando un'altra libreria i18n.
+
+## Utilizzo di entrambi i 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,
+  },
+
+  // Mantieni i tuoi attuali file PO sincronizzati con i dizionari Intlayer
+  plugins: [
+    /**
+     * Caricherà tutti i file PO in src che corrispondono al pattern {key}.i18n.po
+     */
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Assicura che questi file PO abbiano la precedenza sui file in `./locales/en/${key}.po`
+    }),
+    /**
+     * Caricherà e scriverà l'output e le traduzioni nei file PO nella directory locales
+     */
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin `syncPO`
+
+### Avvio rapido
+
+Aggiungi il plugin al tuo `intlayer.config.ts` e puntalo alla tua struttura PO esistente.
+
+```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,
+  },
+
+  // Mantieni i tuoi attuali file PO sincronizzati con i dizionari Intlayer
+  plugins: [
+    syncPO({
+      // Layout per lingua e per namespace
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternativa: file singolo per lingua:
+
+```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;
+```
+
+#### Come funziona
+
+- Lettura: il plugin scopre i file PO dal tuo costruttore `source` e li carica come dizionari Intlayer.
+- Scrittura: dopo le build e i riempimenti, scrive i PO localizzati negli stessi percorsi (con gli header Gettext appropriati).
+- Riempimento automatico: il plugin dichiara un percorso `autoFill` per ogni dizionario. L'esecuzione di `intlayer fill` aggiorna per impostazione predefinita solo le traduzioni mancanti nei tuoi file PO.
+
+API:
+
+```ts
+syncPO({
+  source: ({ key, locale }) => string, // richiesto
+  location?: string, // etichetta opzionale, default: "sync-po::path/to/source"
+  priority?: number, // priorità opzionale per la risoluzione dei conflitti, default: 0
+  format?: 'icu' | 'i18next' | 'vue-i18n', // opzionale, necessario solo quando i valori msgstr utilizzano una specifica sintassi di interpolazione
+});
+```
+
+#### `format` ('icu' | 'i18next' | 'vue-i18n')
+
+I file PO sono sempre file Gettext Portable Object — questo è fisso. Questa opzione descrive solo la **sintassi di interpolazione** utilizzata all'interno dei valori `msgstr`, in modo che Intlayer possa convertirli nel proprio formato al momento del parsing (tramite `formatDictionary`) e viceversa durante la scrittura dell'output.
+
+- `undefined` _(default)_: i valori `msgstr` sono trattati come stringhe semplici — nessuna trasformazione. Usa questo per la maggior parte dei file PO.
+- `'icu'`: i valori `msgstr` utilizzano la sintassi dei messaggi ICU (es. `{count, plural, one {# item} other {# items}}`).
+- `'i18next'`: i valori `msgstr` utilizzano la sintassi di interpolazione i18next (es. `{{variable}}`).
+- `'vue-i18n'`: i valori `msgstr` utilizzano la sintassi Vue I18n.
+
+> La trasformazione è applicata da `formatDictionary` di `@intlayer/chokidar` al caricamento e invertita con `formatDictionaryOutput` alla scrittura. Per regole complesse come i plurali ICU, la fedeltà del round-trip non è garantita.
+
+**Esempio — i file PO contengono interpolazione in stile i18next:**
+
+```ts
+syncPO({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+  format: "i18next",
+}),
+```
+
+### Sorgenti PO multiple e priorità
+
+Puoi aggiungere più plugin `syncPO` per sincronizzare diverse sorgenti PO. Questo è utile quando hai più sorgenti di traduzione o diverse strutture PO 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 vincono su quelli più bassi
+- La priorità predefinita dei file `.content` è `0`
+- La priorità predefinita dei plugin è `0`
+- I plugin con la stessa priorità vengono elaborati nell'ordine in cui appaiono nella configurazione
+
+```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: [
+    // Sorgente PO primaria (priorità massima)
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Sorgente PO di fallback (priorità inferiore)
+    syncPO({
+      source: ({ locale }) => `./fallback-locales/${locale}.po`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Sorgente PO legacy (priorità minima)
+    syncPO({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.po`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin Load PO
+
+### Avvio rapido
+
+Aggiungi il plugin al tuo `intlayer.config.ts` per ingerire file PO esistenti come dizionari Intlayer. Questo plugin è di sola lettura (nessuna scrittura su disco):
+
+```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: [
+    // Ingerisci i messaggi PO situati ovunque nel tuo albero dei sorgenti
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      // Carica una singola lingua per istanza di plugin (impostata di default sulla defaultLocale della configurazione)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternativa: layout per lingua, ancora di sola lettura (viene caricata solo la lingua selezionata):
+
+```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({
+      // Solo i file per Locales.FRENCH verranno caricati da questo pattern
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### Come funziona
+
+- Scoperta: costruisce un glob dal tuo costruttore `source` e raccoglie i file PO corrispondenti.
+- Ingestione: carica ogni file PO come dizionario Intlayer con la `locale` fornita.
+- Sola lettura: non scrive né formatta i file di output; usa `syncPO` se hai bisogno della sincronizzazione round-trip.
+- Pronto per il riempimento automatico: definisce un percorso `fill` in modo che `intlayer content fill` possa popolare le chiavi mancanti.
+
+### API
+
+```ts
+loadPO({
+  // Costruisce i percorsi per i tuoi PO. `locale` è opzionale se la tua struttura non ha un segmento per la lingua
+  source: ({ key, locale }) => string,
+
+  // Lingua di destinazione per i dizionari caricati da questa istanza di plugin
+  // Di default configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Etichetta opzionale per identificare la sorgente
+  location?: string, // default: "plugin"
+
+  // Priorità utilizzata per la risoluzione dei conflitti con altre sorgenti
+  priority?: number, // default: 0
+});
+```
+
+### Comportamento e convenzioni
+
+- Se la tua maschera `source` include un segnaposto per la lingua, vengono ingeriti solo i file per la `locale` selezionata.
+- Se non c'è un segmento `{key}` nella tua maschera, la chiave del dizionario è "index".
+- Le chiavi sono derivate dai percorsi dei file sostituendo il segnaposto `{key}` nel tuo costruttore `source`.
+- Il plugin utilizza solo i file scoperti e non fabbrica lingue o chiavi mancanti.
+- Il percorso `fill` è dedotto dalla tua `source` e utilizzato per aggiornare i valori mancanti tramite CLI quando acconsenti.
+
+## Risoluzione dei conflitti
+
+Quando la stessa chiave di traduzione esiste in più sorgenti PO:
+
+1. Il plugin con la priorità più alta determina il valore finale
+2. Le sorgenti con priorità inferiore vengono utilizzate come fallback per le chiavi mancanti
+3. Questo ti consente di mantenere le traduzioni legacy mentre migri gradualmente verso nuove strutture
+
+## CLI
+
+I file PO sincronizzati saranno considerati come gli altri file `.content`. Ciò significa che tutti i comandi intlayer saranno disponibili per i file PO sincronizzati. Inclusi:
+
+- `intlayer content test` per testare se mancano traduzioni
+- `intlayer content list` per elencare i file PO sincronizzati
+- `intlayer content fill` per riempire le traduzioni mancanti
+- `intlayer content push` per inviare i file PO sincronizzati
+- `intlayer content pull` per recuperare i file PO sincronizzati
+
+Vedi [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md) per maggiori dettagli.
+
+## Limitazioni (attuali)
+
+- Nessun supporto per inserimenti o plurali/ICU quando si puntano librerie di terze parti.
+- L'editor visuale non è ancora disponibile per runtime diversi da Intlayer.
+- Solo sincronizzazione PO; i formati di catalogo non-PO non sono supportati.
+
+## Perché è importante
+
+- Possiamo raccomandare soluzioni i18n consolidate e posizionare Intlayer come componente aggiuntivo.
+- Sfruttiamo la loro SEO/parole chiave con tutorial che terminano suggerendo Intlayer per gestire i PO.
+- Espande il pubblico potenziale dai "nuovi progetti" a "qualsiasi team che utilizzi già i18n".

package/docs/ja/mcp_server.md

@@ -51,12 +51,12 @@ Intlayer MCPサーバーをIDEで有効にすると、以下の機能が利用
 
   > コマンドとオプションの完全なリストは、[Intlayer CLIドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/index.md)でご覧ください。
 
-## ローカルサーバー（stdio）とリモートサーバー（SSE）
+## ローカルサーバー（stdio）とリモートサーバー（Streamable HTTP）
 
 MCPサーバーは以下の2つの方法で使用できます：
 
 - ローカルサーバー（stdio）
-- リモートサーバー（SSE）
+- リモートサーバー（Streamable HTTP）
 
 ### ローカルサーバー（stdio）（推奨）
 
@@ -64,7 +64,7 @@ Intlayerは、あなたのマシンにローカルインストールできるNPM
 
 このサーバーはMCPサーバーを使用する推奨方法です。CLIツールを含むMCPサーバーのすべての機能が統合されています。
 
-### リモートサーバー（SSE）
+### リモートサーバー（Streamable HTTP）
 
 MCPサーバーはSSEトランスポート方式を使用してリモートでも利用可能です。このサーバーはIntlayerによってホストされており、https://mcp.intlayer.org で利用できます。このサーバーは認証不要で公開アクセス可能で、無料で使用できます。
 
@@ -97,7 +97,7 @@ bun x intlayer init mcp
 このコマンドは以下のことを行います：
 
 1. 使用しているプラットフォーム（Cursor、VS Code、Claude Desktopなど）を尋ねます。
-2. 使用するトランスポート方法（ローカルサーバー (stdio) またはリモートサーバー (SSE)）を尋ねます。
+2. 使用するトランスポート方法（ローカルサーバー (stdio) またはリモートサーバー (Streamable HTTP)）を尋ねます。
 3. 構成ファイル（例：`.cursor/mcp.json`、`.vscode/mcp.json`、またはグローバルなClaude Desktop構成）を自動的に更新します。
 
 ---
@@ -107,7 +107,7 @@ bun x intlayer init mcp
 1. コマンドパレットを開きます（Ctrl+Shift+P または Cmd+Shift+P）。
 2. `Intlayer: Setup AI Agent Skills` と入力します。
 3. 使用するプラットフォームを選択します（例：`VS Code`、`Cursor`、`Windsurf`、`OpenCode`、`Claude Code`、`GitHub Copilot Workspace` など）。
-4. インストールするMCPを選択します（stdio、SSE）。
+4. インストールするMCPを選択します（stdio、Streamable HTTP）。
 5. Enterキーを押します。
 
 ---
@@ -131,16 +131,16 @@ CursorでMCPサーバーを設定するには、[公式ドキュメント](https
 }
 ```
 
-### リモートサーバー（SSE）
+### リモートサーバー（Streamable HTTP）
 
-Server-Sent Events（SSE）を使用してリモートのIntlayer MCPサーバーに接続するには、ホストされているサービスに接続するようにMCPクライアントを設定できます。
+Server-Sent Events（Streamable HTTP）を使用してリモートのIntlayer MCPサーバーに接続するには、ホストされているサービスに接続するようにMCPクライアントを設定できます。
 
 ```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 @@ VS CodeでIntlayer MCPサーバーを使用するには、ワークスペース
 }
 ```
 
-### リモートサーバー（SSE）
+### リモートサーバー（Streamable HTTP）
 
-Server-Sent Events（SSE）を使用してリモートの Intlayer MCP サーバーに接続する場合、MCP クライアントをホストされているサービスに接続するように設定できます。
+Server-Sent Events（Streamable HTTP）を使用してリモートの Intlayer MCP サーバーに接続する場合、MCP クライアントをホストされているサービスに接続するように設定できます。
 
 ```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 @@ Server-Sent Events（SSE）を使用してリモートの Intlayer MCP サーバ
 
 ## ChatGPT でのセットアップ
 
-### リモートサーバー（SSE）
+### リモートサーバー（Streamable HTTP）
 
 ChatGPT で MCP サーバーを設定するには、[公式ドキュメント](https://platform.openai.com/docs/mcp#test-and-connect-your-mcp-server)に従ってください。
 
@@ -232,6 +232,19 @@ ChatGPT で MCP サーバーを設定するには、[公式ドキュメント](h
 }
 ```
 
+### リモートサーバー（Streamable HTTP）
+
+```json fileName="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
+    }
+  }
+}
+```
+
 ---
 
 ## CLIを使ったMCPサーバーの利用