@intlayer/docs 8.9.4-canary.0 → 8.9.4

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

@@ -0,0 +1,354 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Sync PO プラグイン
+description: Intlayer 辞書を Gettext PO ファイルと同期します。Intlayer を使用してメッセージの管理、翻訳、テストを行いながら、既存の i18n を維持します。
+keywords:
+  - Intlayer
+  - Sync PO
+  - Gettext
+  - i18n
+  - 翻訳
+slugs:
+  - doc
+  - plugin
+  - sync-po
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 8.9.4
+    date: 2026-05-10
+    changes: "Sync PO プラグインの初期ドキュメント"
+---
+
+# Sync PO (i18n ブリッジ) - ICU / i18next サポート付きの Sync PO
+
+既存の i18n スタックのアドオンとして Intlayer を使用します。このプラグインは、Gettext PO メッセージを Intlayer 辞書と同期させ、以下のことを可能にします。
+
+- 既存の PO ベースの翻訳ワークフローを維持する。
+- アプリをリファクタリングすることなく、Intlayer（CLI、CI、プロバイダー、CMS）を使用してメッセージを管理および翻訳する。
+- Intlayer を PO 管理レイヤーとして提案しながら、各エコシステムをターゲットにしたチュートリアルや SEO コンテンツをリリースする。
+
+注意点と現在の範囲：
+
+- CMS への外部化は、翻訳と通常のテキストで機能します。
+- 挿入、複数形/ICU、または PO エントリ自体の内部にある他のライブラリの高度なランタイム機能はまだサポートされていません。
+- ビジュアルエディターは、サードパーティの i18n 出力ではまだサポートされていません。
+
+### このプラグインを使用する場合
+
+- すでに翻訳に Gettext PO ファイルを使用している場合。
+- レンダリングランタイムを変更せずに、AI による補完、CI でのテスト、コンテンツ運用を行いたい場合。
+
+## インストール
+
+```bash
+pnpm add -D @intlayer/sync-po-plugin
+# または
+npm i -D @intlayer/sync-po-plugin
+```
+
+## プラグイン
+
+このパッケージは 2 つのプラグインを提供します。
+
+- `loadPO`: PO ファイルを Intlayer 辞書にロードします。
+  - このプラグインは、ソースから PO ファイルをロードして Intlayer 辞書に読み込むために使用されます。コードベース全体をスキャンして特定の PO ファイルを検索できます。
+    このプラグインの使用例：
+    - i18n ライブラリが PO ファイルの読み込み場所を制限しているが、コンテンツ宣言はコードベース内の好きな場所に配置したい場合。
+    - リモートソース（例：CMS、API など）からメッセージを取得し、メッセージを PO ファイルに保存したい場合。
+
+  > 内部的には、このプラグインはコードベース全体をスキャンして特定の PO ファイルを検索し、Intlayer 辞書に読み込みます。
+  > このプラグインは、出力や翻訳を PO ファイルに書き戻さないことに注意してください。
+
+- `syncPO`: PO ファイルを Intlayer 辞書と同期させます。
+  - このプラグインは、PO ファイルを Intlayer 辞書と同期させるために使用されます。指定された場所をスキャンし、特定の PO ファイルのパターンに一致する PO をロードできます。このプラグインは、別の i18n ライブラリを使用しながら Intlayer の利点を得たい場合に役立ちます。
+
+## 両方のプラグインの使用
+
+```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,
+  },
+
+  // 現在の PO ファイルを Intlayer 辞書と同期させる
+  plugins: [
+    /**
+     * src 内の {key}.i18n.po パターンに一致するすべての PO ファイルをロードします
+     */
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      locale: Locales.ENGLISH,
+      priority: 1, // `./locales/en/${key}.po` のファイルよりもこれらの PO ファイルが優先されるようにします
+    }),
+    /**
+     * ロードし、出力と翻訳を locales ディレクトリの PO ファイルに書き戻します
+     */
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncPO` プラグイン
+
+### クイックスタート
+
+プラグインを `intlayer.config.ts` に追加し、既存の 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,
+  },
+
+  // 現在の PO ファイルを Intlayer 辞書と同期させる
+  plugins: [
+    syncPO({
+      // ロケール別、名前空間別のレイアウト
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+代替案：ロケールごとに 1 つのファイル：
+
+```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;
+```
+
+#### 仕組み
+
+- 読み取り: プラグインは `source` ビルダーから PO ファイルを検出し、Intlayer 辞書として読み込みます。
+- 書き込み: ビルドと補完の後、ローカライズされた PO を同じパスに書き戻します（適切な Gettext ヘッダー付き）。
+- 自動補完: プラグインは各辞書の `autoFill` パスを宣言します。`intlayer fill` を実行すると、デフォルトで PO ファイルの不足している翻訳のみが更新されます。
+
+API:
+
+```ts
+syncPO({
+  source: ({ key, locale }) => string, // 必須
+  location?: string, // オプションのラベル、デフォルト: "sync-po::path/to/source"
+  priority?: number, // 競合解決のためのオプションの優先度、デフォルト: 0
+  format?: 'icu' | 'i18next' | 'vue-i18n', // オプション、msgstr の値が特定の補完構文を使用している場合にのみ必要
+});
+```
+
+#### `format` ('icu' | 'i18next' | 'vue-i18n')
+
+PO ファイルは常に Gettext Portable Object ファイルです。これは固定されています。このオプションは、`msgstr` 値の中で使用される **補完構文** のみを記述します。これにより、Intlayer はパース時（`formatDictionary` 経由）に独自の形式に変換し、出力書き込み時に元に戻すことができます。
+
+- `undefined` _(デフォルト)_: `msgstr` の値はプレーンテキストとして扱われ、変換されません。ほとんどの PO ファイルでこれを使用します。
+- `'icu'`: `msgstr` の値は ICU メッセージ構文を使用します（例：`{count, plural, one {# item} other {# items}}`）。
+- `'i18next'`: `msgstr` の値は i18next 補完構文を使用します（例：`{{variable}}`）。
+- `'vue-i18n'`: `msgstr` の値は Vue I18n 構文を使用します。
+
+> 変換はロード時に `@intlayer/chokidar` の `formatDictionary` によって適用され、書き込み時に `formatDictionaryOutput` で元に戻されます。ICU 複数形のような複雑なルールの場合、ラウンドトリップの忠実性は保証されません。
+
+**例 — PO ファイルに i18next スタイルの補完が含まれている場合:**
+
+```ts
+syncPO({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+  format: "i18next",
+}),
+```
+
+### 複数の PO ソースと優先度
+
+複数の `syncPO` プラグインを追加して、異なる PO ソースを同期させることができます。これは、プロジェクトに複数の翻訳ソースや異なる PO 構造がある場合に役立ちます。
+
+#### 優先度システム
+
+複数のプラグインが同じ辞書キーをターゲットにしている場合、`priority` パラメーターによってどのプラグインが優先されるかが決まります。
+
+- 優先度の高い数値が低い数値よりも優先されます
+- `.content` ファイルのデフォルト優先度は `0` です
+- プラグインのデフォルト優先度は `0` です
+- 同じ優先度のプラグインは、設定に表示される順序で処理されます
+
+```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: [
+    // 主要な PO ソース (最高優先度)
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // フォールバック PO ソース (低い優先度)
+    syncPO({
+      source: ({ locale }) => `./fallback-locales/${locale}.po`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // レガシー PO ソース (最低優先度)
+    syncPO({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.po`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Load PO プラグイン
+
+### クイックスタート
+
+既存の PO ファイルを Intlayer 辞書として取り込むために、プラグインを `intlayer.config.ts` に追加します。このプラグインは読み取り専用です（ディスクへの書き込みはありません）。
+
+```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: [
+    // ソースツリー内の任意の場所にある PO メッセージを取り込む
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      // プラグインインスタンスごとに単一のロケールをロードします (デフォルトは config の defaultLocale です)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+代替案：ロケール別のレイアウト、依然として読み取り専用（選択したロケールのみがロードされます）：
+
+```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({
+      // このパターンから Locales.FRENCH のファイルのみが読み込まれます
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### 仕組み
+
+- 発見: `source` ビルダーから glob を構築し、一致する PO ファイルを収集します。
+- 取り込み: 各 PO ファイルを指定された `locale` で Intlayer 辞書として読み込みます。
+- 読み取り専用: 出力ファイルを書き込んだりフォーマットしたりしません。ラウンドトリップ同期が必要な場合は `syncPO` を使用してください。
+- 自動補完対応: `intlayer content fill` が不足しているキーを入力できるように `fill` パスを定義します。
+
+### API
+
+```ts
+loadPO({
+  // PO へのパスを構築します。構造にロケールセグメントがない場合、`locale` はオプションです。
+  source: ({ key, locale }) => string,
+
+  // このプラグインインスタンスによってロードされる辞書のターゲットロケール
+  // デフォルトは configuration.internationalization.defaultLocale です
+  locale?: Locale,
+
+  // ソースを識別するためのオプションのラベル
+  location?: string, // デフォルト: "plugin"
+
+  // 他のソースとの競合解決に使用される優先度
+  priority?: number, // デフォルト: 0
+});
+```
+
+### 動作と規約
+
+- `source` マスクにロケールプレースホルダーが含まれている場合、選択した `locale` のファイルのみが取り込まれます。
+- マスクに `{key}` セグメントがない場合、辞書キーは "index" になります。
+- キーは、`source` ビルダー内の `{key}` プレースホルダーを置き換えることにより、ファイルパスから派生します。
+- プラグインは発見されたファイルのみを使用し、不足しているロケールやキーを捏造しません。
+- `fill` パスは `source` から推測され、オプトインしたときに CLI を介して不足している値を更新するために使用されます。
+
+## 競合解決
+
+同じ翻訳キーが複数の PO ソースに存在する場合：
+
+1. 優先度が最も高いプラグインが最終的な値を決定します
+2. 優先度の低いソースは、不足しているキーのフォールバックとして使用されます
+3. これにより、新しい構造に徐々に移行しながら、レガシーな翻訳を維持することができます
+
+## CLI
+
+同期された PO ファイルは、他の `.content` ファイルと同様に扱われます。つまり、同期された PO ファイルに対してすべての intlayer コマンドが利用可能になります。以下を含みます。
+
+- `intlayer content test`: 不足している翻訳があるかどうかをテストします
+- `intlayer content list`: 同期された PO ファイルをリストします
+- `intlayer content fill`: 不足している翻訳を埋めます
+- `intlayer content push`: 同期された PO ファイルをプッシュします
+- `intlayer content pull`: 同期された PO ファイルをプルします
+
+詳細は [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md) を参照してください。
+
+## 制限事項（現在）
+
+- サードパーティライブラリをターゲットにする場合、挿入や複数形/ICU のサポートはありません。
+- Intlayer 以外のランタイムでは、ビジュアルエディターはまだ利用できません。
+- PO 同期のみ。PO 以外のカタログ形式はサポートされていません。
+
+## なぜこれが重要なのか
+
+- 確立された i18n ソリューションを推奨し、Intlayer をアドオンとして位置付けることができます。
+- Intlayer を使用して PO を管理することを提案して終わるチュートリアルで、彼らの SEO/キーワードを活用します。
+- 対応可能なオーディエンスを「新しいプロジェクト」から「すでに i18n を使用しているチーム」へと拡大します。

package/docs/ko/mcp_server.md

@@ -23,7 +23,7 @@ history:
     changes: "Claude Desktop 설정 추가"
   - version: 5.5.12
     date: 2025-07-10
-    changes: "SSE 전송 및 원격 서버 추가"
+    changes: "Streamable HTTP 전송 및 원격 서버 추가"
   - version: 5.5.10
     date: 2025-06-29
     changes: "초기 기록"
@@ -51,12 +51,12 @@ Intlayer MCP 서버를 IDE에서 활성화하면 다음과 같은 기능을 사
 
   > 전체 명령어 및 옵션 목록은 [Intlayer CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/index.md)에서 확인하세요.
 
-## 로컬 서버 (stdio) vs 원격 서버 (SSE)
+## 로컬 서버 (stdio) vs 원격 서버 (Streamable HTTP)
 
 MCP 서버는 두 가지 방식으로 사용할 수 있습니다:
 
 - 로컬 서버 (stdio)
-- 원격 서버 (SSE)
+- 원격 서버 (Streamable HTTP)
 
 ### 로컬 서버 (stdio) (권장)
 
@@ -64,9 +64,9 @@ Intlayer는 사용자의 컴퓨터에 로컬로 설치할 수 있는 NPM 패키
 
 이 서버는 MCP 서버를 사용하는 권장 방법입니다. CLI 도구를 포함한 MCP 서버의 모든 기능이 통합되어 있기 때문입니다.
 
-### 원격 서버 (SSE)
+### 원격 서버 (Streamable HTTP)
 
-MCP 서버는 SSE 전송 방식을 사용하여 원격으로도 사용할 수 있습니다. 이 서버는 Intlayer에서 호스팅하며 https://mcp.intlayer.org 에서 이용할 수 있습니다. 이 서버는 인증 없이 공개적으로 접근할 수 있으며 무료로 사용할 수 있습니다.
+MCP 서버는 Streamable HTTP 전송 방식을 사용하여 원격으로도 사용할 수 있습니다. 이 서버는 Intlayer에서 호스팅하며 https://mcp.intlayer.org 에서 이용할 수 있습니다. 이 서버는 인증 없이 공개적으로 접근할 수 있으며 무료로 사용할 수 있습니다.
 
 원격 서버는 CLI 도구, AI 자동완성 등과 통합되어 있지 않다는 점에 유의하세요. 원격 서버는 Intlayer 생태계와 관련된 문서와 상호작용하여 AI 어시스턴트를 돕기 위한 용도로만 사용됩니다.
 
@@ -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://docs.cursor.c
 }
 ```
 
-### 원격 서버 (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 서버를 구성하려면 [공식 문서](https://platform.ope
 }
 ```
 
+### 원격 서버 (Streamable HTTP)
+
+```json fileName="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
+    }
+  }
+}
+```
+
 ---
 
 ## CLI를 통한 MCP 서버 사용