Translate Gadget

一个基于 PySide6 的桌面翻译小工具，支持动态背景色适配，让翻译窗口自然融入桌面环境。

功能特性

• 动态背景色：自动采样窗口周围背景色，输入框背景与桌面环境融为一体
• 透明窗口：窗口背景完全透明，无边框设计
• 始终置顶：翻译窗口始终显示在屏幕最上层
• 自动翻译：输入文本后按 Enter 自动翻译，支持中→英、英→中双向翻译
• 智能语言检测：自动识别输入语言，无需手动切换
• 快捷键操作：
  • Enter - 触发翻译
  • Ctrl+Enter - 清空输入框和翻译结果
  • F4 - 打开设置页面
  • 双击输入框 - 清空输入框
  • Ctrl+左键拖拽 - 移动窗口位置
• 系统托盘：托盘图标 + 右键菜单（设置、退出）
• 设置页面：配置翻译 API 凭证，设置持久化存储

快速开始

环境要求

• Python 3.12+
• Windows 10/11 或 Ubuntu 22.04+
• Linux 下若需要中文输入法，建议安装 fcitx5 的 Qt6 支持（可用 scripts/install_fcitx5_qt6.sh）

安装

# 从 PyPI 安装（推荐，装完即可全局使用命令）
uv tool install translate-gadget
# 或
pip install translate-gadget

# 启动
translate-gadget

源码运行：

# 克隆项目
git clone https://github.com/eleksbai/translate-gadget.git
cd translate-gadget

# 安装依赖（含 dev 工具链）
uv sync

# 运行程序
uv run python -m translate_gadget

配置翻译 API

注意：目前仅支持阿里云翻译 API。注册阿里云账号后，可获得免费翻译额度。

1. 按 F4 或右键托盘图标选择「设置」
2. 填写阿里云翻译 API 凭证：
   • App ID：阿里云 AccessKey ID
   • 密钥：阿里云 AccessKey Secret
3. 点击「保存」，配置立即生效

获取阿里云 API 凭证：

1. 访问 阿里云官网 注册账号
2. 开通「机器翻译」服务（定价说明）
3. 在 AccessKey 管理页面 创建 AccessKey
4. 新用户享有免费翻译额度，详见阿里云官方说明

使用说明

基本操作

1. 激活窗口：点击托盘图标显示翻译窗口
2. 输入文本：在输入框中输入要翻译的文本
3. 执行翻译：按 Enter 键触发翻译
4. 查看结果：翻译结果显示在输入框下方
5. 清空内容：按 Ctrl+Enter 或双击输入框清空

窗口位置

• 窗口默认位于屏幕左上角
• 翻译结果显示在输入框下方，窗口自动向下扩展
• 按住 Ctrl + 鼠标左键拖拽输入框，可移动窗口到任意位置

动态背景色

窗口会自动采样周围 20 像素边距区域的背景色：

• 采样频率：每秒 1 次
• 智能过滤：按颜色出现频率取前 70% 数据，过滤文字、图标等干扰
• 性能优化：自动调整采样密度，确保采样点数不超过 1 万

项目结构

translate-gadget/
├── .github/workflows/publish.yml  # 打 tag 后自动构建并发布到 PyPI
├── src/translate_gadget/
│   ├── __main__.py          # 程序入口
│   ├── window.py            # 主窗口（动态取色、翻译界面）
│   ├── translator.py        # 翻译 API 接口
│   ├── config.py            # 配置管理
│   ├── tray.py              # 系统托盘
│   ├── settings_dialog.py   # 设置对话框
│   ├── utils.py             # 工具函数（语言检测、包内资源路径）
│   └── resources/           # 随包分发的资源（图标等）
├── scripts/                 # 环境辅助与手工验证脚本
├── tests/                   # 测试代码
├── LICENSE
├── .pre-commit-config.yaml  # 提交前检查（ruff + pytest）
└── pyproject.toml           # 项目配置（元数据、依赖、ruff/pytest）

技术栈

开发

uv sync                        # 安装运行与 dev 依赖（pytest / ruff / pre-commit）
uv run pytest                  # 运行测试
uv run ruff check              # 静态检查
uv run ruff format             # 代码格式化
uv run pre-commit install      # 安装提交前钩子
uv build                       # 构建 sdist + wheel

版本号来自 git tag（由 hatch-vcs 推导），不需要手工修改 pyproject.toml。

发布

发布由 GitHub Actions（.github/workflows/publish.yml）完成：推送 v* tag 后自动跑 lint、测试，用 uv build 构建，并通过 PyPI 的 Trusted Publishing（OIDC，无需 API Token）上传。

前置条件（只需配置一次）：

1. GitHub 仓库 Settings → Environments 中创建名为 pypi 的环境
2. PyPI → 项目 translate-gadget → Publishing → 添加 pending publisher：
   • Repository：eleksbai/translate-gadget
   • Workflow name：publish.yml
   • Environment name：pypi

# 1. 先把改动提交并推送到 master（tag 必须指向 master 最新提交）
git push

# 2. 打 tag：v<major>.<minor>.<YYMMDD>，例如 v0.1.261030
git tag v0.1.261030

# 3. 推送 tag 触发发布
git push origin v0.1.261030

# 若发错了：在 master 上修好后重新打 tag 递增补丁号
git tag v0.1.261030.1
git push origin v0.1.261030.1

注意：tag 必须指向 master 最新提交且匹配 v<major>.<minor>.<YYMMDD>[.<n>]；已上传的版本号不能在 PyPI 上覆盖或复用。

许可证

MIT License