django-autotranslate

Automatically translate the pot (.po) files generated by Django's makemessages command using machine translation services.

Installation

pip install django-autotranslate

To show a progress bar while translating, install the progress extra:

pip install "django-autotranslate[progress]"

Add 'autotranslate' to your INSTALLED_APPS setting.

INSTALLED_APPS = (
    ...
    'autotranslate',
)

Quick Start

django-admin autotranslate

The command finds all the generated pot (.po) files under the locale paths (LOCALE_PATHS) specified in django project settings, and translates them automatically.

Options

• -p, --path: A locale directory to translate (can be given more than once)
• -a, --app: An app whose messages to translate (can be given more than once)
• -l, --locale: Only translate this locale, e.g. pt_BR or pt-br (can be given more than once). By default every locale found is translated
• -r, --retranslate: Translate all messages again, including translated messages and messages awaiting review
• -f, --set-fuzzy: Mark machine translations as fuzzy so they can be reviewed before use (fuzzy entries are not compiled)
• -s, --source-language: The language the messages are written in (default en)
• --service: The translation service to use instead of settings.AUTOTRANSLATE_SERVICE
• --no-progress: Do not show a progress bar. A progress bar is shown when the progress extra is installed and the output is a terminal

django-admin autotranslate -l 'de' -l 'es'

Settings

The translation service is set with AUTOTRANSLATE_SERVICE. It defaults to the free Google Translate service, "autotranslate.services.GoogleTranslatorService". To use a different service give its import path, or a dictionary with the import path as BACKEND and OPTIONS to configure it. The --service option overrides the setting for a single run, the OPTIONS are only used with the configured BACKEND.

• Paid Google Cloud Translation (pip install "django-autotranslate[google]"):

AUTOTRANSLATE_SERVICE = {
    "BACKEND": "autotranslate.services.GoogleAPITranslatorService",
    "OPTIONS": {
        "api_key": "<google-api-key>",  # required
        "max_segments": 128,  # strings per request
    },
}

• Amazon Translate (pip install "django-autotranslate[amazon]"). The OPTIONS are passed to boto3.client(), anything not given is found by boto3 as usual (environment variables, ~/.aws config files, instance roles):

AUTOTRANSLATE_SERVICE = {
    "BACKEND": "autotranslate.services.AmazonTranslateTranslatorService",
    "OPTIONS": {"region_name": "us-east-1"},
}

• Free Google Translate (default). The OPTIONS tune how requests are retried:

AUTOTRANSLATE_SERVICE = {
    "BACKEND": "autotranslate.services.GoogleTranslatorService",
    "OPTIONS": {
        "retries": 3,  # retries for network errors and rejected requests
        "retry_delay": 1.0,  # seconds before retrying a network error (doubles)
        "rate_limit_delay": 30.0,  # seconds before retrying a rejected request (doubles)
    },
}

Language codes

Django identifies languages with lower case BCP 47 language tags (e.g. pt-br, zh-hans), which the services spell differently. Each Django language is matched to the service's languages by:

1. The service's built in exceptions, e.g. zh-hans is zh-CN for Google, zh for Amazon, and Django's pt (European Portuguese) is pt-PT for the paid services, whose pt is Brazilian.
2. A case insensitive match against the languages the service supports.
3. Dropping region subtags, e.g. pt-br becomes pt. Script subtags are never dropped, so sr-latn (Latin script Serbian) is not translated as Cyrillic Serbian.

Languages that do not match are skipped. Every service accepts a language_map option to add or override exceptions, map a language to None to skip it:

AUTOTRANSLATE_SERVICE = {
    "BACKEND": "autotranslate.services.GoogleAPITranslatorService",
    "OPTIONS": {
        "api_key": "<google-api-key>",
        # use Brazilian Portuguese for pt and skip Argentinian Spanish
        "language_map": {"pt": "pt", "es-ar": None},
    },
}

Placeholders and markup

Placeholders and markup in messages are protected from translation:

• python-format placeholders (%(name)s, %d, %.2f, %%) and python-brace-format placeholders ({name}, {0:>10}, {{), chosen by the flags makemessages writes for each message.
• HTML: tags, character references (ending in ;, so AT&T is ordinary text) and comments are kept and the text inside elements is translated, except in code, kbd, pre, samp, script, style and var elements. Attribute values are not translated.
• Newlines.

The paid Google and Amazon services are told not to translate them (translate="no"). The free Google service only translates plain text, so they are replaced with numbered tokens (__x0__). Translations that lose or change a placeholder or tag, or add placeholders or markup that were not in the source message, are discarded with a warning and the message is left untranslated.

Compatibility Matrix

Documentation

Full documentation is available at django-autotranslate.readthedocs.io.

Development

git clone https://github.com/ankitpopli1891/django-autotranslate.git
cd django-autotranslate
just setup
just install
just test

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.