Skip to main content

Apertium Web Service

Project description

Apertium APy

Build Status Coverage Status PyPI PyPI - Python Version

Apertium APy, Apertium API in Python, is a web server exposing Apertium functions including text, document, and webpage translation, as well as morphological analysis and generation. More information is available on the Apertium Wiki.


  • Python 3.6+
  • Tornado 4.5.3 - 6.0.4 (python3-tornado on Debian/Ubuntu)

Additional functionality is provided by installation of the following packages:

  • apertium-streamparser enables spell checking
  • requests enables suggestion handling
  • chromium_compact_language_detector enables improved language detection (cld2)
  • chardet enables website character encoding detection
  • commentjson allows to keep API keys in commented json
  • lxml enables pair preferences

Precise versions are available in requirements.txt and


Before you install, you can try out a live version of APy at

APy is available through PyPi:

$ pip install apertium-apy

On Ubuntu/Debian, it is also available through apt:

$ wget -qO- | bash
$ apt-get install apertium-apy

Finally, GitHub Container Registry hosts an image of the provided Dockerfile with entry point apertium-apy exposing port 2737:

$ docker pull


Installation through apt or pip adds an apertium-apy executable:

$ apertium-apy --help

usage: apertium-apy [-h] [-s NONPAIRS_PATH] [-l LANG_NAMES] [-f MISSING_FREQS]
                [-p PORT] [-c SSL_CERT] [-k SSL_KEY] [-t TIMEOUT]
                [-j [NUM_PROCESSES]] [-d] [-P LOG_PATH]
                [-i MAX_PIPES_PER_PAIR] [-n MIN_PIPES_PER_PAIR]
                [-u MAX_USERS_PER_PIPE] [-m MAX_IDLE_SECS]
                [-r RESTART_PIPE_AFTER] [-v VERBOSITY] [-V] [-S]
                [-wp WIKI_PASSWORD] [-wu WIKI_USERNAME] [-b]
                [-rs RECAPTCHA_SECRET] [-md MAX_DOC_PIPES] [-C CONFIG]
                [-ak API_KEYS_FILE]

Apertium APY -- API server for machine translation and language analysis

positional arguments:
pairs_path            path to Apertium installed pairs (all modes files in
                        this path are included)

optional arguments:
-h, --help            show this help message and exit
                        path to Apertium tree (only non-translator debug modes
                        are included from this path)
-l LANG_NAMES, --lang-names LANG_NAMES
                        path to localised language names sqlite database
                        (default = langNames.db)
                        path to missing word frequency sqlite database
                        (default = None)
-p PORT, --port PORT  port to run server on (default = 2737)
-c SSL_CERT, --ssl-cert SSL_CERT
                        path to SSL Certificate
-k SSL_KEY, --ssl-key SSL_KEY
                        path to SSL Key File
-t TIMEOUT, --timeout TIMEOUT
                        timeout for requests (default = 10)
-j [NUM_PROCESSES], --num-processes [NUM_PROCESSES]
                        number of processes to run (default = 1; use 0 to run
                        one http server per core, where each http server runs
                        all available language pairs)
-d, --daemon          daemon mode: redirects stdout and stderr to files
                        apertium-apy.log and apertium-apy.err; use with --log-
-P LOG_PATH, --log-path LOG_PATH
                        path to log output files to in daemon mode; defaults
                        to local directory
-i MAX_PIPES_PER_PAIR, --max-pipes-per-pair MAX_PIPES_PER_PAIR
                        how many pipelines we can spin up per language pair
                        (default = 1)
-n MIN_PIPES_PER_PAIR, --min-pipes-per-pair MIN_PIPES_PER_PAIR
                        when shutting down pipelines, keep at least this many
                        open per language pair (default = 0)
-u MAX_USERS_PER_PIPE, --max-users-per-pipe MAX_USERS_PER_PIPE
                        how many concurrent requests per pipeline before we
                        consider spinning up a new one (default = 5)
-m MAX_IDLE_SECS, --max-idle-secs MAX_IDLE_SECS
                        if specified, shut down pipelines that have not been
                        used in this many seconds
                        restart a pipeline if it has had this many requests
                        (default = 1000)
                        logging verbosity
-V, --version         show APY version
-S, --scalemt-logs    generates ScaleMT-like logs; use with --log-path;
                        keeps unknown words in memory until a limit is
                        reached; use with --missing-freqs (default = 1000)
                        How many seconds back to keep track request timing
                        stats (default = 3600)
-wp WIKI_PASSWORD, --wiki-password WIKI_PASSWORD
                        Apertium Wiki account password for SuggestionHandler
-wu WIKI_USERNAME, --wiki-username WIKI_USERNAME
                        Apertium Wiki account username for SuggestionHandler
-b, --bypass-token    ReCAPTCHA bypass token
                        ReCAPTCHA secret for suggestion validation
-md MAX_DOC_PIPES, --max-doc-pipes MAX_DOC_PIPES
                        how many concurrent document translation pipelines we
                        allow (default = 3)
-C CONFIG, --config CONFIG
                        Configuration file to load options from
-ak, --api-keys         JSON file where API keys are stored. Comments are allowed


APy uses GitHub Actions for continuous integration. Locally, use make test to run the same checks it does. After installing Pipenv, run pipenv install --dev to install the requirements required for development, e.g. linters.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

apertium-apy-0.12.0.tar.gz (713.3 kB view hashes)

Uploaded source

Built Distribution

apertium_apy-0.12.0-py3-none-any.whl (559.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page