or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdexternal-apis.mdindex.mdpackage-management.mdtext-processing.mdtranslation.md
tile.json

configuration.mddocs/

Configuration

Comprehensive configuration management for argostranslate including data directories, cache settings, remote repository URLs, device selection, API keys, and experimental feature flags. All settings are automatically configured with sensible defaults and can be customized per environment.

Capabilities

Directory Configuration

File system paths for data storage, caching, and package management.

# Core directories
home_dir: Path          # User home directory
data_dir: Path          # Application data directory  
package_data_dir: Path  # Package installation directory
cache_dir: Path         # Translation cache directory
downloads_dir: Path     # Package download directory

# Package search paths
package_dirs: list[Path]        # List of directories to search for packages
local_package_index: Path      # Local package index file path

Remote Repository Configuration

Settings for package repository access and updates.

remote_repo: str              # Remote package repository URL
remote_package_index: str     # Remote package index URL

Feature Flags

Control flags for optional functionality and experimental features.

debug: bool                   # Enable debug logging output
dev_mode: bool               # Enable development mode features
experimental_enabled: bool    # Enable experimental functionality
stanza_available: bool       # Stanza NLP library availability flag

Device and Performance Configuration

Hardware and performance-related settings for optimal translation performance.

device: str                  # Computation device: "cpu" or "cuda"

API Authentication

Configuration for external translation service authentication.

libretranslate_api_key: str  # LibreTranslate API key
openai_api_key: str          # OpenAI API key

Model Provider Selection

Enumeration and configuration for translation backend selection.

class ModelProvider:
    """Enumeration of available translation model providers."""
    OPENNMT = 0          # Local OpenNMT neural models (default)
    LIBRETRANSLATE = 1   # LibreTranslate API service
    OPENAI = 2           # OpenAI language models

# Active model provider
model_provider: ModelProvider

Application Metadata

Information about the application and version details.

about_text: str             # Application description text

Utility Constants

Helper constants for configuration parsing and validation.

TRUE_VALUES: list[str]      # Values considered as "true" in configuration
                           # Typically: ["true", "1", "yes", "on"]

Network Utilities

Network-related configuration and utilities for package downloads and API access.

# From argostranslate.networking module
USER_AGENT: str                 # HTTP user agent string for requests
supported_protocols: set[str]   # Set of supported URL protocols ("http", "https")

def get_protocol(url: str) -> str | None:
    """
    Extract protocol from URL.
    
    Args:
        url (str): URL to analyze
        
    Returns:
        str | None: Protocol string or None if not found
    """

def get(url: str, retry_count: int = 3) -> bytes | None:
    """
    Download data from URL with retry logic.
    
    Args:
        url (str): URL to download from
        retry_count (int): Number of retry attempts
        
    Returns:
        bytes | None: Downloaded data or None if failed
    """

def get_from(urls: list[str], retry_count: int = 3) -> bytes | None:
    """
    Download from first successful URL in list.
    
    Args:
        urls (list[str]): List of URLs to try
        retry_count (int): Retry attempts per URL
        
    Returns:
        bytes | None: Downloaded data or None if all failed
    """

Logging Utilities

Logging functions and logger access for debugging and monitoring.

# From argostranslate.utils module
logger: logging.Logger          # Package logger instance

def info(*argv):
    """
    Log information message.
    
    Args:
        *argv: Arguments to log
    """

def error(*argv):
    """
    Log error message.
    
    Args:
        *argv: Arguments to log
    """

Usage Examples

Basic Configuration Access

import argostranslate.settings as settings

# Check current configuration
print(f"Data directory: {settings.data_dir}")
print(f"Cache directory: {settings.cache_dir}")  
print(f"Debug mode: {settings.debug}")
print(f"Device: {settings.device}")

# Check API key availability
if settings.libretranslate_api_key:
    print("LibreTranslate API key is configured")
if settings.openai_api_key:
    print("OpenAI API key is configured")

Model Provider Configuration

import argostranslate.settings as settings
from argostranslate.settings import ModelProvider

# Check current provider
print(f"Current provider: {settings.model_provider}")

# Switch to LibreTranslate API
settings.model_provider = ModelProvider.LIBRETRANSLATE

# Switch to OpenAI
settings.model_provider = ModelProvider.OPENAI

# Switch back to local models (default)
settings.model_provider = ModelProvider.OPENNMT

Device Configuration

import argostranslate.settings as settings

# Check current device
print(f"Current device: {settings.device}")

# Configure for CPU usage
settings.device = "cpu"

# Configure for GPU usage (if CUDA available)
settings.device = "cuda"

Directory Customization

import argostranslate.settings as settings
from pathlib import Path

# Check default directories
print(f"Package directory: {settings.package_data_dir}")
print(f"Cache directory: {settings.cache_dir}")

# Add custom package directory
custom_package_dir = Path("/custom/packages")
if custom_package_dir not in settings.package_dirs:
    settings.package_dirs.append(custom_package_dir)

print(f"Package search paths: {settings.package_dirs}")

Development and Debug Configuration

import argostranslate.settings as settings

# Enable debug mode for verbose logging
settings.debug = True

# Enable development mode
settings.dev_mode = True

# Enable experimental features
settings.experimental_enabled = True

# Check feature availability
if settings.stanza_available:
    print("Stanza NLP library is available")
