Metadata-Version: 2.5
Name: django-autotranslate
Version: 2.0.0
Summary: Automatically translate the pot (.po) files generated by Django's makemessages command using machine translation services.
Project-URL: Homepage, https://django-autotranslate.readthedocs.io
Project-URL: Documentation, https://django-autotranslate.readthedocs.io
Project-URL: Repository, https://github.com/ankitpopli1891/django-autotranslate
Project-URL: Issues, https://github.com/ankitpopli1891/django-autotranslate/issues
Project-URL: Changelog, https://django-autotranslate.readthedocs.io/en/latest/changelog.html
Author-email: Ankit Popli <ankitpopli1891@gmail.com>, Brian Kohan <bckohan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,django,i18n,translate
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: django-typer<5,>=4
Requires-Dist: django<6.2,>=5.2
Requires-Dist: googletrans>=4.0.2
Requires-Dist: polib>=1.2.0
Provides-Extra: amazon
Requires-Dist: boto3>=1.43.111; extra == 'amazon'
Provides-Extra: google
Requires-Dist: google-api-python-client>=2.162.0; extra == 'google'
Provides-Extra: progress
Requires-Dist: tqdm>=4.66.0; extra == 'progress'
Description-Content-Type: text/markdown

# django-autotranslate
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![PyPI version](https://badge.fury.io/py/django-autotranslate.svg)](https://pypi.python.org/pypi/django-autotranslate/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/django-autotranslate.svg)](https://pypi.python.org/pypi/django-autotranslate/)
[![PyPI djversions](https://img.shields.io/pypi/djversions/django-autotranslate.svg)](https://pypi.org/project/django-autotranslate/)
[![PyPI status](https://img.shields.io/pypi/status/django-autotranslate.svg)](https://pypi.python.org/pypi/django-autotranslate)
[![Documentation Status](https://readthedocs.org/projects/django-autotranslate/badge/?version=latest)](http://django-autotranslate.readthedocs.io/?badge=latest/)
[![Code Cov](https://codecov.io/gh/ankitpopli1891/django-autotranslate/branch/master/graph/badge.svg)](https://codecov.io/gh/ankitpopli1891/django-autotranslate)
[![Test Status](https://github.com/ankitpopli1891/django-autotranslate/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/ankitpopli1891/django-autotranslate/actions/workflows/test.yml?query=branch:master)
[![Lint Status](https://github.com/ankitpopli1891/django-autotranslate/actions/workflows/lint.yml/badge.svg?branch=master)](https://github.com/ankitpopli1891/django-autotranslate/actions/workflows/lint.yml?query=branch:master)

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

## Installation

```bash
pip install django-autotranslate
```

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

```bash
pip install "django-autotranslate[progress]"
```

Add ``'autotranslate'`` to your ``INSTALLED_APPS`` setting.

```python
INSTALLED_APPS = (
    ...
    'autotranslate',
)
```

## Quick Start

```bash
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

```bash
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]"``):

```python
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):

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

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

```python
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](https://www.rfc-editor.org/info/bcp47) 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:

```python
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

| autotranslate | django      |
| :-----------: | :---------: |
| v1.0.x        | Django 1.5+ |
| v1.1.x        | Django 1.8+ |
| v2.0.x        | Django 5.2+ |

## Documentation

Full documentation is available at [django-autotranslate.readthedocs.io](https://django-autotranslate.readthedocs.io).

## Development

```bash
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](CONTRIBUTING.md).
