Metadata-Version: 2.5
Name: translate-gadget
Version: 0.1.261102
Summary: 一个基于 PySide6 的桌面翻译小工具：动态背景色、无边框悬浮窗、系统托盘与阿里云机器翻译
Project-URL: Homepage, https://github.com/eleksbai/translate-gadget
Project-URL: Repository, https://github.com/eleksbai/translate-gadget
Project-URL: Issues, https://github.com/eleksbai/translate-gadget/issues
Author-email: hyman <eleksbai@qq.com>
License-Expression: MIT
License-File: LICENSE
Keywords: chinese,desktop,gui,pyside6,translate,translation,tray
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: alibabacloud-alimt20181012<2.0.0,>=1.0.1
Requires-Dist: alibabacloud-tea-openapi<1.0.0,>=0.3.1
Requires-Dist: pyside6>=6.7
Description-Content-Type: text/markdown

# 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`）

### 安装

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

# 启动
translate-gadget
```

源码运行：

```bash
# 克隆项目
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. 访问 [阿里云官网](https://www.aliyun.com/) 注册账号
2. 开通「机器翻译」服务（[定价说明](https://help.aliyun.com/zh/machine-translation/product-overview/pricing-of-machine-translation)）
3. 在 [AccessKey 管理页面](https://ram.console.aliyun.com/manage/ak) 创建 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）
```

## 技术栈

| 组件 | 技术 |
|------|------|
| GUI 框架 | PySide6 (Qt 6) |
| 配置存储 | QSettings |
| 依赖管理 | uv |

## 开发

```bash
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`

```bash
# 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
