Ppt Translator

🚀 使用亞馬遜Bedrock的PowerPoint翻譯器

這是一款強大的PowerPoint翻譯工具，藉助亞馬遜Bedrock模型實現高質量翻譯。該服務既可以作為獨立的命令行工具使用，也能作為FastMCP（快速模型上下文協議）服務，與像Amazon Q Developer這樣的AI助手集成。它在翻譯PowerPoint演示文稿時，能保留其格式和結構。

✨ 主要特性

• PowerPoint翻譯：翻譯PowerPoint演示文稿中的文本內容。
• 亞馬遜Bedrock集成：利用亞馬遜Bedrock模型進行高質量翻譯。
• 格式保留：保持原有的格式、佈局和樣式。
• 獨立與MCP支持：既可以作為命令行工具使用，也能通過FastMCP與AI助手集成。
• 多語言支持：支持多種語言之間的翻譯。
• 批量處理：能夠高效處理多個幻燈片和文本元素。
• 選擇性翻譯：可以翻譯整個演示文稿或特定幻燈片。

💻 使用示例

基礎用法

翻譯示例

PowerPoint翻譯器在準確翻譯內容的同時，能保持原有的格式：

英文原始演示幻燈片 佈局複雜	翻譯為韓語的同一演示文稿 格式和佈局保留

Kiro MCP示例

命令行使用示例

翻譯整個演示文稿：

uv run python server.py --translate --input-file presentation.pptx --target-language ko

翻譯特定幻燈片：

uv run python server.py --translate-slides "1,3,5" --input-file presentation.pptx --target-language ja

獲取幻燈片信息：

uv run python server.py --slide-info --input-file presentation.pptx

高級用法

獨立命令行使用

PowerPoint翻譯器可以直接從命令行使用：

# 將整個演示文稿翻譯成韓語
uv run python server.py --translate --input-file orig.pptx --target-language ko

# 翻譯特定幻燈片（單個幻燈片）
uv run python server.py --translate-slides "1,3,5" --input-file orig.pptx --target-language ko

# 翻譯幻燈片範圍
uv run python server.py --translate-slides "2-4" --input-file orig.pptx --target-language ko

# 混合翻譯（單個 + 範圍）
uv run python server.py --translate-slides "1,3-5,8" --input-file orig.pptx --target-language ko

# 獲取幻燈片信息和預覽
uv run python server.py --slide-info --input-file orig.pptx

# 直接使用python
python server.py --translate --input-file orig.pptx --target-language ko
python server.py --translate-slides "1,3" --input-file orig.pptx --target-language ko

FastMCP服務器模式（用於AI助手集成）

啟動FastMCP服務器，以便與像Amazon Q Developer這樣的AI助手集成：

# 使用uv（推薦）
uv run python server.py --mcp

# 直接使用python
python server.py --mcp

📦 安裝指南

前提條件

• Python 3.11或更高版本
• 具有Bedrock訪問權限的AWS賬戶
• 配置了適當憑證的AWS CLI
• 訪問亞馬遜Bedrock模型（例如Claude、Nova等）

AWS憑證設置

在使用此服務之前，請確保您的AWS憑證已正確配置。您有以下幾種選擇：

1. AWS CLI配置（推薦）：

aws configure

這將提示您輸入：

• AWS訪問密鑰ID
• AWS秘密訪問密鑰
• 默認區域名稱
• 默認輸出格式

2. AWS配置文件配置：

aws configure --profile your-profile-name

3. 環境變量（如有需要）：

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

4. IAM角色（在EC2實例上運行時）

該服務將自動使用您配置的AWS憑證。您可以在.env文件中指定要使用的配置文件。

安裝步驟

1. 克隆倉庫：

git clone <repository-url>
cd ppt-translator

2. 使用uv安裝依賴項（推薦）：

uv sync

或者使用pip：

pip install -r requirements.txt

3. 設置環境變量：

cp .env.example .env

編輯.env文件並進行配置：

# AWS配置
AWS_REGION=us-east-1
AWS_PROFILE=default

