Docs Translation Synchronizer

VS Code Desktop で日本語・英語の Markdown 文書を手動同期します。変更箇所を翻訳し、対応するファイルの相対パスを保って作成・更新します。

インストール

1. VS Code の Extensions ビューを開きます（Windows/Linux: Ctrl+Shift+X、macOS: Cmd+Shift+X）。
2. Docs Translation Synchronizer を検索して Install を選びます。
3. 文書を含むフォルダを VS Code Desktop で開き、workspace を信頼します。

VS Code 1.101 以降が必要です。VS Code Web、remote/virtual workspace は対象外です。

初回の設定と同期

1. コマンドパレット（Windows/Linux: Ctrl+Shift+P、macOS: Cmd+Shift+P）から Docs Sync: Select Japanese Folder と Docs Sync: Select English Folder を実行し、対象フォルダを指定します。workspace 内の相対パス（例: docs/ja）または workspace 内の絶対パスを指定できます。初期値は ja と en です。2つのフォルダは異なる場所にし、互いを含まないようにしてください。
2. Docs Sync: Set Up Provider and API Key から OpenAI、Claude、Gemini の提供元・モデル・API key を設定します。翻訳本文の送信には別途許可が必要です。Custom API は HTTPS の JSON POST を受け付け、翻訳済み Markdown 文字列を返す必要があります。Custom API を使う場合は、user settings の docsSync.provider、docsSync.model、docsSync.endpoint、docsSync.apiProfile に値を設定し、Docs Sync: Register Provider API Key でkeyを登録して送信を許可してください。apiProfile では認証ヘッダー、リクエスト項目、応答から翻訳文字列を取り出す方法を指定します。 OpenAI、Claude、Gemini の提供元・モデル・keyを変更するときも同じセットアップコマンドを再実行します。現在の提供元には (current) が付き、モデルを入力し直して新しいkeyを登録できます。保存済みkeyの値は表示されません。Custom API の設定変更はuser settingsで行い、keyは Docs Sync: Register Provider API Key から再登録します。提供元やモデルを変更した場合、その設定に対する翻訳本文の送信許可を改めて確認してください。
3. 翻訳元の UTF-8 .md ファイルを保存し、Japanese to English または English to Japanese を実行します。実行前に内容を確認するには Japanese to English with preview または English to Japanese with preview を使い、予定操作と送信する Markdown 本文を確認して Apply を選びます。Apply までは API を呼び出しません。
4. 完了通知と翻訳先フォルダの出力を確認します。同期は自動ではありません。翻訳元を編集・保存した後、方向コマンドを再実行してください。

初回に同じ相対パスのファイルが両言語に存在し、同期履歴がない場合は安全のため停止します。未保存の対象文書は保存してから実行してください。

コマンド

すべてコマンドパレットから実行できます。Docs Sync ビューには API 設定、両方向の同期、プレビュー実行のボタンもあります。

データと制約

• API key は VS Code SecretStorage に保存されます。API には翻訳対象の Markdown 本文を送信します。同期状態と Undo 用データには両言語の本文をローカル保存します。送信先は選択した提供元または自分で設定した Custom API です。送信を許可する前に、送信予定の本文とAPI提供元のデータ取り扱いを確認してください。
• UTF-8 CommonMark/GFM の .md が対象です。ファイル上限は 1 MiB、翻訳 unit 上限は 16 KiB です。見出し #〜### を基準に分割し、1ファイル分を1つの論理 API リクエストで送信します。
• 追跡済み Markdown の削除は同期先にも反映します。Undo はフォルダの組ごとの直近 run が対象で、その後に編集されている場合は停止します。両側の変更を自動で統合する機能はありません。
• ローカル workspace 内のフォルダのみ利用できます。symlink/junction、MDX、添付ファイルは対象外です。