# 自動ドキュメント翻訳

GitHub Actions と Dify AI に基づく多言語ドキュメント自動翻訳システム。英語、中国語、日本語の三言語相互翻訳をサポートします。

> **他の言語**: [中文](README.md) | [English](README_EN.md)

## 動作原理

1. **トリガー条件**: main以外のブランチにプッシュすると自動実行
2. **スマート検出**: 変更された `.md/.mdx` ファイルを自動識別し、元言語を判定
3. **翻訳ロジック**:
    - ✅ 新規ドキュメントを他の言語に翻訳
    - ❌ 既存の翻訳ファイルはスキップ（手動編集の上書きを回避）
4. **自動コミット**: 翻訳結果を現在のブランチに自動プッシュ

## システム特徴

- 🌐 **多言語サポート**: 設定ベースの言語マッピング、理論的には任意の言語拡張をサポート
- 📚 **用語の一貫性**: 内蔵専門用語データベース、LLMが用語表を賢く遵守し技術用語翻訳の統一を確保
- 🔄 **並行処理**: スマート並行制御、複数のターゲット言語を同時翻訳
- 🛡️ **フォールトトレランス**: 3回再試行メカニズム、指数バックオフ戦略
- ⚡ **増分翻訳**: 変更ファイルのみ処理、重複作業を回避
- 🧠 **高性能モデル**: 高性能LLMモデルを使用し翻訳品質を確保

## 使用方法

### ドキュメント作成者向け

1. 任意の言語ディレクトリでドキュメントを作成/修正
2. ブランチ（main以外）にプッシュ
3. 0.5-1分待って自動翻訳完了
4. **翻訳結果の確認**:
    - Pull Requestを作成してローカル確認と後続編集
    - またはGitHubでActionsプッシュコミット詳細を確認し、翻訳品質を直接レビュー

### サポート言語ディレクトリ

- **一般ドキュメント**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
- **プラグイン開発ドキュメント**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`

注：システムアーキテクチャはより多くの言語拡張をサポート、設定ファイルの修正のみで可能

## 注意事項

- システムは新規ドキュメントのみ翻訳、既存翻訳は上書きしません
- 既存翻訳を更新する場合、対象ファイルを手動削除してから再トリガー
- 用語翻訳は `termbase_i18n.md` の専門用語表に従い、LLMはスマート用語認識機能を持つ
- 翻訳品質は設定された高性能モデルに依存、Dify Studioで高性能ベースモデル使用を推奨

### システム設定

#### 用語データベース

`tools/translate/termbase_i18n.md` を編集して専門用語翻訳対照表を更新。

#### 翻訳モデル

Dify Studio で翻訳プロンプトの調整やベースモデルの変更。

---

## 🔧 開発とデプロイ設定

### ローカル開発環境

#### 1. 仮想環境作成

```bash
# 仮想環境作成
python -m venv venv

# 仮想環境アクティベート
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate
```

#### 2. 依存関係インストール

```bash
pip install -r tools/translate/requirements.txt
```

#### 3. APIキー設定

`tools/translate/` ディレクトリに `.env` ファイルを作成：

```bash
DIFY_API_KEY=your_dify_api_key_here
```

#### 4. 翻訳実行

```bash
# インタラクティブモード（初心者推奨）
python tools/translate/main.py

# コマンドラインモード（ファイル指定）
python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
```

> **ヒント**: IDEで右クリック「相対パスをコピー」をパラメータとして使用

### 他のリポジトリへのデプロイ

1. **ファイルコピー**:
    - `.github/workflows/translate.yml`
    - `tools/translate/` ディレクトリ全体

2. **GitHub Secrets設定**:
    - Repository Settings → Secrets and variables → Actions
    - `DIFY_API_KEY` シークレットを追加

3. **テスト**: ブランチでドキュメント修正し、自動翻訳機能を検証

### 技術詳細

- 並行翻訳は2タスクに制限、過度なAPI圧迫を回避
- `.md` と `.mdx` ファイル形式をサポート
- Dify API ワークフローモードベース

## TODO

- [ ] 既存翻訳の更新サポート