# 翻譯配置
DEFAULT_TARGET_LANGUAGE=ko
BEDROCK_MODEL_ID=us.anthropic.claude-3-7-sonnet-20250219-v1:0

# 翻譯設置
MAX_TOKENS=4000
TEMPERATURE=0.1
ENABLE_POLISHING=true
BATCH_SIZE=20
CONTEXT_THRESHOLD=5

# 調試設置
DEBUG=false

注意：如果您已經使用aws configure配置了AWS憑證，則.env文件中不需要AWS憑證（訪問密鑰ID和秘密訪問密鑰）。該服務將自動使用您的AWS CLI憑證。

📚 詳細文檔

FastMCP設置（Amazon Q Developer和Kiro）

1. 安裝

如果您尚未安裝Amazon Q Developer或Kiro，請參考以下鏈接：

• Amazon Q Developer CLI：https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-installing.html
• Kiro：https://kiro.dev

2. 配置FastMCP服務器

創建或更新您的Q Developer FastMCP配置文件：

Kiro

用戶級別：~/.kiro/settings/mcp.json

Amazon Q Developer

在macOS/Linux上：~/.aws/amazonq/mcp.json 在Windows上：%APPDATA%\amazonq\mcp.json

添加PowerPoint翻譯器FastMCP服務器配置： 使用uv：

{
  "mcpServers": {
    "ppt-translator": {
      "command": "uv",
      "args": ["run", "/path/to/ppt-translator/fastmcp_server.py"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default",
        "BEDROCK_MODEL_ID": "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
      },
      "disabled": false,
      "autoApprove": [
        "translate_powerpoint",
        "get_slide_info",
        "get_slide_preview",
        "translate_specific_slides"
      ]
    }
  }
}

使用python直接配置：

{
  "mcpServers": {
    "ppt-translator": {
      "command": "python",
      "args": ["/path/to/ppt-translator/fastmcp_server.py"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default",
        "BEDROCK_MODEL_ID": "us.anthropic.claude-3-7-sonnet-20250219-v1:0"
      },
      "disabled": false,
      "autoApprove": [
        "translate_powerpoint",
        "get_slide_info",
        "get_slide_preview",
        "translate_specific_slides"
      ]    
    }
  }
}

重要：將/path/to/ppt-translator/替換為您克隆倉庫的實際路徑。

3. 驗證FastMCP服務器

測試FastMCP服務器是否正常工作：

# 導航到項目目錄
cd /path/to/ppt-translator

# 使用uv測試FastMCP服務器
uv run python server.py --mcp --test

# 或者直接使用python測試
python server.py --mcp --test

4. 使用PowerPoint翻譯

連接成功後，您可以使用以下命令（用戶輸入不必為英語）：

將original.pptx翻譯成韓語

請將original.pptx的第10到13張幻燈片翻譯成日語。

可用的FastMCP工具

FastMCP服務器提供以下工具：

• translate_powerpoint：翻譯整個PowerPoint演示文稿

  • 參數：
    • input_file：輸入PowerPoint文件的路徑（.pptx）
    • target_language：目標語言代碼（默認：'ko'）
    • output_file：翻譯輸出文件的路徑（可選，自動生成）
    • model_id：亞馬遜Bedrock模型ID（默認：Claude 3.7 Sonnet）
    • enable_polishing：啟用自然語言潤色（默認：true）

• translate_specific_slides：僅翻譯PowerPoint演示文稿中的特定幻燈片

  • 參數：
    • input_file：輸入PowerPoint文件的路徑（.pptx）
    • slide_numbers：要翻譯的幻燈片編號，用逗號分隔（例如，"1,3,5"或"2-4,7"）
    • target_language：目標語言代碼（默認：'ko'）
    • output_file：翻譯輸出文件的路徑（可選，自動生成）
    • model_id：亞馬遜Bedrock模型ID（默認：Claude 3.7 Sonnet）
    • enable_polishing：啟用自然語言潤色（默認：true）

