@intlayer/docs 8.9.4-canary.0 → 8.9.4

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

@@ -0,0 +1,354 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Plugin Sync PO
+description: Synchronizuj słowniki Intlayer z plikami Gettext PO. Zachowaj istniejące i18n, używając Intlayer do zarządzania, tłumaczenia i testowania swoich komunikatów.
+keywords:
+  - Intlayer
+  - Sync PO
+  - Gettext
+  - i18n
+  - tłumaczenia
+slugs:
+  - doc
+  - plugin
+  - sync-po
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 8.9.4
+    date: 2026-05-10
+    changes: "Początkowa dokumentacja pluginu Sync PO"
+---
+
+# Sync PO (mosty i18n) - Sync PO ze wsparciem ICU / i18next
+
+Używaj Intlayer jako dodatku do swojego istniejącego stosu i18n. Ten plugin utrzymuje synchronizację komunikatów Gettext PO ze słownikami Intlayer, dzięki czemu możesz:
+
+- Zachować istniejący przepływ pracy tłumaczeń oparty na plikach PO.
+- Zarządzać i tłumaczyć swoje komunikaty za pomocą Intlayer (CLI, CI, dostawcy, CMS), bez refaktoryzacji aplikacji.
+- Dostarczać samouczki i treści SEO skierowane do każdego ekosystemu, sugerując Intlayer jako warstwę zarządzania plikami PO.
+
+Uwagi i aktualny zakres:
+
+- Externalizacja do CMS działa dla tłumaczeń i klasycznego tekstu.
+- Brak jeszcze wsparcia dla wstawek, liczb mnogich/ICU lub zaawansowanych funkcji runtime innych bibliotek wewnątrz samych wpisów PO.
+- Edytor wizualny nie jest jeszcze wspierany dla wyjść i18n firm trzecich.
+
+### Kiedy używać tego pluginu
+
+- Używasz już plików Gettext PO do swoich tłumaczeń.
+- Chcesz korzystać z wypełniania wspomaganego przez AI, testów w CI i operacji na treści bez zmiany swojego runtime'u renderowania.
+
+## Instalacja
+
+```bash
+pnpm add -D @intlayer/sync-po-plugin
+# lub
+npm i -D @intlayer/sync-po-plugin
+```
+
+## Pluginy
+
+Ten pakiet dostarcza dwa pluginy:
+
+- `loadPO`: Ładuje pliki PO do słowników Intlayer.
+  - Ten plugin służy do ładowania plików PO ze źródła i zostaną one wczytane do słowników Intlayer. Może on przeszukiwać całą bazę kodu w poszukiwaniu konkretnych plików PO.
+    Plugin ten może być używany:
+    - jeśli używasz biblioteki i18n, która narzuca określoną lokalizację dla ładowania plików PO, ale chcesz umieścić swoją deklarację treści w dowolnym miejscu w swojej bazie kodu.
+    - Może być również używany, jeśli chcesz pobierać komunikaty ze zdalnego źródła (np. CMS, API itp.) i przechowywać je w plikach PO.
+
+  > Pod maską ten plugin przeszuka całą bazę kodu, znajdzie konkretne pliki PO i załaduje je do słowników Intlayer.
+  > Pamiętaj, że ten plugin nie będzie zapisywał wyników i tłumaczeń z powrotem do plików PO.
+
+- `syncPO`: Synchronizuje pliki PO ze słownikami Intlayer.
+  - Ten plugin służy do synchronizacji plików PO ze słownikami Intlayer. Może on przeszukiwać podaną lokalizację i ładować pliki PO pasujące do wzorca. Plugin ten jest przydatny, jeśli chcesz czerpać korzyści z Intlayer, korzystając jednocześnie z innej biblioteki i18n.
+
+## Używanie obu pluginów
+
+```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,
+  },
+
+  // Utrzymuj synchronizację aktualnych plików PO ze słownikami Intlayer
+  plugins: [
+    /**
+     * Załaduje wszystkie pliki PO w src pasujące do wzorca {key}.i18n.po
+     */
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Zapewnia, że te pliki PO mają pierwszeństwo przed plikami w `./locales/en/${key}.po`
+    }),
+    /**
+     * Załaduje i zapisze wyniki oraz tłumaczenia z powrotem do plików PO w katalogu locales
+     */
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin `syncPO`
+
+### Szybki start
+
+Dodaj plugin do swojego `intlayer.config.ts` i skieruj go na istniejącą strukturę plików PO.
+
+```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,
+  },
+
+  // Utrzymuj synchronizację aktualnych plików PO ze słownikami Intlayer
+  plugins: [
+    syncPO({
+      // Układ według języka i przestrzeni nazw
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternatywa: pojedynczy plik na język:
+
+```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;
+```
+
+#### Jak to działa
+
+- Odczyt: plugin wykrywa pliki PO za pomocą konstruktora `source` i ładuje je jako słowniki Intlayer.
+- Zapis: po zbudowaniu i wypełnieniu, zapisuje zlokalizowane pliki PO z powrotem pod tymi samymi ścieżkami (z odpowiednimi nagłówkami Gettext).
+- Automatyczne wypełnianie: plugin deklaruje ścieżkę `autoFill` dla każdego słownika. Uruchomienie `intlayer fill` domyślnie aktualizuje tylko brakujące tłumaczenia w plikach PO.
+
+API:
+
+```ts
+syncPO({
+  source: ({ key, locale }) => string, // wymagane
+  location?: string, // opcjonalna etykieta, domyślnie: "sync-po::path/to/source"
+  priority?: number, // opcjonalny priorytet dla rozwiązywania konfliktów, domyślnie: 0
+  format?: 'icu' | 'i18next' | 'vue-i18n', // opcjonalne, potrzebne tylko gdy wartości msgstr używają specyficznej składni interpolacji
+});
+```
+
+#### `format` ('icu' | 'i18next' | 'vue-i18n')
+
+Pliki PO to zawsze pliki Gettext Portable Object — to jest stałe. Ta opcja opisuje jedynie **składnię interpolacji** używaną wewnątrz wartości `msgstr`, dzięki czemu Intlayer może przekonwertować je na własny format w czasie parsowania (przez `formatDictionary`) i z powrotem podczas zapisywania wyników.
+
+- `undefined` _(domyślnie)_: wartości `msgstr` są traktowane jako zwykłe ciągi znaków — brak transformacji. Używaj tego dla większości plików PO.
+- `'icu'`: wartości `msgstr` używają składni komunikatów ICU (np. `{count, plural, one {# item} other {# items}}`).
+- `'i18next'`: wartości `msgstr` używają składni interpolacji i18next (np. `{{variable}}`).
+- `'vue-i18n'`: wartości `msgstr` używają składni Vue I18n.
+
+> Transformacja jest nakładana przez `formatDictionary` z `@intlayer/chokidar` przy ładowaniu i odwracana za pomocą `formatDictionaryOutput` przy zapisie. W przypadku złożonych reguł, takich jak liczby mnogie ICU, wierność konwersji w obie strony nie jest gwarantowana.
+
+**Przykład — pliki PO zawierają interpolację w stylu i18next:**
+
+```ts
+syncPO({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+  format: "i18next",
+}),
+```
+
+### Wiele źródeł PO i priorytet
+
+Możesz dodać wiele pluginów `syncPO`, aby synchronizować różne źródła PO. Jest to przydatne, gdy masz wiele źródeł tłumaczeń lub różne struktury PO w swoim projekcie.
+
+#### System priorytetów
+
+Gdy wiele pluginów celuje w ten sam klucz słownika, parametr `priority` decyduje, który plugin ma pierwszeństwo:
+
+- Wyższe numery priorytetu wygrywają z niższymi
+- Domyślny priorytet plików `.content` to `0`
+- Domyślny priorytet pluginów to `0`
+- Pluginy o tym samym priorytecie są przetwarzane w kolejności, w jakiej pojawiają się w konfiguracji
+
+```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: [
+    // Główne źródło PO (najwyższy priorytet)
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Zapasowe źródło PO (niższy priorytet)
+    syncPO({
+      source: ({ locale }) => `./fallback-locales/${locale}.po`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Starsze źródło PO (najniższy priorytet)
+    syncPO({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.po`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Plugin Load PO
+
+### Szybki start
+
+Dodaj plugin do swojego `intlayer.config.ts`, aby wczytać istniejące pliki PO jako słowniki Intlayer. Ten plugin jest tylko do odczytu (brak zapisu na dysku):
+
+```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: [
+    // Wczytaj komunikaty PO znajdujące się w dowolnym miejscu w drzewie źródeł
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      // Ładuj jeden język na instancję pluginu (domyślnie defaultLocale z konfiguracji)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternatywa: układ według języka, nadal tylko do odczytu (ładowany jest tylko wybrany język):
+
+```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({
+      // Tylko pliki dla Locales.FRENCH zostaną wczytane z tego wzorca
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### Jak to działa
+
+- Wykrywanie: buduje glob z konstruktora `source` i zbiera pasujące pliki PO.
+- Wczytywanie: ładuje każdy plik PO jako słownik Intlayer z podanym `locale`.
+- Tylko do odczytu: nie zapisuje ani nie formatuje plików wynikowych; użyj `syncPO`, jeśli potrzebujesz synchronizacji w obie strony.
+- Gotowy do automatycznego wypełniania: definiuje ścieżkę `fill`, aby `intlayer content fill` mógł uzupełnić brakujące klucze.
+
+### API
+
+```ts
+loadPO({
+  // Buduj ścieżki do plików PO. `locale` jest opcjonalny, jeśli Twoja struktura nie ma segmentu języka
+  source: ({ key, locale }) => string,
+
+  // Docelowy język dla słowników ładowanych przez tę instancję pluginu
+  // Domyślnie configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Opcjonalna etykieta do identyfikacji źródła
+  location?: string, // domyślnie: "plugin"
+
+  // Priorytet używany do rozwiązywania konfliktów z innymi źródłami
+  priority?: number, // domyślnie: 0
+});
+```
+
+### Zachowanie i konwencje
+
+- Jeśli maska `source` zawiera symbol zastępczy języka, wczytywane są tylko pliki dla wybranego `locale`.
+- Jeśli w masce nie ma segmentu `{key}`, kluczem słownika jest "index".
+- Klucze są wyprowadzane ze ścieżek plików poprzez zastąpienie symbolu zastępczego `{key}` w konstruktorze `source`.
+- Plugin używa tylko wykrytych plików i nie tworzy brakujących języków ani kluczy.
+- Ścieżka `fill` jest wywnioskowana z `source` i używana do aktualizacji brakujących wartości przez CLI, gdy się na to zdecydujesz.
+
+## Rozwiązywanie konfliktów
+
+Gdy ten sam klucz tłumaczenia istnieje w wielu źródłach PO:
+
+1. Plugin o najwyższym priorytecie określa ostateczną wartość
+2. Źródła o niższym priorytecie są używane jako rezerwowe dla brakujących kluczy
+3. Pozwala to na zachowanie starszych tłumaczeń przy jednoczesnym stopniowym przechodzeniu na nowe struktury
+
+## CLI
+
+Zsynchronizowane pliki PO będą traktowane jak inne pliki `.content`. Oznacza to, że wszystkie polecenia intlayer będą dostępne dla zsynchronizowanych plików PO. W tym:
+
+- `intlayer content test` aby przetestować, czy brakuje tłumaczeń
+- `intlayer content list` aby wyświetlić listę zsynchronizowanych plików PO
+- `intlayer content fill` aby wypełnić brakujące tłumaczenia
+- `intlayer content push` aby wysłać zsynchronizowane pliki PO
+- `intlayer content pull` aby pobrać zsynchronizowane pliki PO
+
+Zobacz [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md) po więcej szczegółów.
+
+## Ograniczenia (aktualne)
+
+- Brak wsparcia dla wstawek lub liczb mnogich/ICU przy celowaniu w biblioteki firm trzecich.
+- Edytor wizualny nie jest jeszcze dostępny dla runtime'ów innych niż Intlayer.
+- Tylko synchronizacja PO; formaty katalogów inne niż PO nie są wspierane.
+
+## Dlaczego to ważne
+
+- Możemy polecać uznane rozwiązania i18n i pozycjonować Intlayer jako dodatek.
+- Wykorzystujemy ich SEO/słowa kluczowe za pomocą samouczków, które kończą się sugestią użycia Intlayer do zarządzania plikami PO.
+- Rozszerza grono odbiorców z „nowych projektów” na „każdy zespół korzystający już z i18n”.

package/docs/pt/mcp_server.md

@@ -23,7 +23,7 @@ history:
     changes: "Adicionado configuração do Claude Desktop"
   - version: 5.5.12
     date: 2025-07-10
-    changes: "Adicionado transporte SSE e servidor remoto"
+    changes: "Adicionado transporte Streamable HTTP e servidor remoto"
   - version: 5.5.10
     date: 2025-06-29
     changes: "Histórico inicial"
@@ -51,12 +51,12 @@ Ao ativar o Servidor MCP Intlayer na sua IDE, você desbloqueia:
 
   > Veja a lista completa de comandos e opções na [documentação do Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/index.md).
 
-## Servidor local (stdio) vs Servidor remoto (SSE)
+## Servidor local (stdio) vs Servidor remoto (Streamable HTTP)
 
 O servidor MCP pode ser usado de duas maneiras:
 
 - Servidor local (stdio)
-- Servidor remoto (SSE)
+- Servidor remoto (Streamable HTTP)
 
 ### Servidor local (stdio) (recomendado)
 
@@ -64,7 +64,7 @@ O Intlayer fornece um pacote NPM que pode ser instalado localmente na sua máqui
 
 Este servidor é a forma recomendada de usar o servidor MCP, pois integra todos os recursos do servidor MCP, incluindo as ferramentas CLI.
 
-### Servidor remoto (SSE)
+### Servidor remoto (Streamable HTTP)
 
 O servidor MCP também pode ser usado remotamente, utilizando o método de transporte SSE. Este servidor é hospedado pelo Intlayer e está disponível em https://mcp.intlayer.org. Este servidor pode ser acessado publicamente, sem qualquer autenticação, e é gratuito para uso.
 
@@ -97,7 +97,7 @@ bun x intlayer init mcp
 Este comando irá:
 
 1. Perguntar qual plataforma você está usando (Cursor, VS Code, Claude Desktop, etc.).
-2. Perguntar qual método de transporte você deseja usar (Servidor local (stdio) ou Servidor remoto (SSE)).
+2. Perguntar qual método de transporte você deseja usar (Servidor local (stdio) ou Servidor remoto (Streamable HTTP)).
 3. Atualizar automaticamente seu arquivo de configuração (ex: `.cursor/mcp.json`, `.vscode/mcp.json` ou a configuração global do Claude Desktop).
 
 ---
@@ -107,7 +107,7 @@ Este comando irá:
 1. Abra a paleta de comandos (Ctrl+Shift+P ou Cmd+Shift+P).
 2. Digite `Intlayer: Setup AI Agent Skills`
 3. Escolha a plataforma que você usa (ex: `VS Code`, `Cursor`, `Windsurf`, `OpenCode`, `Claude Code`, `GitHub Copilot Workspace`, etc.).
-4. Escolha o MCP para instalar (stdio, SSE)
+4. Escolha o MCP para instalar (stdio, Streamable HTTP)
 5. Pressione Enter.
 
 ---
@@ -131,16 +131,16 @@ Na raiz do seu projeto, adicione o seguinte arquivo de configuração `.cursor/m
 }
 ```
 
-### Servidor remoto (SSE)
+### Servidor remoto (Streamable HTTP)
 
-Para conectar a um servidor Intlayer MCP remoto usando Server-Sent Events (SSE), você pode configurar seu cliente MCP para se conectar ao serviço hospedado.
+Para conectar a um servidor Intlayer MCP remoto usando Server-Sent Events (Streamable HTTP), você pode configurar seu cliente MCP para se conectar ao serviço hospedado.
 
 ```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 @@ Crie um arquivo `.vscode/mcp.json` na raiz do seu projeto:
 }
 ```
 
-### Servidor remoto (SSE)
+### Servidor remoto (Streamable HTTP)
 
-Para conectar a um servidor Intlayer MCP remoto usando Server-Sent Events (SSE), você pode configurar seu cliente MCP para se conectar ao serviço hospedado.
+Para conectar a um servidor Intlayer MCP remoto usando Server-Sent Events (Streamable HTTP), você pode configurar seu cliente MCP para se conectar ao serviço hospedado.
 
 ```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 @@ Para conectar a um servidor Intlayer MCP remoto usando Server-Sent Events (SSE),
 
 ## Configuração no ChatGPT
 
-### Servidor remoto (SSE)
+### Servidor remoto (Streamable HTTP)
 
 Siga a [documentação oficial](https://platform.openai.com/docs/mcp#test-and-connect-your-mcp-server) para configurar o servidor MCP no ChatGPT.
 
@@ -232,6 +232,19 @@ Caminho do arquivo de configuração:
 }
 ```
 
+### Servidor remoto (Streamable HTTP)
+
+```json fileName="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
+    }
+  }
+}
+```
+
 ---
 
 ## Usando o Servidor MCP via CLI