Argos Translate (argosopentech/argos-translate)

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
Show doc for...
Context Summary (auto-generated)
Raw
# 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.