• get_slide_info：獲取PowerPoint演示文稿中幻燈片的信息

  • 參數：
    • input_file：PowerPoint文件的路徑（.pptx）
  • 返回：包含幻燈片數量和每張幻燈片內容預覽的概述

• get_slide_preview：獲取特定幻燈片內容的詳細預覽

  • 參數：
    • input_file：PowerPoint文件的路徑（.pptx）
    • slide_number：要預覽的幻燈片編號（從1開始索引）

• list_supported_languages：列出所有支持的目標翻譯語言

• list_supported_models：列出所有支持的亞馬遜Bedrock模型

• get_translation_help：獲取使用翻譯器的幫助信息

配置

環境變量

• AWS_REGION：Bedrock服務的AWS區域（默認：us-east-1）
• AWS_PROFILE：要使用的AWS配置文件（默認：default）
• DEFAULT_TARGET_LANGUAGE：默認的目標翻譯語言（默認：ko）
• BEDROCK_MODEL_ID：用於翻譯的Bedrock模型ID（默認：us.anthropic.claude-3-7-sonnet-20250219-v1:0）
• MAX_TOKENS：翻譯請求的最大令牌數（默認：4000）
• TEMPERATURE：AI模型的溫度設置（默認：0.1）
• ENABLE_POLISHING：啟用翻譯潤色（默認：true）
• BATCH_SIZE：批量處理的文本數量（默認：20）
• CONTEXT_THRESHOLD：觸發上下文感知翻譯的文本數量（默認：5）
• DEBUG：啟用調試日誌記錄（默認：false）

支持的語言

該服務支持主要語言之間的翻譯，包括：

• 英語（en）
• 韓語（ko）
• 日語（ja）
• 簡體中文（zh）
• 繁體中文（zh-tw）
• 西班牙語（es）
• 法語（fr）
• 德語（de）
• 意大利語（it）
• 葡萄牙語（pt）
• 俄語（ru）
• 阿拉伯語（ar）
• 印地語（hi）
• 等等...

故障排除

常見問題

1. 未找到AWS憑證：

• 確保AWS憑證已正確配置
• 檢查AWS CLI配置：aws configure list

2. Bedrock訪問被拒絕：

• 驗證您的AWS賬戶是否有權限訪問Bedrock
• 檢查指定的模型是否在您的區域可用

3. FastMCP連接問題：

• 驗證mcp.json中的路徑是否正確
• 檢查Python和依賴項是否已正確安裝
• 查看Q Developer中的日誌以獲取錯誤消息
• 測試服務器：uv run python server.py --mcp --test

4. PowerPoint文件問題：

• 確保輸入文件是有效的PowerPoint（.pptx）文件
• 檢查輸入和輸出路徑的文件權限

5. 模塊導入錯誤：

• 使用uv run確保正確激活虛擬環境
• 安裝依賴項：uv sync

調試模式

啟用調試日誌記錄：

uv run python server.py --mcp --debug

開發

項目結構

ppt-translator/
├── server.py              # 主服務器入口點（獨立和MCP）
├── fastmcp_server.py      # FastMCP服務器實現
├── ppt_handler.py         # PowerPoint處理邏輯
├── translation_engine.py  # 翻譯服務
├── bedrock_client.py      # 亞馬遜Bedrock客戶端
├── config.py             # 配置管理
├── dependencies.py       # 依賴管理
├── text_utils.py         # 文本處理實用工具
├── prompts.py            # 翻譯提示
├── requirements.txt      # Python依賴項
├── pyproject.toml        # 項目配置（uv）
└── imgs/                 # 示例圖像和截圖

使用uv進行開發

本項目使用uv進行依賴管理：

# 安裝依賴項
uv sync

# 運行服務器
uv run python server.py --mcp

# 運行測試
uv run python server.py --mcp --test

# 添加新依賴項
uv add package-name

# 更新依賴項
uv sync --upgrade

📄 許可證

本項目採用MIT許可證 - 詳情請參閱LICENSE文件。