Skip to content

Commit b87a4f0

Browse files
alterxyzalterxyz
committed
docs: translate readme
1 parent 299336b commit b87a4f0

File tree

3 files changed

+380
-0
lines changed

3 files changed

+380
-0
lines changed

‎tools/translate/README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,125 @@
1+
# Automatic Document Translation
12

3+
Multi-language document auto-translation system based on GitHub Actions and Dify AI, supporting English, Chinese, and Japanese trilingual translation.
4+
5+
> **Other Languages**: [中文](README.md) | [日本語](README_JA.md)
6+
7+
## How It Works
8+
9+
1. **Trigger Condition**: Automatically runs when pushing to non-main branches
10+
2. **Smart Detection**: Automatically identifies modified `.md/.mdx` files and determines source language
11+
3. **Translation Logic**:
12+
- ✅ Translates new documents to other languages
13+
- ❌ Skips existing translation files (avoids overwriting manual edits)
14+
4. **Auto Commit**: Translation results are automatically pushed to the current branch
15+
16+
## System Features
17+
18+
- 🌐 **Multi-language Support**: Configuration-based language mapping, theoretically supports any language extension
19+
- 📚 **Terminology Consistency**: Built-in professional terminology database, LLM intelligently follows terminology to ensure unified technical vocabulary translation
20+
- 🔄 **Concurrent Processing**: Smart concurrency control, translates multiple target languages simultaneously
21+
- 🛡️ **Fault Tolerance**: 3-retry mechanism with exponential backoff strategy
22+
- ⚡ **Incremental Translation**: Only processes changed files, avoids redundant work
23+
- 🧠 **High-Performance Models**: Uses high-performance LLM models to ensure translation quality
24+
25+
## Usage
26+
27+
### For Document Writers
28+
29+
1. Write/modify documents in any language directory
30+
2. Push to branch (non-main)
31+
3. Wait 0.5-1 minute for automatic translation completion
32+
4. **View Translation Results**:
33+
- Create Pull Request for local viewing and subsequent editing
34+
- Or view Actions push commit details on GitHub to directly review translation quality
35+
36+
### Supported Language Directories
37+
38+
- **General Documentation**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
39+
- **Plugin Development Documentation**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
40+
41+
Note: System architecture supports extending more languages, just modify configuration files
42+
43+
## Important Notes
44+
45+
- System only translates new documents, won't overwrite existing translations
46+
- To update existing translations, manually delete target files then retrigger
47+
- Terminology translation follows professional vocabulary in `termbase_i18n.md`, LLM has intelligent terminology recognition capabilities
48+
- Translation quality depends on configured high-performance models, recommend using high-performance base models in Dify Studio
49+
50+
### System Configuration
51+
52+
#### Terminology Database
53+
54+
Edit `tools/translate/termbase_i18n.md` to update professional terminology translation reference table.
55+
56+
#### Translation Model
57+
58+
Visit Dify Studio to adjust translation prompts or change base models.
59+
60+
---
61+
62+
## 🔧 Development and Deployment Configuration
63+
64+
### Local Development Environment
65+
66+
#### 1. Create Virtual Environment
67+
68+
```bash
69+
# Create virtual environment
70+
python -m venv venv
71+
72+
# Activate virtual environment
73+
# macOS/Linux:
74+
source venv/bin/activate
75+
# Windows:
76+
# venv\Scripts\activate
77+
```
78+
79+
#### 2. Install Dependencies
80+
81+
```bash
82+
pip install -r tools/translate/requirements.txt
83+
```
84+
85+
#### 3. Configure API Key
86+
87+
Create `.env` file in `tools/translate/` directory:
88+
89+
```bash
90+
DIFY_API_KEY=your_dify_api_key_here
91+
```
92+
93+
#### 4. Run Translation
94+
95+
```bash
96+
# Interactive mode (recommended for beginners)
97+
python tools/translate/main.py
98+
99+
# Command line mode (specify file)
100+
python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
101+
```
102+
103+
> **Tip**: Right-click in IDE and select "Copy Relative Path" to use as parameter
104+
105+
### Deploy to Other Repositories
106+
107+
1. **Copy Files**:
108+
- `.github/workflows/translate.yml`
109+
- `tools/translate/` entire directory
110+
111+
2. **Configure GitHub Secrets**:
112+
- Repository Settings → Secrets and variables → Actions
113+
- Add `DIFY_API_KEY` secret
114+
115+
3. **Test**: Modify documents in branch to verify automatic translation functionality
116+
117+
### Technical Details
118+
119+
- Concurrent translation limited to 2 tasks to avoid excessive API pressure
120+
- Supports `.md` and `.mdx` file formats
121+
- Based on Dify API workflow mode
122+
123+
## TODO
124+
125+
- [ ] Support updating existing translations

