Project description

Toolforge I18n

A work in progress library for making Wikimedia Toolforge tools written in Python+Flask translatable.

Features

Make your tool translatable into dozens, potentially hundreds of languages!
Easy integration with translatewiki.net by reusing MediaWiki message file syntax.
Full support for the magic words {{GENDER:}} and {{PLURAL:}}, as well as for hyperlink syntax ([url text]) and list formatting.
- Note that there is no support for any other wikitext syntax; formatting in messages (e.g. bold passages) should be written in plain HTML, if it can’t be left out the message entirely (e.g. on a surrounding element in the template).
By default, support for a MediaWiki-like ?uselang= URL parameter, including ?uselang=qqx to see message keys.
Correct conversion between MediaWiki language codes and HTML language codes / IETF BCP 47 language tags; for instance, ?uselang=simple produces <html lang="en-simple">.
Correct lang= and dir= in the face of language fallback: messages that (due to language fallback) don’t match the surrounding markup are automatically wrapped in a <span> with the right attributes. (Even MediaWiki doesn’t do this! Though, admittedly, MediaWiki doesn’t have the luxury of assuming that every message can be wrapped in a <span> – many MediaWiki messages are block elements that would rather need a <div>.)
Includes checks to ensure all translations are safe, without unexpected elements (e.g. <script>) or attributes (e.g. onclick=), to protect against XSS attacks from translations. The tests are automatically registered via a pytest plugin and also run at tool initialization time.

How to use it

The library is still a work in progress, so preferably don’t use it yet :) but if you’re feeling adventurous, the rough steps should be:

Add the library to your tool’s dependencies. (As the library is still in its early stages, and there may be breaking changes, I recommend pinning your dependencies using pip-tools or something similar.)
In your tool’s source code, add a file tool_translations_config.py with at least the following contents:
```
from toolforge_i18n.translations import TranslationsConfig

config = TranslationsConfig()
```
Later, you may want to customize parts of the translations config, such as the message variables; see the class documentation for details.
Create an i18n/ directory, with en.json and qqq.json files, just like for MediaWiki extensions. en.json contains English messages, while qqq.json contains message documentation; both contain a JSON object mapping the message key to the text / documentation.
In your tool’s source code (probably app.py), add the following import:
```
from toolforge_i18n.flask_things import ToolforgeI18n, message
```
And add this line shortly after creating the app (which usually looks like app = flask.Flask(__name__)):
```
i18n = ToolforgeI18n(app)
```
Use message('message-key') for any message that should be translatable, either in a Jinja2 template ({{ message('message-key') }}) or directly in the Python code. For messages with parameters, use kwargs syntax like message('message-key', arg1='X', arg2='Y') and define the variable names in tool_translations_config (as mentioned above).

Optionally, set up CI for your tool, and run pytest in it. This will automatically run tests that ensure the translations are safe. A basic CI setup for tools on Wikimedia GitLab might look like this (.gitlab-ci.yml):

stages:
  - test

variables:
  PYTHONDONTWRITEBYTECODE: "1"
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

test-job:
  stage: test
  image: python:3.11
  cache:
    - key: pip-python-3.11
      paths:
        - .cache/pip
  script:
    - python3 -m pip install -r requirements.txt
    - python3 -m pip install pytest
    - pytest

See also the check_translations flag for tool_translations_config.

License

BSD-3-Clause

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

0.0.5

Jul 21, 2024

0.0.2

Jul 7, 2024

0.0.1

Jun 4, 2024

Download files

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

Source Distribution

toolforge_i18n-0.0.5.tar.gz (24.1 kB view hashes)

Uploaded Jul 21, 2024 Source

Built Distribution

toolforge_i18n-0.0.5-py3-none-any.whl (23.8 kB view hashes)

Uploaded Jul 21, 2024 Python 3

Hashes for toolforge_i18n-0.0.5.tar.gz

Hashes for toolforge_i18n-0.0.5.tar.gz
Algorithm	Hash digest
SHA256	`ea3a1e748fa409dc7b5b33e874146a78c2357dac3b92a12d63a337a99ec11ccc`
MD5	`3887292bb33e6a67270825d7aded58ad`
BLAKE2b-256	`701f7646e3e973f80f2b340cbb25925af6dd3512953255047a2ffd742a574e5d`

Hashes for toolforge_i18n-0.0.5-py3-none-any.whl

Hashes for toolforge_i18n-0.0.5-py3-none-any.whl
Algorithm	Hash digest
SHA256	`a03c4eea1705a90661dfc852f00f2d5a1566bfea988de5decce13f14d03a3a22`
MD5	`23ccc4ce79eb13a5c5d7563b9a886e50`
BLAKE2b-256	`5cc87230fb101c766cc6ebbd220f9b57e5f0e699d96ba690561a3e42272665d6`