else:
    print("Stanza NLP library not found")

API Configuration

import argostranslate.settings as settings

# Configure LibreTranslate API
settings.libretranslate_api_key = "your-libretranslate-api-key"

# Configure OpenAI API
settings.openai_api_key = "your-openai-api-key"

# Switch to API-based translation
from argostranslate.settings import ModelProvider
settings.model_provider = ModelProvider.LIBRETRANSLATE

Repository Configuration

import argostranslate.settings as settings

# Check current repository settings
print(f"Remote repo: {settings.remote_repo}")
print(f"Package index: {settings.remote_package_index}")

# Use custom repository (advanced usage)
settings.remote_repo = "https://my-custom-repo.example.com/"
settings.remote_package_index = "https://my-custom-repo.example.com/index.json"

Environment Variable Integration

Argostranslate automatically loads configuration from environment variables:

# API keys
export LIBRETRANSLATE_API_KEY="your-libretranslate-key"
export OPENAI_API_KEY="your-openai-key"

# Debug mode
export ARGOS_DEBUG="true"

# Device selection
export ARGOS_DEVICE="cuda"

# Custom data directory
export ARGOS_DATA_DIR="/custom/data/path"

Python code automatically uses environment variables:

import argostranslate.settings as settings

# These values are automatically loaded from environment
print(f"API key loaded: {bool(settings.libretranslate_api_key)}")
print(f"Debug mode: {settings.debug}")
print(f"Device: {settings.device}")

Configuration File Support

While argostranslate primarily uses environment variables and programmatic configuration, you can create configuration helpers:

import argostranslate.settings as settings
import json
from pathlib import Path

def load_config_from_file(config_path: Path):
    """Load configuration from JSON file."""
    if config_path.exists():
        with open(config_path, 'r') as f:
            config = json.load(f)
        
        # Apply configuration
        if 'debug' in config:
            settings.debug = config['debug']
        if 'device' in config:
            settings.device = config['device']
        if 'libretranslate_api_key' in config:
            settings.libretranslate_api_key = config['libretranslate_api_key']
        if 'model_provider' in config:
            from argostranslate.settings import ModelProvider
            provider_map = {
                'opennmt': ModelProvider.OPENNMT,
                'libretranslate': ModelProvider.LIBRETRANSLATE,
                'openai': ModelProvider.OPENAI
            }
            settings.model_provider = provider_map.get(config['model_provider'], ModelProvider.OPENNMT)

# Example config.json
config_example = {
    "debug": True,
    "device": "cuda",
    "model_provider": "opennmt",
    "libretranslate_api_key": "your-api-key"
}

# Load configuration
config_file = Path("argos_config.json")
load_config_from_file(config_file)

Default Values

Argostranslate ships with sensible defaults for all configuration options:

# Default directory structure (relative to user home)
# ~/.local/share/argos-translate/  (data_dir)
# ~/.local/share/argos-translate/packages/  (package_data_dir)  
# ~/.cache/argos-translate/  (cache_dir)

# Default remote repository
# https://github.com/argosopentech/argos-translate-packages

# Default model provider
# ModelProvider.OPENNMT (local neural models)

# Default device
# "cpu" (automatically detects CUDA if available)

# Default feature flags
# debug: False
# dev_mode: False  
# experimental_enabled: False

Advanced Configuration

Custom Package Directories

import argostranslate.settings as settings
from pathlib import Path

# Add multiple custom package directories
custom_dirs = [
    Path("/opt/argos-packages"),
    Path("/usr/local/share/argos-packages"),
    Path("./local-packages")
]

for dir_path in custom_dirs:
    if dir_path.exists() and dir_path not in settings.package_dirs:
        settings.package_dirs.append(dir_path)

print(f"Searching packages in: {settings.package_dirs}")

Performance Optimization

import argostranslate.settings as settings

# Optimize for performance
settings.device = "cuda"  # Use GPU if available
settings.debug = False    # Disable debug logging
settings.experimental_enabled = True  # Enable performance features

# Configure cache directory on fast storage
from pathlib import Path
fast_cache = Path("/tmp/argos-cache")
fast_cache.mkdir(exist_ok=True)
settings.cache_dir = fast_cache

Multi-Environment Configuration

import argostranslate.settings as settings
import os

def configure_for_environment():
    """Configure argostranslate based on deployment environment."""
    
    env = os.getenv("DEPLOYMENT_ENV", "development")
    
    if env == "production":
        settings.debug = False
        settings.dev_mode = False
        settings.experimental_enabled = False
        settings.device = "cuda"  # Use GPU in production
        
    elif env == "development":
        settings.debug = True
        settings.dev_mode = True
        settings.experimental_enabled = True
        settings.device = "cpu"  # CPU for development
        
    elif env == "testing":
        settings.debug = False
        settings.dev_mode = False
        settings.experimental_enabled = False
        settings.device = "cpu"  # Consistent testing environment

configure_for_environment()

Logging Configuration

Access to the logging system for debugging and monitoring:

from argostranslate.utils import logger, info, error

# Use built-in logging functions
info("Translation started")
error("Translation failed", extra_data)

# Access logger directly for custom configuration
import logging
logger.setLevel(logging.DEBUG)

# Create custom handler
handler = logging.FileHandler('argos-translate.log')
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)