mod_translate_argos

Provides automatic translation using a local Argos Translate Python worker as a translation service for Zotonic's mod_translation module.

Setup and configuration

Enable mod_translate_argos. Installation creates a shared Python virtual environment under apps/zotonic_mod_translate_argos/venv in the Zotonic data directory and installs priv/python/requirements.txt. Open System → Argos Translate in the admin to refresh the package index and install the language packages needed for translation. Package administration requires use.mod_admin_config permission.

Grant use.mod_translate_argos to user groups allowed to request translations. The integration handles the translate notification used by the admin's add-language dialog. Plain text and HTML requests are routed to their matching model functions. The observer returns {ok, TranslatedTexts} on success and undefined on denied access or translation errors, allowing other providers to handle the notification.

Both source and target languages are required. Language variants are normalized to their primary language code. Translation runs locally; package installation and index updates may need network access.

mod_translate_argos.timeout sets the worker request timeout in milliseconds; the default is 120000. The following are Zotonic system configuration keys:

• translate_argos_python_command: override the Python executable used to create the virtual environment. Otherwise Zotonic's python_command system setting is used, falling back to python3. Bare command names are resolved with os:find_executable/1.
• translate_argos_max_queue: maximum queued requests across all sites, default 100. Zero disables waiting behind an active request.

Set system configuration in zotonic.config, for example:

{translate_argos_max_queue, 100}

Language packages

Argos needs installed translation packages for the requested language pair. Packages can be managed in the admin or with argospm from the module's virtual environment. For example, install an English-to-Dutch package with:

<zotonic-data-dir>/apps/zotonic_mod_translate_argos/venv/bin/argospm update
<zotonic-data-dir>/apps/zotonic_mod_translate_argos/venv/bin/argospm install translate-en_nl

Replace <zotonic-data-dir> with the actual Zotonic data directory. Argos can also translate through intermediate languages when the required packages are installed. The virtual environment, worker, and language packages are shared between sites.

Shared worker

The model starts the worker on demand under z_system_process. One persistent Python process serves all sites and serializes requests. Package administration has priority over queued translations. Plain and tagged text are sent in batches of at most 16 strings, retaining the input order.

The worker is started lazily on the first translation or package request, not at Zotonic startup. The global supervisor keeps it running independently of individual sites. It launches Python using erlexec and exchanges newline-delimited JSON over stdin/stdout; no separate HTTP service is needed.

Package commands (packages, install_package, and update_packages) use a priority queue. Translations use a normal FIFO queue. Queued requests are removed when their caller exits and skipped when their caller's gen_server:call timeout window has already elapsed.

GPU and Apple Accelerate support

Argos uses CTranslate2 for model inference. The module passes auto as the worker's device setting; the Python script uses it for ARGOS_DEVICE_TYPE unless that environment variable is already set. Acceleration depends on the installed CTranslate2 build and the available hardware and runtime libraries. With automatic device selection, CPU is the fallback when a supported GPU backend is unavailable.

NVIDIA CUDA

CUDA acceleration requires a supported NVIDIA GPU, NVIDIA driver, CUDA runtime, and a CTranslate2 build with CUDA support. For a custom source build, the README uses these CMake options from the CTranslate2 build directory:

cmake .. -DWITH_CUDA=ON -DWITH_CUDNN=ON
make -j
make install

Build the matching CTranslate2 Python wheel and install it into the Argos virtual environment. When using a custom installation prefix, ensure that the Python build and runtime can find the CTranslate2 headers and shared libraries.

macOS and Apple Accelerate

Modern Apple hardware does not provide the NVIDIA CUDA path. CTranslate2 can use Apple Accelerate for CPU math and linear algebra when its installed wheel or source build enables that backend. This is CPU acceleration, not Apple GPU, Metal, or MPS execution.

For a custom source build, the README uses:

cmake .. -DWITH_ACCELERATE=ON
make -j
make install

Build and install the matching Python wheel into the module virtual environment.

Installing a custom inference build

The module's Python requirements normally determine which CTranslate2 build is installed. After the virtual environment exists, install a custom wheel with:

<zotonic-data-dir>/apps/zotonic_mod_translate_argos/venv/bin/pip install /path/to/ctranslate2-*.whl

Restart Zotonic, or stop the shared Argos worker so it restarts with the new Python package. Because the worker is shared, this affects every site using it.