Argos Translate

Common errors

• Package not found for translating from 'en' to 'es'.

  cause The core `argostranslate` library is installed, but the specific language model package (e.g., English to Spanish) has not been downloaded and installed.
  fix You must explicitly download and install language models. Use `argostranslate.package.update_package_index()` to get available packages, then filter and install the desired one using `argostranslate.package.install_from_path(package_to_install.download())`. Alternatively, use the `argospm` command-line tool: `argospm install translate-en_es`.

• 'argos-translate' is not recognized as an internal or external command, operable program or batch file.

  cause The `argos-translate` or `argos-translate-gui` executables are not in your system's PATH, or they are not correctly linked/aliased after installation.
  fix Ensure that the directory where `pip` installs executables (often `~/.local/bin` on Linux/macOS, or `Scripts` subdirectory in your Python installation on Windows) is included in your system's PATH environment variable. Using a Python virtual environment and activating it can help manage this. On Windows, you might need to invoke it via `python -m argostranslate.cli` or specify the full path to the script.

• FileNotFoundError: [WinError 2] The system cannot find the file specified

  cause This error can occur during installation or execution, often related to underlying C++ dependencies (like `ctranslate2` needing a specific compiler or runtime, or `sentencepiece` build issues) or missing system-level tools.
  fix Ensure you have the necessary build tools for Python packages (e.g., Microsoft C++ Build Tools on Windows). If using a specific Python version (like 3.12), verify compatibility for `ctranslate2` and `sentencepiece`. A clean virtual environment can sometimes resolve conflicts.

Warnings

• breaking Major breaking changes occurred around versions 1.2 and 1.4, specifically deprecating `load_available_packages` for `get_available_packages` and `load_installed_languages` for `get_installed_languages`. Other changes affected `translate.apply_packaged_translation`, `ITranslate.split_into_paragraphs`, and `package.Package.remove`.
  Fix: Refer to the official documentation or GitHub release notes for specific API changes. Update deprecated function calls to their newer equivalents (e.g., `get_available_packages()` instead of `load_available_packages()`).
• gotcha Repeated calls to `argostranslate.translate.translate()` within a loop can be inefficient due to models potentially being reloaded. It's more performant to load the translation object once and reuse it.
  Fix: Instead of `argostranslate.translate.translate(text, from_code, to_code)` in a loop, load the `ITranslation` object once: `installed_languages = argostranslate.translate.get_installed_languages(); from_lang = ...; to_lang = ...; translation_obj = from_lang.get_translation(to_lang);` Then, call `translated_text = translation_obj.translate(text)` repeatedly.
• gotcha Installation issues on Python 3.12 have been reported, primarily due to underlying dependencies like `ctranslate2` or `sentencepiece` not having readily available wheels or requiring specific build environments for Python 3.12 at the time of the issue.
  Fix: Ensure you are using the latest `argostranslate` version and `pip`. If issues persist, consider using a slightly older Python version (e.g., 3.11) or checking the `ctranslate2` and `sentencepiece` project pages for Python 3.12 compatibility updates.

Install

• pip install argostranslate Install core library

Imports

• package
  wrong:

  from argostranslate import package

  correct:

  import argostranslate.package

  While 'from argostranslate import package' might work, the documentation and examples consistently use the fully qualified 'import argostranslate.package' and 'import argostranslate.translate' to avoid name collisions and for clarity.
• translate
  wrong:

  from argostranslate import translate

  correct:

  import argostranslate.translate

  See note for 'package' import.

Quickstart

This quickstart demonstrates how to programmatically download and install a language model, then use it to translate text. The library requires explicit installation of language models (e.g., 'en' to 'es') after the main library itself is installed.

import argostranslate.package
import argostranslate.translate

# Define source and target languages using ISO 639-1 codes
from_code = "en"
to_code = "es"

# Update package index and download/install the desired language model
print("Updating package index...")
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
    ),
    None
)

if package_to_install:
    print(f"Downloading and installing {from_code} -> {to_code} package...")
    download_path = package_to_install.download()
    argostranslate.package.install_from_path(download_path)
    print("Package installed.")
else:
    print(f"No package found for {from_code} -> {to_code}. Please check available packages or codes.")

# Perform translation
installed_languages = argostranslate.translate.get_installed_languages()
from_lang = next(filter(lambda x: x.code == from_code, installed_languages), None)
to_lang = next(filter(lambda x: x.code == to_code, installed_languages), None)

if from_lang and to_lang:
    print(f"Translating 'Hello World' from {from_code} to {to_code}...")
    translatedText = from_lang.get_translation(to_lang).translate("Hello World")
    print(f"Translated text: {translatedText}")
else:
    print("Source or target language not found among installed languages.")