# mod\_translate\_argos

Source: https://zotonic.com/docs/2763/mod_translate_argos

URI: https://zotonic.com/id/2763

Language: en



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:

```erlang
{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:

```sh
<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:

```sh
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:

```sh
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:

```sh
<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.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/2763?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/2763?language=en>)
