translate-shell

Translate text by:

• online translators
  • google
  • bing
  • youdaozhiyun
  • haici
• offline dictionaries
  • stardict
• LLM
  • OpenAI
  • llama: use your local model

Supports:

• CLI
• GUI
  • GNU/Linux
  • Android
  • macOS
  • Windows
• REPL
• script:
  • python
  • shell
  • vim: DEPRECATION: vim port will be replaced by language server
• language server
• CI/CD
  • github action

Usage

UI

CLI

trans --translators=google,bing,haici,stardict crush

REPL

$ trans  # enter REPL
> en:ja  # change source language to english and target language to japanese
> :  # swap source and target languages
> =stardict  # use stardict to translate text
> !cat example/test.txt  # execute a shell command
ハッカー
> <example/test.txt   # translate a file
hacker
> 画家  # translate text
painter; artist
> !  # enter shell
$ echo $SHELL  # execute a shell command
/usr/bin/zsh
$ exit  # exit shell
>

TUI

Vim

Translate --translators=google,bing Free as in Freedom

GUI

GNU/Linux

Android

Script

Python

>>> from translate_shell.translate import translate
>>> translate("The Mythical Man-Month", "zh_TW")
... Translations(
...     status=1,
...     results=[
...         Translation(
...             translator="google",
...             sl="auto",
...             tl="zh_TW",
...             text="The Mythical Man-Month",
...             phonetic="",
...             paraphrase="神話般的人月",
...             explains={},
...             details={},
...             alternatives=["神話般的月"]
...         )
...     ],
...     text="The Mythical Man-Month",
...     to_lang="zh_TW",
...     from_lang="auto",
... )

Shell Script

$ xsel -o | trans --format json | jq -r '"《\(.results[].paraphrase)》的英文是 \(.text)."'
《大教堂和集市》的英文是 the cathedral and the bazaar.

Vim Script

:let g:text = 'Just for Fun'
:let g:translation = json_decode(translate_shell#call('--format=json', g:text))
:echo g:text 'is' g:translation.results[0].paraphrase 'in Chinese.'
Just for Fun is 纯娱乐 in Chinese.

Language server

• document hover: display translated results
• completions: complete translated words

CI/CD

Github Action

This repo provides an action to translate *.po of a repository. See inputs. For example, you have a repository which contains translations of another project's documents (upstream), you can write a github workflow to detect if upstream has update. If a new version exist, update the version and generate new .pos, then translate the changed .pos and git commit.

Examples:

• tmux-zh

on:
  schedule:
    # Run this CI/CD at 0:00 on Friday
    - cron: 0 0 * * 5
  workflow_dispatch:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate new .po
        id: version
        run: |
          # update version
          # then use perl / sed / ... to replace the version string of your file
          # then generate new .po
          echo VERSION=XXX > $GITHUB_OUTPUT
      - name: Translate your *.po
        uses: Freed-Wu/translate-shell@main
      - name: Git commit
        run: |
          git add **.po
          git config --global user.name 'Github Actions'
          git config --global user.email '41898282+github-actions[bot]@users.noreply.github.com'
          git commit -m ":bookmark: Dump version to $VERSION"
          git tag "$VERSION"
          git remote set-url origin "https://x-access-token:$GH_TOKEN@github.com/$GITHUB_REPOSITORY"
          git push
          git push --tags
        env:
          VERSION: ${{steps.version.outputs.VERSION}}
          GH_TOKEN: ${{secrets.GH_TOKEN}}

You can use the following commands to get the new version:

# get a github repo's version:
curl https://api.github.com/repos/user/repo/releases/latest | jq -r .tag_name
# get a gitlab repo's version
curl 'https://gitlab.com/api/v4/projects/41218592/repository/tags?per_page=1' |
jq -r '.[].name'

You can use the following tools to generate the new .pos:

• sphinx-intl: Generate .po for any project using sphinx to generate document.
• po4a: Generate .po for any project which use markdown, LaTeX, man, ... to write document.

Similar Projects

See comparison.

Features

• Translate with different translators at same time, like translator
• Translate clipboard contents automatically, like ydcv
• Speak the pronunciation of words
• Support online translate engines
• Support offline dictionaries
• Many methods to use, from shell, python and vim
• Magic text, like en: to change source language, :zh_CN to change target language, <file to translate file, etc.
• Allow customization by config.py
• Good shell completions, especially for zsh, complete options and translation history
• Manpage: man trans
• Beautiful UI
• Cross platforms
• Rich API, can be easily called from shell and python
• Good document
• Unit test, keep code quality
• CI/CD
• clean code
• Respect PEP484
• Respect PEP621
• Respect XDG

The last but not least: it is a libre software.

See document to know more.

PS: PR is welcome! Please make code clean and keep test pass!