localtrans

English | 简体中文

A command-line translator for technical text. Translates Chinese to professional English via any OpenAI-compatible local backend (LM Studio / Ollama / vLLM / …).

Ships two equivalent commands: localtrans and lt.

---

Table of Contents

• Install
• First-time setup: lt init
• Usage
• Configuration
  • Environment variables
  • Config file
  • Backend recipes: LM Studio / Ollama / vLLM
• Upgrade & Uninstall

---

Install

uv is recommended. From the project root:

# recommended
uv tool install .

# or
pipx install .

# or
python -m pip install .

Both localtrans and lt will be available on your PATH.

---

First-time setup: lt init

Run this right after installing. It prompts for the model name and writes it to the local config file:

lt init

Enter the model identifier to use (e.g. gemma-3-4b-it, qwen2.5:7b). It is written to:

~/.config/localtrans/config.json

To change the backend URL, timeout, reasoning mode, etc., see Configuration below.

---

Usage

Basic translation

lt "这个函数会导致线程阻塞"
echo "内存泄漏" | lt

-p / --paste: copy result to clipboard

The translation is written to the clipboard instead of stdout.

lt -p "这个函数会导致线程阻塞"

Requires one of: wl-clipboard / xclip / xsel (Linux), pbcopy (macOS), clip (Windows).

-s / --selection: translate the current selection

Reads the system primary selection (falls back to the clipboard if empty), writes the result back to the clipboard, and sends a desktop notification. No terminal output — ideal for a global hotkey.

lt -s

Window-manager examples:

# i3 / sway
bindsym $mod+t exec --no-startup-id lt -s

# Hyprland
bind = SUPER, T, exec, lt -s

Requires: one of wl-clipboard / xclip / xsel, plus libnotify (notify-send).

---

Configuration

Environment variables

Variable	Default	Purpose
TRANS_BASE_URL	http://localhost:1234/v1	OpenAI-compatible endpoint
TRANS_MODEL	config file / gemma-4-e4b	Model id (env var wins over config)
TRANS_TIMEOUT	60	Request timeout, seconds
TRANS_DISABLE_THINKING	false	When true, sends reasoning_effort to disable thinking
TRANS_REASONING_EFFORT	none	Paired with the option above
LOCALTRANS_CONFIG_PATH	—	Override config file path
XDG_CONFIG_HOME	—	Override the config root directory

Config file

Path: ~/.config/localtrans/config.json (overridable via LOCALTRANS_CONFIG_PATH / XDG_CONFIG_HOME).

lt init only writes the model field. For other settings, edit the file directly or use environment variables.

Backend recipes

LM Studio (default)

LM Studio listens on http://localhost:1234/v1 out of the box — no extra setup needed:

lt init   # enter the model name currently loaded in LM Studio

Ollama

Ollama exposes an OpenAI-compatible API on port 11434. Point localtrans at it:

export TRANS_BASE_URL="http://localhost:11434/v1"
lt init   # enter an Ollama model name, e.g. qwen2.5:7b

Add the export line to your shell rc (.zshrc / .bashrc) to make it persistent.

vLLM / other OpenAI-compatible servers

Any server exposing /v1/chat/completions works — just set the base URL:

export TRANS_BASE_URL="http://your-host:8000/v1"
export TRANS_MODEL="your-model-id"

Disable thinking mode (Qwen3 / DeepSeek-R1 / …)

export TRANS_DISABLE_THINKING=true
export TRANS_REASONING_EFFORT=none

---

Upgrade & Uninstall

Tool	Upgrade	Uninstall
uv tool	uv tool install --reinstall .	uv tool uninstall localtrans
pipx	pipx reinstall localtrans --spec .	pipx uninstall localtrans
pip	python -m pip install --upgrade .	python -m pip uninstall localtrans