laradoc-trans

一套由 AI 驅動，專為 Laravel 官方文件設計的自動化翻譯工具。

laradoc-trans 旨在簡化繁體中文化 Laravel 文件的繁瑣流程。它能自動比對版本差異、管理翻譯進度，並透過強大的 AI 模型確保翻譯品質，讓您能專注於內容的校對與潤飾。

✨ 功能亮點

• 🤖 AI 驅動翻譯：預設使用 Google Gemini，並可透過 LangChain 彈性更換為 OpenAI GPT 等不同模型。
• 🔄 智慧差異比對：只翻譯官方文件更新的部分，無需重複勞動，節省時間與成本。
• 📈 進度自動管理：自動記錄與追蹤每個檔案的翻譯狀態，即使中斷也能無縫接續。
• ✅ 品質驗證報告：提供 validate 指令，對比原文與譯文，產生詳細的結構與內容一致性報告。
• ⚙️ 高度可設定：可自訂提示詞 (Prompt) 與模型，以符合您的特定翻譯風格與需求。

🚀 5 分鐘快速上手

1. 安裝工具 (建議 Node.js v22+):

   npm install -g laradoc-trans

   要使用本工具也要確認 git 都有安裝好

2. 初始化工作區: 此命令會自動建立 workspace 目錄、複製官方文件（預設分支），並為您準備好 .env 設定檔。

   laradoc-trans init --workspace-path workspace
   cd workspace

3. 填寫 API 金鑰: 編輯 workspace/.env 檔案，設定要使用的 LLM_PROVIDER 並填入對應的 API 金鑰。

   # 可選 'gemini' 或 'openai'，預設為 'gemini'
   LLM_PROVIDER="gemini"
   
   # 如果使用 gemini
   GEMINI_API_KEY=YOUR_GEMINI_API_KEY
   
   # 如果使用 openai
   # OPENAI_API_KEY=YOUR_OPENAI_API_KEY

4. 執行翻譯:

   # 嘗試翻譯 5 個檔案看看效果，翻譯後的檔案會暫存於工作區的 `tmp` 目錄。
   laradoc-trans run --branch 12.x --limit 5

   # 完整翻譯，會將剩餘未翻譯完的檔案進行翻譯，翻譯結果會存放於工作區的 `repo/target` 目錄。
   laradoc-trans run --branch 12.x --all

5. 驗證翻譯品質:

   # 針對指定分支，比對原始與翻譯檔案的內容與結構一致性
   laradoc-trans validate --branch 12.x
   
   # 完成後，請查看 `workspace/validate-report` 目錄下的報告

⚠️⚠️ 注意事項 ⚠️⚠️

VS Code 使用者

如果您使用 VS Code 開啟翻譯後的 .md 檔案，強烈建議您在專案的工作區設定中，關閉 Markdown All in One 套件的「儲存時自動更新 TOC」功能。

這個功能可能會在您儲存檔案時，非預期地修改文件的目錄結構，導致後續的 validate 驗證失敗。

解決方案1：修改設定檔

在您的工作區根目錄建立或修改 .vscode/settings.json 檔案，並加入以下設定：

{
  "markdown.extension.toc.updateOnSave": false
}

解決方案2：直接禁用工作區的擴充功能

如果您希望更徹底地隔離工作區的環境，避免任何潛在的擴充功能衝突，可以選擇直接禁用所有在此工作區建議的擴充功能。

如圖示找到停用/啟用按鈕，選擇停用(工作區)：

深入了解

• 想知道更多的用法？ 請閱讀 ➡️ 使用者指南 (User Guide)

• 想知道如何利用 validate 命令提升翻譯品質？ 請閱讀 ➡️ Validate 指南

• 想了解程式內部設計或參與開發？ 請閱讀 ➡️ 開發者指南 (Developer Guide)

👨‍💻 作者

• Pigo Chu [email protected]

📄 授權

本專案採用 AGPL-3.0-only 授權.