Try Live
Add Docs
Rankings
Pricing
Enterprise
Docs
Install
Install
Docs
Pricing
Enterprise
More...
More...
Try Live
Rankings
Add Docs
Argos Translate
https://github.com/argosopentech/argos-translate
Admin
Argos Translate is an open-source offline translation library written in Python, supporting
...
Tokens:
8,436
Snippets:
113
Trust Score:
9.1
Update:
1 month ago
Context
Skills
Chat
Benchmark
96.8
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# Argos Translate Argos Translate is an open-source offline translation library written in Python that uses OpenNMT for neural machine translation. It supports installing language model packages (.argosmodel files) containing translation data, enabling offline translation between over 30 languages including Arabic, Chinese, English, French, German, Spanish, and many more. The library can be used as a Python library, command-line tool, or integrated with GUI applications. A key feature of Argos Translate is automatic pivot translation, which chains translations through intermediate languages when a direct translation isn't available. For example, with Spanish→English and English→French packages installed, you can translate Spanish→French automatically. The library also powers LibreTranslate, a self-hosted API and web application for translation services. ## Core Translation API The `translate` module provides the main translation functionality. The simplest way to translate text is using the `translate()` function, which takes source text and language codes. ```python import argostranslate.package import argostranslate.translate # First, install a language package from_code = "en" to_code = "es" # Update package index and install the required 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 text translated_text = argostranslate.translate.translate("Hello World", from_code, to_code) print(translated_text) # Output: ¡Hola Mundo! ``` ## Package Management API The `package` module handles downloading, installing, and managing translation packages. Packages are zip archives with `.argosmodel` extension containing OpenNMT models and metadata. ```python import argostranslate.package # Update the remote package index argostranslate.package.update_package_index() # Get list of available packages for download available_packages = argostranslate.package.get_available_packages() for pkg in available_packages: print(f"{pkg.from_name} → {pkg.to_name} (v{pkg.package_version})") # Find and install a specific language pair en_to_de = next( filter( lambda x: x.from_code == "en" and x.to_code == "de", available_packages ), None ) if en_to_de: download_path = en_to_de.download() argostranslate.package.install_from_path(download_path) print(f"Installed: {en_to_de}") # List installed packages installed_packages = argostranslate.package.get_installed_packages() for pkg in installed_packages: print(f"Installed: {pkg.from_name} → {pkg.to_name}") # Uninstall a package if installed_packages: argostranslate.package.uninstall(installed_packages[0]) ``` ## Install Package from Local File You can install translation packages directly from a local `.argosmodel` file path. ```python import pathlib import argostranslate.package # Install from a local .argosmodel file package_path = pathlib.Path("/path/to/translate-en_it-2_0.argosmodel") argostranslate.package.install_from_path(package_path) # Verify installation installed = argostranslate.package.get_installed_packages() for pkg in installed: print(f"Installed: {pkg}") ``` ## Language and Translation Objects API For more control over translations, use the `Language` and `ITranslation` objects. This allows access to translation hypotheses with confidence scores. ```python import argostranslate.translate # Get all installed languages installed_languages = argostranslate.translate.get_installed_languages() for lang in installed_languages: print(f"{lang.name} ({lang.code})") # Get a specific language by code english = argostranslate.translate.get_language_from_code("en") spanish = argostranslate.translate.get_language_from_code("es") if english and spanish: # Get translation object between languages translation = english.get_translation(spanish) if translation: # Simple translation result = translation.translate("Good morning!") print(f"Translation: {result}") # Get multiple translation hypotheses with scores hypotheses = translation.hypotheses("Good morning!", num_hypotheses=4) for i, hyp in enumerate(hypotheses): print(f"Hypothesis {i+1}: {hyp.value} (score: {hyp.score})") # Alternative: get translation directly from codes translation = argostranslate.translate.get_translation_from_codes("en", "es") if translation: print(translation.translate("How are you?")) ``` ## LibreTranslate API Client Connect to a LibreTranslate server for remote translation, language detection, and listing available languages. ```python from argostranslate.apis import LibreTranslateAPI # Connect to a LibreTranslate server lt = LibreTranslateAPI("https://translate.argosopentech.com/") # Or with API key for authenticated endpoints # lt = LibreTranslateAPI("https://your-server.com/", api_key="your-api-key") # Translate text translated = lt.translate("Hello, how are you?", source="en", target="es") print(f"Translation: {translated}") # Output: Translation: Hola, ¿cómo estás? # Detect language detected = lt.detect("Bonjour le monde") print(f"Detected: {detected}") # Output: [{"confidence": 0.9, "language": "fr"}] # Get available languages languages = lt.languages() for lang in languages: print(f"{lang['name']} ({lang['code']})") ``` ## Command Line Interface - argos-translate The `argos-translate` command provides translation from the terminal. It supports both direct arguments and piped input. ```bash # Basic translation with language codes argos-translate --from-lang en --to-lang es "Hello World" # Output: Hola Mundo # Short flag syntax argos-translate -f en -t es "Good morning!" # Output: ¡Buenos días! # Translate piped input echo "This is a test sentence." | argos-translate --from-lang en --to-lang de # Output: Dies ist ein Testsatz. # Translate file contents cat document.txt | argos-translate -f en -t fr # GPU acceleration (requires CUDA) ARGOS_DEVICE_TYPE=cuda argos-translate -f en -t es "Hello World" # Output: Hola Mundo ``` ## Command Line Interface - argospm Package Manager The `argospm` command manages translation packages from the terminal. ```bash # Update the package index from remote repository argospm update # Search for available packages argospm search # Output: translate-en_es: en -> es # translate-es_en: es -> en # ... # Search with filters argospm search --from-lang en argospm search --from-lang en --to-lang de # Install a specific language pair argospm install translate-en_es # Output: Downloaded package /home/user/.local/cache/argos-translate/downloads/translate-en_es.argosmodel # Installed package to /home/user/.local/share/argos-translate/packages # Install all available packages argospm install translate # List installed packages argospm list # Output: translate-en_es # translate-es_en # Remove a package argospm remove translate-en_es # Output: Removed package translate-en_es # Install all packages via bash loop for i in $(argospm search | sed 's/:.*$//g'); do argospm install $i; done # Remove all packages for i in $(argospm list); do argospm remove $i; done ``` ## Configuration via Environment Variables Argos Translate can be configured via environment variables or a JSON settings file. Environment variables take precedence. ```bash # Enable debug mode export ARGOS_DEBUG="1" # Set custom package directory export ARGOS_PACKAGES_DIR="/custom/path/to/packages/" # GPU acceleration (options: "cpu", "cuda", "auto") export ARGOS_DEVICE_TYPE="cuda" # Custom package index URL export ARGOS_PACKAGE_INDEX="https://your-custom-index.com/" # CTranslate2 performance tuning export ARGOS_INTER_THREADS="2" export ARGOS_INTRA_THREADS="4" export ARGOS_BATCH_SIZE="64" export ARGOS_BEAM_SIZE="4" export ARGOS_COMPUTE_TYPE="auto" # Options: auto, int8, int16, float16, float32 # Alternative model providers export ARGOS_MODEL_PROVIDER="OPENNMT" # Options: OPENNMT, LIBRETRANSLATE, OPENAI # Sentence boundary detection method export ARGOS_CHUNK_TYPE="DEFAULT" # Options: DEFAULT, STANZA, SPACY, MINISBD, NONE # API keys for remote providers export LIBRETRANSLATE_API_KEY="your-libretranslate-key" export OPENAI_API_KEY="your-openai-key" ``` ## Configuration via JSON File Settings can also be stored in `~/.config/argos-translate/settings.json`. ```json { "ARGOS_DEBUG": "0", "ARGOS_PACKAGES_DIR": "/home/user/.local/share/argos-translate/packages/", "ARGOS_DEVICE_TYPE": "cpu", "ARGOS_INTER_THREADS": "1", "ARGOS_INTRA_THREADS": "0", "ARGOS_BATCH_SIZE": "32", "ARGOS_BEAM_SIZE": "4", "ARGOS_COMPUTE_TYPE": "auto", "ARGOS_MODEL_PROVIDER": "OPENNMT", "ARGOS_CHUNK_TYPE": "DEFAULT" } ``` ## Programmatic Settings Access Access and modify settings programmatically at runtime. ```python from argostranslate import settings # Access current settings print(f"Device: {settings.device}") print(f"Package directory: {settings.package_data_dir}") print(f"Debug mode: {settings.debug}") print(f"Batch size: {settings.batch_size}") print(f"Beam size: {settings.beam_size}") # Get a custom setting with default custom_value = settings.get_setting("CUSTOM_KEY", default="default_value") # Set a setting (writes to settings.json) settings.set_setting("ARGOS_BATCH_SIZE", "64") # Package directories searched for installed packages for pkg_dir in settings.package_dirs: print(f"Package dir: {pkg_dir}") ``` ## Install Package for Language Pair Utility A convenience function to install the necessary package for a specific language pair. ```python from argostranslate.package import install_package_for_language_pair # Automatically find and install package for language pair success = install_package_for_language_pair("en", "fr") if success: print("English to French package installed successfully") else: print("Package not found or installation failed") # Now translate import argostranslate.translate result = argostranslate.translate.translate("Hello", "en", "fr") print(result) # Bonjour ``` Argos Translate is ideal for applications requiring offline translation capabilities, such as desktop applications, privacy-focused tools, or systems without reliable internet access. It integrates well with web services through LibreTranslate, enabling self-hosted translation APIs. The package system allows flexible deployment with only required language pairs installed. For developers building on Argos Translate, the library provides multiple abstraction levels: simple `translate()` function calls for basic use cases, `Language` and `Translation` objects for more control, and direct access to CTranslate2 parameters for performance tuning. The pivot translation feature automatically enables translation between any installed language pairs, making it practical to support many language combinations with fewer model packages.