小說翻譯器 (Novel Translator)

一個專為「小說家になろう」(ncode.syosetu.com) 設計的 Chrome 瀏覽器擴展，使用 Google Gemini AI 將日文小說即時翻譯成繁體中文。

✨ 功能特色

• 🎯 智能段落識別 - 針對小說家になろう優化，自動過濾容器和重複段落
• 🚀 批次翻譯 - 每次處理 30 個段落，大幅提高翻譯效率
• 🎨 美觀介面 - 翻譯結果以漸層色塊顯示，易於閱讀
• 🔘 浮動按鈕 - 右下角浮動按鈕，隨時觸發翻譯
• 📊 詳細日誌 - 完整的操作記錄和 API 回應日誌，含段落元素資訊
• 🛡️ 智能錯誤處理 - 配額錯誤一次提醒，自動停止後續請求
• 💰 免費使用 - 使用 Google Gemini 免費 API（15 RPM / 1,500 RPD）

📋 系統需求

• Google Chrome 瀏覽器（最新版本）
• Google Gemini API Key（免費）

🔧 安裝步驟

1. 下載擴展

克隆或下載此專案到本地：

git clone <repository-url>
cd novel-translator

或直接下載 ZIP 檔案並解壓縮。

2. 獲取 Google Gemini API Key

1. 前往 Google AI Studio
2. 登入你的 Google 帳號
3. 點擊「Create API Key」或「建立 API 金鑰」
4. 選擇或建立一個專案
5. 複製生成的 API Key（格式類似：AIzaSy...）

注意：免費版有以下限制：

• 每分鐘 15 次請求（15 RPM）
• 每天 1,500 次請求（1,500 RPD）

3. 載入擴展到 Chrome

1. 開啟 Chrome 瀏覽器
2. 在網址列輸入 chrome://extensions/ 並按 Enter
3. 開啟右上角的「開發人員模式」(Developer mode)
4. 點擊「載入未封裝項目」(Load unpacked)
5. 選擇專案資料夾 novel-translator
6. 擴展會出現在擴展列表中

4. 設定 API Key

1. 點擊擴展圖示（或在擴展列表中點擊「詳細資料」）
2. 點擊「選項」或「Options」
3. 在「Google Gemini API Key」欄位貼上你的 API Key
4. 點擊「儲存設定」

🎮 使用方法

基本使用

1. 前往任何「小說家になろう」的小說頁面

   • 例如：https://ncode.syosetu.com/n3581fh/1/

2. 頁面右下角會出現藍色的「翻譯」浮動按鈕

3. 點擊「翻譯」按鈕開始翻譯

   • 按鈕會變成「翻譯中...」並顯示載入動畫
   • 每個段落下方會顯示翻譯進度

4. 翻譯完成後

   • 成功：翻譯結果顯示為綠色背景的區塊
   • 失敗：錯誤訊息顯示為紅色背景

檢視日誌

打開 Chrome 開發者工具（F12 或右鍵 → 檢查），切換到「Console」標籤，可以看到詳細的翻譯過程日誌：

[NovelTranslator] 開始翻譯所有段落
[NovelTranslator] 找到段落數: 42
[NovelTranslator] 總字元數: 8563
[Background] ========== 開始批次翻譯 ==========
[Background] 批次段落數: 42
[Background] API 回應狀態: 200 OK
[Background] 批次請求耗時: 3245ms

📁 專案結構

novel-translator/
├── manifest.json          # 擴展配置文件
├── src/
│   ├── background.js     # 後台服務（API 請求處理）
│   ├── content.js        # 內容腳本（頁面互動）
│   ├── options.html      # 設定頁面
│   ├── options.js        # 設定頁面邏輯
│   ├── popup.html        # 彈出視窗（預留）
│   └── styles.css        # 樣式表
└── README.md             # 本文件

⚙️ 工作原理

1. 智能段落識別：內容腳本會自動搜尋頁面中的小說段落

   • 嘗試多種選擇器：#novel_honbun, .novel_view, #honbun, .p-novel 等
   • 優先選擇 <p> 標籤作為段落
   • 自動過濾容器元素（檢測是否包含子段落）
   • 過濾超長文本（>= 3000 字，可能是容器而非段落）
   • 自動去除重複段落
   • 詳細日誌記錄每個段落的元素資訊

