{"slug": "show-hn-gemmatrans-on-device-translation-for-macos-built-with-mlx", "title": "Show HN: GemmaTrans – On-device translation for macOS, built with MLX", "summary": "Developer Rand01ph released GemmaTrans, an on-device translation app for macOS built with MLX-Swift, supporting Google Gemma 4 and Tencent Hy-MT2 models fully offline. The app provides a local HTTP API, menu bar integration, and global hotkeys for text selection translation, with automatic language detection and model download from HuggingFace or ModelScope.", "body_md": "macOS 本地大模型划词翻译。基于 **MLX-Swift**（Apple Silicon 原生加速），支持多个本地翻译模型（Google **Gemma 4** / 腾讯混元 **Hy-MT2**），完全离线运行：\n\n**本地 HTTP API**（`127.0.0.1:8765`\n\n）：极简`/translate`\n\n接口 + 兼容`/v1/chat/completions`\n\n请求格式，PopClip、Bob、Raycast 等工具直连**menu bar app**：全局热键划词翻译，浮窗流式显示译文**智能双向**：自动检测语言——中文 → 英文，其他语言 → 中文（目标语言可配置）**多模型可选**：内置 Gemma 4（E4B/E2B，4-bit）与腾讯混元** Hy-MT2**（1.8B 翻译专用，4/8-bit）；设置页可下载、切换、删除模型，支持后台下载（边用边下）**性能可视**：翻译后显示每秒 token 速率（按模型分别记录），随时观察各模型快慢**模型下载**：首次启动按内存自动选 Gemma 档拉取（E4B≈4.9GB / E2B≈3.6GB），双源（HuggingFace / 国内 ModelScope）+ 断点续传\n\n```\ngit clone https://github.com/Rand01ph/gemma-trans && cd gemma-trans\n# MLX 的 Metal 着色器需要 xcodebuild（首次如提示缺 Metal 工具链：xcodebuild -downloadComponent MetalToolchain）\nxcodebuild -scheme gemma-trans-cli -destination 'platform=macOS' -skipMacroValidation -derivedDataPath .build-cli build\n.build-cli/Build/Products/Debug/gemma-trans-cli serve\n# 首次自动下载模型 → Model ready. Listening on http://127.0.0.1:8765\n```\n\n国内网络可用镜像：启动前 `export HF_ENDPOINT=https://hf-mirror.com`\n\n。`gemma-trans-cli spike`\n\n跑一次最小验证。\n\n```\n# 健康检查\ncurl -s http://127.0.0.1:8765/health\n\n# 翻译（自动检测语言，英文→中文）\ncurl -s -X POST http://127.0.0.1:8765/translate -H 'Content-Type: application/json' \\\n  -d '{\"text\": \"The quick brown fox jumps over the lazy dog.\"}'\n\n# 流式（SSE）\ncurl -s -N -X POST http://127.0.0.1:8765/translate -H 'Content-Type: application/json' \\\n  -d '{\"text\": \"今天天气真好\", \"stream\": true}'\n\n# /v1/chat/completions 接口\ncurl -s -X POST http://127.0.0.1:8765/v1/chat/completions -H 'Content-Type: application/json' \\\n  -d '{\"messages\": [{\"role\": \"user\", \"content\": \"Hello world\"}]}'\n```\n\n- 保持\n`gemma-trans-cli serve`\n\n（或 app）运行；用 app 时在菜单栏确认\"本地 API\"开启（默认已开） - 在 Finder 中双击\n`popclip/GemmaTrans.popclipext`\n\n目录，PopClip 会提示安装 - 任意 app 选中文字 → 点击 PopClip 弹条中的 GemmaTrans 图标 → 顶部显示译文\n\nPopClip 也可以用任何接受 `/v1/chat/completions`\n\n的扩展指向 `http://127.0.0.1:8765/v1`\n\n（API key 随意填）。\n\n| 字段 | 类型 | 说明 |\n|---|---|---|\n`text` |\nstring | 必填，待翻译文本（超长截断；上限随机器自动调优，16GB 机器默认 1500 字符，可在设置中手动覆盖） |\n`target` |\nstring? | 目标语言 BCP-47 码（如 `en` 、`zh-Hans` ）；缺省走智能双向 |\n`stream` |\nbool? | `true` 时返回 SSE 流 |\n\n响应：`{\"translation\": \"...\", \"detected\": \"en\", \"target\": \"zh-Hans\", \"truncated\": false}`\n\nSSE 流格式：若干 `data: {\"delta\": \"...\"}`\n\n→ 一条 `data: {\"translation\": 全文, ...}`\n\n→ `data: [DONE]`\n\n。\n\n兼容 `/v1/chat/completions`\n\n请求格式（含 `stream: true`\n\nSSE），方便接受该格式的工具直连本地引擎。取最后一条 `user`\n\n消息按智能双向翻译；`model`\n\n字段与 system 消息被忽略——这是翻译器，不是通用聊天，且全程本地，不连任何外部服务。\n\n`{\"status\": \"ready\"}`\n\n（200）或 `{\"status\": \"loading\"}`\n\n（503）。\n\n错误码：400（空文本/无效 JSON）、503（模型未加载 / 引擎忙超时 30s）、500（引擎错误，`error`\n\n字段含详情，常见于系统内存压力过高时 GPU 分配失败）。\n\n引擎与服务日志：`~/Library/Logs/GemmaTrans/gemmatrans.log`\n\n（GUI app 无 stderr，排障看这里）。\n\nAPI 可在菜单栏/设置中即时开关，无需重启。关闭后划词翻译不受影响——划词是进程内调用，不走端口。端口被其他程序占用时菜单会显示\"API 失败\"，划词照常可用；若占用者是另一个 GemmaTrans 实例（如 CLI serve），app 会拒绝启动以避免加载两份模型。\n\n```\nbrew install xcodegen   # 首次\ncd App && xcodegen generate\nxcodebuild -project GemmaTrans.xcodeproj -scheme GemmaTrans -configuration Debug -derivedDataPath build build\nopen build/Build/Products/Debug/GemmaTrans.app\n```\n\n- 启动后弹出主窗口（含模型下载进度），同时 menu bar 出现 💬 图标；模型加载完成（约 15s）后图标变实心，并在\n`127.0.0.1:8765`\n\n提供 API（app 与 CLI serve 二者跑一个即可，同时跑会端口冲突） **三种译法**（均无需任何系统权限）：- 主窗口里粘贴/输入文字 → 点「翻译」流式显示译文\n- 任意 app 选中文字 → 按\n`⌥⌘T`\n\n一键翻译选中内容，**无需先复制**；也可从「服务」菜单点「Translate with GemmaTrans」- 这是 macOS「服务」快捷键，默认\n`⌥⌘T`\n\n。macOS 不一定会自动启用声明的默认值——若按了没反应，去 系统设置 › 键盘 › 键盘快捷键 › 服务 › 文本，勾选并确认 Translate with GemmaTrans 的快捷键（一次性，之后长期生效；也可在这里改键）\n\n- 这是 macOS「服务」快捷键，默认\n- 复制文字后按\n`⌥D`\n\n→ 翻译剪贴板内容（鼠标旁浮窗流式显示，Esc 关闭，可一键复制）\n\n- 菜单\"设置…\"可改目标语言、API 端口和剪贴板热键\n- 设置\"性能\"区默认按机器内存自动配置 KV cache 与输入上限（加载时还会按当前可用内存降档），也可手动覆盖\n\n```\nGemmaTransKit     核心库：MLX-Swift 引擎封装、语言检测（NaturalLanguage）、提示词、按内存自动调优\nGemmaTransServer  HTTP 层：FlyingFox，/translate + /v1/chat/completions + SSE\ngemma-trans-cli   命令行：spike / serve\n```\n\n", "url": "https://wpnews.pro/news/show-hn-gemmatrans-on-device-translation-for-macos-built-with-mlx", "canonical_source": "https://github.com/Rand01ph/gemma-trans", "published_at": "2026-06-27 14:45:33+00:00", "updated_at": "2026-06-27 15:05:09.127215+00:00", "lang": "en", "topics": ["machine-learning", "large-language-models", "ai-tools", "developer-tools"], "entities": ["Rand01ph", "GemmaTrans", "MLX-Swift", "Google", "Gemma 4", "Tencent", "Hy-MT2", "HuggingFace"], "alternates": {"html": "https://wpnews.pro/news/show-hn-gemmatrans-on-device-translation-for-macos-built-with-mlx", "markdown": "https://wpnews.pro/news/show-hn-gemmatrans-on-device-translation-for-macos-built-with-mlx.md", "text": "https://wpnews.pro/news/show-hn-gemmatrans-on-device-translation-for-macos-built-with-mlx.txt", "jsonld": "https://wpnews.pro/news/show-hn-gemmatrans-on-device-translation-for-macos-built-with-mlx.jsonld"}}