‎tools/translate/README_CN.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# 自动翻译文档
2+
3+
基于 GitHub Actions 和 Dify AI 的文档自动翻译系统，支持英文、中文、日文三语互译。
4+
5+
> **其他语言**: [English](README_EN.md) | [日本語](README_JA.md)
6+
7+
## 工作原理
8+
9+
1. **触发条件**: 推送到非 main 分支时自动运行
10+
2. **智能检测**: 自动识别修改的 `.md/.mdx` 文件并判断源语言
11+
3. **翻译逻辑**:
12+
- ✅ 翻译新增文档到其他语言
13+
- ❌ 跳过已存在的翻译文件（避免覆盖手动修改）
14+
4. **自动提交**: 翻译结果自动推送到当前分支
15+
16+
## 系统特性
17+
18+
- 🌐 **多语言支持**: 基于配置的语言映射，理论上支持任意语言扩展
19+
- 📚 **术语表一致性**: 内置专业术语库，LLM 智能遵循术语表确保技术词汇翻译统一
20+
- 🔄 **并发处理**: 智能并发控制，同时翻译多个目标语言
21+
- 🛡️ **容错机制**: 3 次重试机制，指数退避策略
22+
- ⚡ **增量翻译**: 只处理变更文件，避免重复工作
23+
- 🧠 **高性能模型**: 使用性能较强的 LLM 模型确保翻译质量
24+
25+
## 使用方法
26+
27+
### 文档编写者
28+
29+
1. 在任意语言目录下编写/修改文档
30+
2. 推送到分支（非 main）
31+
3. 等待 0.5-1 分钟自动翻译完成
32+
4. **查看翻译结果**:
33+
- 创建 Pull Request 进行本地查看和后续编辑
34+
- 或在 GitHub 查看 Actions 推送的 commit 详情，直接审查翻译质量
35+
36+
### 支持的语言目录
37+
38+
- **通用文档**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
39+
- **插件开发文档**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
40+
41+
注：系统架构支持扩展更多语言，只需修改配置文件
42+
43+
## 注意事项
44+
45+
- 系统只翻译新文档，不会覆盖已存在的翻译
46+
- 如需更新现有翻译，请手动删除目标文件后重新触发
47+
- 术语翻译遵循 `termbase_i18n.md` 中的专业词汇表，LLM 具备智能术语识别能力
48+
- 翻译质量依赖于配置的高性能模型，建议在 Dify Studio 中使用性能较强的基座模型
49+
50+
### 系统配置
51+
52+
#### 术语表
53+
54+
编辑 `tools/translate/termbase_i18n.md` 更新专业术语翻译对照表。
55+
56+
#### 翻译模型
57+
58+
访问 Dify Studio 调整翻译 prompt 或更换基座模型。
59+
60+
---
61+
62+
---
63+
64+
---
65+
66+
## 🔧 开发和部署配置
67+
68+
### 本地开发环境
69+
70+
#### 1. 创建虚拟环境
71+
72+
```bash
73+
# 创建虚拟环境
74+
python -m venv venv
75+
76+
# 激活虚拟环境
77+
# macOS/Linux:
78+
source venv/bin/activate
79+
# Windows:
80+
# venv\Scripts\activate
81+
```
82+
83+
#### 2. 安装依赖
84+
85+
```bash
86+
pip install -r tools/translate/requirements.txt
87+
```
88+
89+
#### 3. 配置 API 密钥
90+
91+
在 `tools/translate/` 目录下创建 `.env` 文件：
92+
93+
```bash
94+
DIFY_API_KEY=your_dify_api_key_here
95+
```
96+
97+
#### 4. 运行翻译
98+
99+
```bash
100+
# 交互模式（推荐新手使用）
101+
python tools/translate/main.py
102+
103+
# 命令行模式（指定文件）
104+
python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
105+
```
106+
107+
> **提示**: 在 IDE 中右键选择"复制相对路径"作为参数传入
108+
109+
### 部署到其他仓库
110+
111+
1. **复制文件**:
112+
113+
- `.github/workflows/translate.yml`
114+
- `tools/translate/` 整个目录
115+
116+
2. **配置 GitHub Secrets**:
117+
118+
- Repository Settings → Secrets and variables → Actions
119+
- 添加 `DIFY_API_KEY` 密钥
120+
121+
3. **测试**: 在分支中修改文档，验证自动翻译功能
122+
123+
### 技术细节
124+
125+
- 并发翻译限制为 2 个任务，避免 API 压力过大
126+
- 支持 `.md` 和 `.mdx` 文件格式
127+
- 基于 Dify API 的 workflow 模式
128+
129+
## TODO
130+
131+
- [ ] 支持更新现有翻译

