## File: README.md # Argos Translate [Demo](https://libretranslate.com) | [Website](https://www.argosopentech.com) | [Docs](https://argos-translate.readthedocs.io) | [Forum](https://community.libretranslate.com/c/argos-translate/5) | [GitHub](https://github.com/argosopentech/argos-translate) | [PyPI](https://pypi.org/project/argostranslate/) **Open-source offline translation library written in Python** Argos Translate uses [OpenNMT](https://opennmt.net/) for translations and can be used as either a Python library, command-line, or GUI application. Argos Translate supports installing language model packages which are zip archives with a ".argosmodel" extension containing the data needed for translation. [LibreTranslate](https://libretranslate.com) is an API and web-app built on top of Argos Translate. Argos Translate also manages automatically pivoting through intermediate languages to translate between languages that don't have a direct translation between them installed. For example, if you have a es → en and en → fr translation installed you are able to translate from es → fr as if you had that translation installed. This allows for translating between a wide variety of languages at the cost of some loss of translation quality. The [argospm-index](https://github.com/argosopentech/argospm-index) repo contains metadata and download links to access pre-trained Argos Translate models. ### Supported languages ##### [Browse Package Index](https://www.argosopentech.com/argospm/index/) Arabic, Azerbaijani, Basque, Catalan, Chinese, Czech, Danish, Dutch, English, Esperanto, Finnish, French, Galician, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Irish, Italian, Japanese, Kyrgyz, Korean, Malay, Persian, Polish, Portuguese, Portuguese (Brazil), Russian, Slovak, Spanish, Swahili, Swedish, Turkish, Ukrainian, Urdu, and more [Request a language](https://github.com/argosopentech/argos-translate/discussions/91) ## Installation ### Install with Python Argos Translate is available from [PyPI](https://pypi.org/project/argostranslate/) and can be easily installed with [pip](https://pip.pypa.io/en/stable/installation/). ``` pip install argostranslate ``` Install [GUI](https://github.com/argosopentech/argos-translate-gui): ``` pip install argostranslategui ``` ### Python source installation into virtualenv Download a copy of this repo and install with pip. ``` git clone https://github.com/argosopentech/argos-translate.git cd argos-translate virtualenv env source env/bin/activate pip install -e . ``` ## Examples ### [Python](https://argos-translate.readthedocs.io/en/latest/py-modindex.html) ```python import argostranslate.package import argostranslate.translate from_code = "en" to_code = "es" # Download and install Argos Translate package argostranslate.package.update_package_index() available_packages = argostranslate.package.get_available_packages() package_to_install = next( filter( lambda x: x.from_code == from_code and x.to_code == to_code, available_packages ) ) argostranslate.package.install_from_path(package_to_install.download()) # Translate translatedText = argostranslate.translate.translate("Hello World", from_code, to_code) print(translatedText) # '¡Hola Mundo!' ``` ### Command Line Interface ``` argospm update argospm install translate-en_de argos-translate --from en --to de "Hello World!" # Hallo Welt! ``` Install all translation packages: ``` argospm install translate ``` ### [LibreTranslate](https://github.com/LibreTranslate/LibreTranslate) Web App ([Demo](https://libretranslate.com/)) ### [LibreTranslate](https://github.com/uav4geo/LibreTranslate) API ```javascript const res = await fetch("https://translate.argosopentech.com/translate", { method: "POST", body: JSON.stringify({ q: "Hello!", source: "en", target: "es" }), headers: { "Content-Type": "application/json"} }); console.log(await res.json()); { "translatedText": "¡Hola!" } ``` #### Graphical user interface The GUI code is in a [separate repository](https://github.com/argosopentech/argos-translate-gui). ## [Packages](https://www.argosopentech.com/argospm/index/) - [Browse](https://www.argosopentech.com/argospm/index/) - [P2P download with BitTorrent](/p2p/README.md) - [Training scripts](https://github.com/argosopentech/argos-train) - [Google Drive download](https://drive.google.com/drive/folders/11wxM3Ze7NCgOk_tdtRjwet10DmtvFu3i) ### GPU Acceleration To enable GPU support, you need to set the `ARGOS_DEVICE_TYPE` env variable to `cuda` or `auto`. ``` $ ARGOS_DEVICE_TYPE=cuda argos-translate --from-lang en --to-lang es "Hello World" Hola Mundo ``` The above env variable passes the device type to [CTranslate2](https://github.com/OpenNMT/CTranslate2). ### HTML Translation The [translate-html](https://github.com/argosopentech/translate-html) library is built on top of Argos Translate and [Beautiful Soup](https://beautiful-soup-4.readthedocs.io/en/latest/) and parses and translates HTML. The LibreTranslate API also has support for translating HTML. ### Files Translation The [argos-translate-files](https://github.com/LibreTranslate/argos-translate-files) library is built on top of Argos Translate and parses and translates files. The LibreTranslate API also has support for translating files. ## Uninstall ``` shell pip uninstall argostranslate ``` You may choose to also delete temporary and cached files: ``` shell rm -r ~/.local/cache/argos-translate rm -r ~/.local/share/argos-translate ``` ## Related Projects - [LibreTranslate-py](https://github.com/argosopentech/LibreTranslate-py) - Python bindings for LibreTranslate - [MetalTranslate](https://github.com/argosopentech/MetalTranslate) - Customizable translation in C++ - [LibreTranslate/Locomotive](https://github.com/LibreTranslate/Locomotive) - Toolkit for training/converting LibreTranslate compatible language models 🚂 - [DesktopTranslator](https://github.com/ymoslem/DesktopTranslator) - [OpenNMT](https://opennmt.net/) based translation application - [LibreTranslate-rs](https://github.com/grantshandy/libretranslate-rs) - LibreTranslate Rust bindings - [LibreTranslate Go](https://github.com/SnakeSel/libretranslate) - LibreTranslate Golang bindings - [LibreTranslate Java](https://github.com/dynomake/libretranslate-java) - LibreTranslate Java bindings - [LibreTranslator](https://gitlab.com/BeowuIf/libretranslator) - LibreTranslate Android app ## Contributing Contributions are welcome! Available issues are on the [GitHub issues page](https://github.com/argosopentech/argos-translate/issues). Contributions of code, data, and pre-trained models can all be accepted. ## Support For support please use the [LibreTranslate Forum](https://community.libretranslate.com/c/argos-translate/5) or [GitHub Issues](https://github.com/argosopentech/argos-translate/issues). For questions about [CTranslate2](https://github.com/OpenNMT/CTranslate2) or general machine translation research the [OpenNMT Forum](https://forum.opennmt.net/) is a good resource. ## Services Custom models trained on your own data are available for $1000/language (negotiable). [I am also available for hire](https://www.argosopentech.com/about/) to do support, consulting, or custom software development. ## Financial Support #### Donate If you find this software useful donations are greatly appreciated and help to make this project sustainable. - [GitHub Sponsor](https://github.com/sponsors/argosopentech) - [PayPal](https://www.paypal.com/biz/fund?id=MCCFG437JP9PJ) - [Venmo @pjfinlay](https://venmo.com/u/pjfinlay) - Bitcoin: 16UJrmSEGojFPaqjTGpuSMNhNRSsnspFJT Paid supporters receive priority support. #### Sponsors Argos Translate is proudly sponsored by TestMu AI. [TestMu AI (formerly LambdaTest)](https://www.testmuai.com/) is the world's first full-stack agentic AI quality engineering platform. Autonomous AI agents plan, author, execute, analyze, and optimize tests with humans in the loop, across 3,000+ browser/OS combinations and 10,000+ real devices. Trusted by 18,000+ enterprises including Microsoft, OpenAI, NVIDIA, and Vimeo. [Explore the platform →](https://www.testmuai.com/) #### Hosting affiliate links You can help support Argos Translate financially by purchasing hosting through these referral links: - [Vast.ai](http://vast.ai/?ref=24817) - Cheap GPU rentals - [DigitalOcean](https://m.do.co/c/a1af57be6e3f) - Best all around hosting - [Sharktech](https://portal.sharktech.net/aff.php?aff=1181) - Cheap bandwith - [Time4VPS](https://www.time4vps.com/?affid=6929) - Cheap storage ## Contributing Contributions are welcome! Bug reports, pull requests, documentation writing, and feature ideas are all appreciated. ## License Argos Translate is dual licensed under either the [MIT License](https://github.com/argosopentech/argos-translate/blob/master/LICENSE) or [Creative Commons CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). --- ## File: data_snap/README.md This is the directory for building a data snap. Put **unzipped** files in the packages directory to be copied into a data snap. --- ## File: docs/source/argostranslate.rst argostranslate package ====================== Submodules ---------- argostranslate.apis module -------------------------- .. automodule:: argostranslate.apis :members: :undoc-members: :show-inheritance: argostranslate.argospm module ----------------------------- .. automodule:: argostranslate.argospm :members: :undoc-members: :show-inheritance: argostranslate.cli module ------------------------- .. automodule:: argostranslate.cli :members: :undoc-members: :show-inheritance: argostranslate.fewshot module ----------------------------- .. automodule:: argostranslate.cli :members: :undoc-members: :show-inheritance: argostranslate.gui module ------------------------- .. automodule:: argostranslate.gui :members: :undoc-members: :show-inheritance: argostranslate.models module ---------------------------- .. automodule:: argostranslate.models :members: :undoc-members: :show-inheritance: argostranslate.networking module ---------------------------- .. automodule:: argostranslate.networking :members: :undoc-members: :show-inheritance: argostranslate.package module ----------------------------- .. automodule:: argostranslate.package :members: :undoc-members: :show-inheritance: argostranslate.sbd module ------------------------- .. automodule:: argostranslate.sbd :members: :undoc-members: :show-inheritance: argostranslate.settings module ------------------------------ .. automodule:: argostranslate.settings :members: :undoc-members: :show-inheritance: argostranslate.tags module ------------------------- .. automodule:: argostranslate.tags :members: :undoc-members: :show-inheritance: argostranslate.translate module ------------------------------- .. automodule:: argostranslate.translate :members: :undoc-members: :show-inheritance: argostranslate.utils module --------------------------- .. automodule:: argostranslate.utils :members: :undoc-members: :show-inheritance: Module contents --------------- .. automodule:: argostranslate :members: :undoc-members: :show-inheritance: --- ## File: docs/source/cli.rst Command Line Interface ====================== .. code-block:: python argos-translate --from-lang en --to-lang es "Hello World" Hola Mundo echo "Text to translate" | argos-translate --from-lang en --to-lang es Texto para traducir argospm --help usage: argospm [-h] {update,search,install,list,remove} ... positional arguments: {update,search,install,list,remove} Available commands. update Downloads remote package index. search Search package from remote index. install Install package. list List installed packages. remove Remove installed package. optional arguments: -h, --help show this help message and exit Translate a string from English to Spanish. Note: If you do not have the language pair that you are calling installed, you will get a `Traceback` error.:: argos-translate --from-lang en --to-lang es "Hello World." Hola Mundo Translate with shorter flag namesj argos-translate -f en -t es "Hello World." Hola Mundo Translate longer text piped into `argos-translate`.:: echo "Text to translate" | argos-translate --from-lang en --to-lang es Texto para traducir Update ------ Downloads remote package index. .. code-block:: sh argospm update Search ------ Search package from remote index. .. code-block:: sh argospm search --from-lang en --to-lang es Install ------ Install package. .. code-block:: sh argospm install translate-en_es List ------ List installed packages. .. code-block:: sh argospm list Remove ------ Remove installed package. .. code-block:: sh argospm remove translate-en_es Enable tab completion for Bash ------------------------------ .. code-block:: bash curl -sSL https://raw.githubusercontent.com/argosopentech/argos-translate/master/scripts/completion.bash > /etc/bash_completion.d/argospm.bash Importing new pairs through the CLI ------ * Update list of available language pairs: `argospm update` * List all available language pairs: `argospm search` * Install new pair syntax: `argospm install *lang_pair_name*` For example, install Turkish to English pair: `argospm install translate-tr_en` Optionally, you could install all language pairs using BASH.:: for i in $(argospm search | sed 's/:.*$//g'); do argospm install $i ; done Removing a pair through the CLI ------ 1. Remove the Turkish to English pair: `argospm remove translate-tr_en` Optionally, you could remove all language pairs using BASH if you need to free space fast. for i in $(argospm list); do argospm remove $i ; done --- ## File: docs/source/examples.rst Examples =========================================== Basic Python example -------------- .. code-block:: python import argostranslate.package import argostranslate.translate from_code = "en" to_code = "es" # Download and install Argos Translate package argostranslate.package.update_package_index() available_packages = argostranslate.package.get_available_packages() package_to_install = next( filter( lambda x: x.from_code == from_code and x.to_code == to_code, available_packages ) ) argostranslate.package.install_from_path(package_to_install.download()) # Translate translatedText = argostranslate.translate.translate("Hello World", from_code, to_code) print(translatedText) # '¡Hola Mundo!' Install package from file path -------------- .. code-block:: python import pathlib import argostranslate.package package_path = pathlib.Path("/root/translate-en_it-2_0.argosmodel") argostranslate.package.install_from_path(package_path) --- ## File: docs/source/gui.rst Graphical User Interface ====================== Run the GUI version of Argos Translate. argos-translate-gui Installing a language ------ When installing with snap a .desktop file should also be installed which will make Argos Translate available from the desktop menu. Languages are chosen as drop down choices. More languages pairs can be installed. The left text box translates into the right box. Example workflow translating from Vietnamese into English: * Set the left drop down to `Vietnamese` and the right drop down to `English`. * Replace the default text `Text to translate from` in the left text box with some text in Vietnamese. A quick way to do this is to click in the left text box and press the keyboard shortcut `CTRL+a` to select all and then `CTRL+v` to paste. * Wait patiently. * When text appears in the right text box, read the translation! If the output looks similar to the input, try changing the origin language as some languages appear similar if you are unfamiliar with them. Adding language pair models from the graphical interface ------ Language pairs are on average 100MB each. Installing new pairs through the GUI ------ * Open Argos Translate: `argos-translate-gui` * Click on the `Manage Packages` menu item. * Click on the `Download packages` button. * Click on the down arrow beside a language pair that you want to add. * Wait for the hourglass icon to change into a check mark icon. * Repeat the last two steps until you have all of the language pairs that you want. * Click on the `X` in the top right to close the `Download packages` window. * Click on the `X` in the top right to close the `Manage Packages` window. Note: The `Download packages` screen does not seem to have a scroll bar so you will probably need to follow the next set of instructions to import new pairs through the GUI. Importing new pairs through the GUI ------ * Download or make new pairs. Model links can be downloaded from https://www.argosopentech.com/argospm/index/ or https://raw.githubusercontent.com/argosopentech/argospm-index/main/index.json * Open Argos Translate: `argos-translate-gui` * Click on the `Manage Packages` menu item. * Click on the `Install package file` button. * Navigate to where you downloaded the new language pairs, click on the `.argosmodel` file, and click on the `Open` button. * Repeat the last two steps until you have all of the language pairs that you want. * Click on the `X` in the top right to close the `Manage Packages` window. Removing a pair through the GUI ------ * Open Argos Translate: `argos-translate-gui` * Click on the `Manage Packages` menu item. * Click on the trash can icon besides the pair you want to remove. * Click on the `X` in the top right to close the `Manage Packages` window. --- ## File: docs/source/settings.rst Settings ====================== Argos Translate can be configured either by setting environment variables or editing the config file. ~/.config/argos-translate/settings.json .. code-block:: json { "ARGOS_DEBUG": "1", "ARGOS_PACKAGE_INDEX": "https://raw.githubusercontent.com/argosopentech/argospm-index/main/" } .. code-block:: sh export ARGOS_DEBUG=1 export ARGOS_PACKAGE_INDEX="https://raw.githubusercontent.com/argosopentech/argospm-index/main" Set package index ----------------- Reads package index at https://raw.githubusercontent.com/argosopentech/argospm-index/main/index.json .. code-block:: sh export ARGOS_PACKAGE_INDEX="https://raw.githubusercontent.com/argosopentech/argospm-index/main" View debugging information -------------------------- Argos Translate prints more verbose logging .. code-block:: sh export ARGOS_DEBUG=1 Chunk Type -------------------------- Configure Sentence Boundary Detection (SBD) model The seq2seq neural networks that Argos Translate uses for translation can only handle ~150 tokens of input at at time. Argos Translate uses a separate SBD model to split text into sentences before translation. By default Argos Translate uses `MiniSBD `_, however, Stanza and Spacy are also supported. .. code-block:: sh pip install "argostranslate[stanza]" # Stanza/PyTorch is an optional dependency export ARGOS_CHUNK_TYPE="STANZA" .. code-block:: sh export ARGOS_CHUNK_TYPE="SPACY" .. code-block:: sh export ARGOS_CHUNK_TYPE="NONE" .. code-block:: sh export ARGOS_CHUNK_TYPE="DEFAULT" Set packages dir ---------------- This is the directory that Argos Translate saves installed packages to. .. code-block:: sh export ARGOS_PACKAGES_DIR="/home/user/.local/share/argos-translate/packages/" Set device ---------- .. code-block:: sh export ARGOS_DEVICE_TYPE="cpu" export ARGOS_DEVICE_TYPE="cuda" --- ## File: docs/index.rst Argos Translate Documentation =========================================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` Open-source offline translation library written in Python Argos Translate uses OpenNMT for translations, SentencePiece for tokenization, Stanza for sentence boundary detection, and PyQt for GUI. Argos Translate can be used as either a Python library, command-line, or GUI application. LibreTranslate is an API and web-app built on top of Argos Translate. Argos Translate supports installing language model packages which are zip archives with a ".argosmodel" extension with the data needed for translation. Argos Translate also manages automatically pivoting through intermediate languages to translate between languages that don't have a direct translation between them installed. For example, if you have a es ➔ en and en ➔ fr translation installed you are able to translate from es ➔ fr as if you had that translation installed. This allows for translating between a wide variety of languages at the cost of some loss of translation quality. Python Example -------------- .. code-block:: python import argostranslate.package import argostranslate.translate from_code = "en" to_code = "es" # Download and install Argos Translate package argostranslate.package.update_package_index() available_packages = argostranslate.package.get_available_packages() available_package = list( filter( lambda x: x.from_code == from_code and x.to_code == to_code, available_packages ) )[0] download_path = available_package.download() argostranslate.package.install_from_path(download_path) # Translate installed_languages = argostranslate.translate.get_installed_languages() from_lang = list(filter( lambda x: x.code == from_code, installed_languages))[0] to_lang = list(filter( lambda x: x.code == to_code, installed_languages))[0] translation = from_lang.get_translation(to_lang) translatedText = translation.translate("Hello World!") print(translatedText) # '¡Hola Mundo!' Command Line Interface Example -------------- .. code-block:: bash argospm update argospm install translate-en_de argos-translate --from en --to de "Hello World!" # Hallo Welt! .. toctree:: :maxdepth: 2 :caption: Contents: :ref:`genindex` source/settings source/cli source/gui source/examples