2. 批次處理：將段落分批（每批 30 個）發送到後台

   • 減少 API 請求次數（原本 30 個請求變成 1 個）
   • 批次間延遲 2 秒避免速率限制
   • 智能錯誤處理：遇到配額錯誤立即停止後續請求

3. API 翻譯：後台使用 Gemini API 進行翻譯

   • 使用編號標記 [1], [2], [3] 等區分段落
   • 解析返回結果並匹配對應段落
   • maxOutputTokens: 32768 支援長文翻譯
   • 完整的 API 請求/回應日誌記錄

4. 顯示結果：翻譯結果顯示在原文段落下方

   • 成功：綠色漸層背景
   • 失敗：紅色背景並顯示簡化錯誤訊息
   • 配額錯誤統一顯示：「API 配額已用盡，請稍後再試」
   • 完整錯誤訊息記錄在 Console 中

🔍 常見問題

Q: 翻譯按鈕沒有出現？

A: 確認以下幾點：

• 你是否在 ncode.syosetu.com 網域
• 擴展是否已正確載入（檢查 chrome://extensions/）
• 開啟開發者工具查看是否有錯誤訊息

Q: 翻譯失敗，顯示 API 錯誤？

A: 可能的原因：

• API Key 未設定或無效
• 超過 API 免費額度限制
• 網路連線問題

解決方法：

• 檢查 Options 頁面的 API Key 是否正確
• 確認當日/當分鐘的 API 配額是否用盡
• 查看開發者工具的 Console 了解詳細錯誤訊息

Q: 為什麼翻譯速度很慢？

A: 正常現象：

• 每批 30 個段落需要 3-5 秒處理
• 批次間有 2 秒延遲避免觸發速率限制
• 90 個段落大約需要 12-18 秒

Q: 可以翻譯其他網站嗎？

A: 目前專為「小說家になろう」優化，如需支援其他網站：

1. 修改 manifest.json 中的 matches 設定
2. 調整 content.js 中的段落選擇器

🛠️ 開發資訊

修改批次大小

在 src/content.js 中找到：

const BATCH_SIZE = 30; // 修改這個數字（建議範圍 20-50）

注意：批次太大可能超過 API 配額限制或輸出長度限制

修改批次間延遲

在 src/content.js 中找到：

await new Promise(resolve => setTimeout(resolve, 2000)); // 修改延遲時間（毫秒）

修改 Gemini 模型

在 src/background.js 中找到：

const modelName = storage.geminiModel || 'gemini-2.5-flash'; // 修改模型名稱

可用模型：

• gemini-2.5-flash - 最快，適合大量翻譯
• gemini-2.5-pro - 品質更好但較慢

📝 更新日誌

v1.0.2 (最新)

• ✅ 智能段落過濾
  • 優先選擇 <p> 標籤作為段落
  • 自動過濾容器元素（檢測是否包含子段落）
  • 過濾超長文本（>= 3000 字）避免選到容器
  • 自動去除重複段落
• ✅ 增強日誌系統
  • 段落內容預覽（前 50 字）
  • 顯示每個段落的元素資訊（標籤、class、id）
  • 詳細的過濾原因記錄
• ✅ 優化錯誤顯示
  • 配額錯誤簡化為「API 配額已用盡，請稍後再試」
  • 長錯誤訊息自動截斷為 100 字元
  • 完整錯誤訊息保留在 Console

v1.0.1

• ✅ 優化配額錯誤處理
  • 遇到 API 配額超限時只提醒一次
  • 自動停止後續翻譯請求
  • 顯示詳細的解決方案
• ✅ 調整批次大小為 30 個段落
  • 減少觸發配額限制的機會
  • 提高翻譯穩定性
• ✅ 增加 maxOutputTokens 至 32768
  • 支援更長的翻譯輸出

v1.0.0

• ✅ 初始版本
• ✅ 支援「小說家になろう」網站
• ✅ 批次翻譯功能
• ✅ 浮動翻譯按鈕
• ✅ 詳細日誌記錄
• ✅ 防止重複注入

📄 授權

MIT License

🤝 貢獻

歡迎提交 Issue 和 Pull Request！

⚠️ 免責聲明

• 本工具僅供個人學習和研究使用
• 翻譯品質取決於 Google Gemini API
• 請遵守目標網站的使用條款
• 請注意 API 使用配額限制

📧 聯絡方式

如有問題或建議，請開啟 Issue。

---

享受閱讀！Happy Reading! 📚✨