‎tools/translate/README_JA.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# 自動ドキュメント翻訳
2+
3+
GitHub Actions と Dify AI に基づく多言語ドキュメント自動翻訳システム。英語、中国語、日本語の三言語相互翻訳をサポートします。
4+
5+
> **他の言語**: [中文](README.md) | [English](README_EN.md)
6+
7+
## 動作原理
8+
9+
1. **トリガー条件**: main以外のブランチにプッシュすると自動実行
10+
2. **スマート検出**: 変更された `.md/.mdx` ファイルを自動識別し、元言語を判定
11+
3. **翻訳ロジック**:
12+
- ✅ 新規ドキュメントを他の言語に翻訳
13+
- ❌ 既存の翻訳ファイルはスキップ（手動編集の上書きを回避）
14+
4. **自動コミット**: 翻訳結果を現在のブランチに自動プッシュ
15+
16+
## システム特徴
17+
18+
- 🌐 **多言語サポート**: 設定ベースの言語マッピング、理論的には任意の言語拡張をサポート
19+
- 📚 **用語の一貫性**: 内蔵専門用語データベース、LLMが用語表を賢く遵守し技術用語翻訳の統一を確保
20+
- 🔄 **並行処理**: スマート並行制御、複数のターゲット言語を同時翻訳
21+
- 🛡️ **フォールトトレランス**: 3回再試行メカニズム、指数バックオフ戦略
22+
- ⚡ **増分翻訳**: 変更ファイルのみ処理、重複作業を回避
23+
- 🧠 **高性能モデル**: 高性能LLMモデルを使用し翻訳品質を確保
24+
25+
## 使用方法
26+
27+
### ドキュメント作成者向け
28+
29+
1. 任意の言語ディレクトリでドキュメントを作成/修正
30+
2. ブランチ（main以外）にプッシュ
31+
3. 0.5-1分待って自動翻訳完了
32+
4. **翻訳結果の確認**:
33+
- Pull Requestを作成してローカル確認と後続編集
34+
- またはGitHubでActionsプッシュコミット詳細を確認し、翻訳品質を直接レビュー
35+
36+
### サポート言語ディレクトリ
37+
38+
- **一般ドキュメント**: `en/` ↔ `zh-hans/` ↔ `ja-jp/`
39+
- **プラグイン開発ドキュメント**: `plugin-dev-en/` ↔ `plugin-dev-zh/` ↔ `plugin-dev-ja/`
40+
41+
注：システムアーキテクチャはより多くの言語拡張をサポート、設定ファイルの修正のみで可能
42+
43+
## 注意事項
44+
45+
- システムは新規ドキュメントのみ翻訳、既存翻訳は上書きしません
46+
- 既存翻訳を更新する場合、対象ファイルを手動削除してから再トリガー
47+
- 用語翻訳は `termbase_i18n.md` の専門用語表に従い、LLMはスマート用語認識機能を持つ
48+
- 翻訳品質は設定された高性能モデルに依存、Dify Studioで高性能ベースモデル使用を推奨
49+
50+
### システム設定
51+
52+
#### 用語データベース
53+
54+
`tools/translate/termbase_i18n.md` を編集して専門用語翻訳対照表を更新。
55+
56+
#### 翻訳モデル
57+
58+
Dify Studio で翻訳プロンプトの調整やベースモデルの変更。
59+
60+
---
61+
62+
## 🔧 開発とデプロイ設定
63+
64+
### ローカル開発環境
65+
66+
#### 1. 仮想環境作成
67+
68+
```bash
69+
# 仮想環境作成
70+
python -m venv venv
71+
72+
# 仮想環境アクティベート
73+
# macOS/Linux:
74+
source venv/bin/activate
75+
# Windows:
76+
# venv\Scripts\activate
77+
```
78+
79+
#### 2. 依存関係インストール
80+
81+
```bash
82+
pip install -r tools/translate/requirements.txt
83+
```
84+
85+
#### 3. APIキー設定
86+
87+
`tools/translate/` ディレクトリに `.env` ファイルを作成：
88+
89+
```bash
90+
DIFY_API_KEY=your_dify_api_key_here
91+
```
92+
93+
#### 4. 翻訳実行
94+
95+
```bash
96+
# インタラクティブモード（初心者推奨）
97+
python tools/translate/main.py
98+
99+
# コマンドラインモード（ファイル指定）
100+
python tools/translate/main.py path/to/file.mdx [DIFY_API_KEY]
101+
```
102+
103+
> **ヒント**: IDEで右クリック「相対パスをコピー」をパラメータとして使用
104+
105+
### 他のリポジトリへのデプロイ
106+
107+
1. **ファイルコピー**:
108+
- `.github/workflows/translate.yml`
109+
- `tools/translate/` ディレクトリ全体
110+
111+
2. **GitHub Secrets設定**:
112+
- Repository Settings → Secrets and variables → Actions
113+
- `DIFY_API_KEY` シークレットを追加
114+
115+
3. **テスト**: ブランチでドキュメント修正し、自動翻訳機能を検証
116+
117+
### 技術詳細
118+
119+
- 並行翻訳は2タスクに制限、過度なAPI圧迫を回避
120+
- `.md` と `.mdx` ファイル形式をサポート
121+
- Dify API ワークフローモードベース
122+
123+
## TODO
124+
125+
- [ ] 既存翻訳の更新サポート

0 commit comments

Comments
 (0)