Metadata-Version: 2.4
Name: iamtrans
Version: 1.0.1
Summary: Terminal-based translation tool with TUI interface
Author-email: Thierry Cao <iamthierrycao@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Thierry Cao
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/thierrycao/iamtrans
Project-URL: Documentation, https://github.com/thierrycao/iamtrans#readme
Project-URL: Repository, https://github.com/thierrycao/iamtrans
Project-URL: Issues, https://github.com/thierrycao/iamtrans/issues
Keywords: translation,translate,tui,terminal,youdao,google
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.40.0
Requires-Dist: rich>=13.0.0
Requires-Dist: deep-translator>=1.11.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0.0; extra == "build"
Requires-Dist: build>=1.0.0; extra == "build"
Requires-Dist: twine>=5.0.0; extra == "build"
Dynamic: license-file

<div align="center">

# iamtrans

**终端翻译，就该这么用**

Enter 一敲，翻译就到。不换行，不卡顿，不占屏。

[![PyPI](https://img.shields.io/pypi/v/iamtrans?color=blue)](https://pypi.org/project/iamtrans/)
[![Python](https://img.shields.io/pypi/pyversions/iamtrans?color=green)](https://pypi.org/project/iamtrans/)
[![License](https://img.shields.io/badge/license-MIT-orange)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/iamtrans?color=purple)](https://pypi.org/project/iamtrans/)

</div>

---

## 这玩意儿是什么？

一个终端翻译工具。

但它不是那种"输入→等待→输出"的玩意儿。

```bash
$ iamtrans Hello World
你好世界
```

太简单？那就启动浮窗：

```
+----------------------------------------------------------------------+
| +----------+--------------------+--------------------+              |
| | 输入框    | 词典               | 翻译               |              |
| |          |                    |                    |              |
| | Hello    | hello              | 你好               |              |
| |          | UK[...] US[...]    |                    |              |
| | 有道     | [int.] 喂，你好    |                    |              |
| | 翻页     | 例: Hello, how are |                    |              |
| +----------+--------------------+--------------------+              |
| Enter 翻译 | Esc 关闭 | Tab 切换引擎                             |
+----------------------------------------------------------------------+
```

**50字符宽，浮在终端上方**。不挡视线，不占全屏，看着舒服。

---

## 为什么用它？

| 问题 | iamtrans 的答案 |
|------|-----------------|
| Enter 会换行？ | 重写了 TextArea，Enter = 翻译，不换行 |
| 网络请求卡 UI？ | Worker 后台线程，主线程继续响应 |
| 要选语言？ | 检测中文自动翻译成英文，检测英文自动翻译成中文 |
| 要 API key？ | 有道免费接口，用就完事了 |
| 词典只支持英文？ | 中英文都行，有音标有拼音有例句 |

---

## 安装

### pip（推荐）

```bash
pip install iamtrans
```

### 二进制（无需 Python）

从 [Releases](https://github.com/thierrycao/iamtrans/releases) 下载：

| 平台 | 文件 |
|------|------|
| Linux | iamtrans-linux |
| macOS | iamtrans-macos |
| Windows | iamtrans-windows.exe |

```bash
chmod +x iamtrans-macos
./iamtrans-macos
```

### 从源码

```bash
git clone https://github.com/thierrycao/iamtrans.git
cd iamtrans
pip install -e .
```

---

## 使用

### TUI 模式

直接运行，启动浮窗：

```bash
iamtrans
```

**快捷键**：

| 键 | 作用 |
|----|------|
| Enter | 翻译（关键创新点） |
| Esc | 关闭 |
| Tab | 切换引擎 |
| 上/下 | 滚动翻页 |

### 命令行模式

适合脚本调用、管道操作：

```bash
iamtrans Hello World
# -> 你好世界

iamtrans 你好世界
# -> Hello World（自动检测中文，翻译成英文）

iamtrans --to ja Hello
# -> 

iamtrans --list
# -> 列出所有语言
```

---

## 词典功能

**输入英文单词**：

```
hello -> UK[həˈləʊ] US[həˈloʊ]
       [int.] 喂，你好（用于问候）
       例: "Hello, how are you today?"
       [n.] 招呼，问候
```

**输入中文单字**：

```
好 -> 拼音: hào/hǎo
     [形容词] 美；优点多的；令人满意的
     例: 这孩子长得真好
     [动词] 喜爱；喜欢
     例: 这个人好搬弄是非
```

有道词典 `newhh` 字段，多音字、词性、例句都有。

---

## 翻译引擎

| 引擎 | 特点 | 限制 |
|------|------|------|
| youdao | 默认，中文友好 | 无 |
| google | 稳定可靠 | 无 |
| mymemory | 欧洲服务 | 5000 字符/日 |

切换引擎：Tab 键，或 `--engine google`

---

## 技术细节

### 异步处理流程

```
用户输入 -> Enter 键
         -> TranslateTextArea.on_key() 捕获
         -> post_message(TranslateRequest)
         -> run_worker(thread=True) 后台执行
         -> 有道 API -> 网络延迟 300ms
         -> post_message(TranslateResult)
         -> 更新 UI
```

主线程从未停止响应。你的键盘输入，它一直听着。

### 语言检测算法

```python
def detect_language(text):
    # 中文字符：Unicode 区间 \u4e00-\u9fff
    if any('\u4e00' <= c <= '\u9fff' for c in text):
        return 'zh-CN'
    
    # 英文：字母占比 > 70%
    alpha_ratio = alpha_chars / total_chars
    return 'en' if alpha_ratio > 0.7 else 'auto'
```

简单，但够用。

### 有道 API 端点

| 用途 | URL | 参数 |
|------|-----|------|
| 翻译 | dict.youdao.com/suggest | q=text&le=eng|ch |
| 英文词典 | dict.youdao.com/jsonapi | q=word&le=eng |
| 中文词典 | dict.youdao.com/jsonapi | q=字&le=ch |

解析 JSON，提取 `ec`（英文）或 `newhh`（中文）字段。

---

## 打包发布

项目自带脚本，一键搞定：

```bash
# 本地打包 wheel + sdist
./scripts/build_local.sh

# 本地二进制
./scripts/build_binary.sh

# 版本管理
./scripts/version.sh bump patch  # 1.0.0 -> 1.0.1

# 一键发布（打包 + tag + GitHub 推送）
./scripts/release.sh 1.0.1
```

推送 tag 后，GitHub Actions 自动：
- 发布到 PyPI
- 构建 Linux/macOS/Windows 二进制
- 创建 GitHub Release

**设置 PyPI Token**：`repo -> Settings -> Secrets -> PYPI_TOKEN`

---

## 项目结构

```
src/iamtrans/
├── main.py           # CLI 入口，参数解析
├── translator/
│   └── engine.py     # 翻译引擎 + 词典 + 语言检测
└── ui/
    └── app.py        # Textual TUI，三列布局，Worker 异步

scripts/              # 打包发布脚本
.github/workflows/    # CI/CD：ci.yml + release.yml
docs/ARCHITECTURE.md  # 技术架构详解
```

---

## 为什么是 Textual？

Textual 是终端 UI 的现代选择：
- 异步友好（Worker API）
- CSS 样式（不用手画边框）
- 事件驱动（Message 消息流）

比 curses 简洁，比 prompt_toolkit 强大。

---

## License

MIT。随便用，随便改，随便发。

---

<div align="center">

**有问题？[开个 Issue](https://github.com/thierrycao/iamtrans/issues)**

**想贡献？[看 CONTRIBUTING.md](CONTRIBUTING.md)**

**想懂技术？[看 ARCHITECTURE.md](docs/ARCHITECTURE.md)**

</div>
