A library for making Toolforge tools written in Python translatable.
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. -
By default, support for a MediaWiki-like
?uselang=URL parameter, including?uselang=qqxto see message keys. -
Correct conversion between MediaWiki language codes and HTML language codes / IETF BCP 47 language tags; for instance,
?uselang=simpleproduces<html lang="en-simple">. -
Correct
lang=anddir=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 tests that check all the translations for unexpected elements (e.g.
<script>) or attributes (e.g.onclick=), to protect against XSS attacks from translations. (You must set up CI to run these tests, e.g. in GitLab CI or GitHub actions.)
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.pywith 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, withen.jsonandqqq.jsonfiles, just like for MediaWiki extensions.en.jsoncontains English messages, whileqqq.jsoncontains message documentation; both contain a JSON object mapping the message key to the text / documentation. -
In your tool’s tests, add a file
test_translations.pywith at least the following contents:from toolforge_i18n.translations_tests import * # noqa: F401, F403
-
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 likeapp = 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 likemessage('message-key', arg1='X', arg2='Y')and define the variable names intool_translations_config(as mentioned above).
That should be it, but I might have forgotten some steps. Also, at some point I’ll surely flesh this out more.
License
BSD-3-Clause
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file toolforge_i18n-0.0.1.tar.gz.
File metadata
- Download URL: toolforge_i18n-0.0.1.tar.gz
- Upload date:
- Size: 20.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: python-httpx/0.27.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 6c34c20e828088d08dc27b34af6d3a9352a39bd10555d6431333f75f31de0e51 |
|
| MD5 | fcdc91f52e0617745d0d69a0b752a665 |
|
| BLAKE2b-256 | 2921511c415db333b711b20a675074f44f4cbac7d1db9e5a2f08544555b5ef90 |
File details
Details for the file toolforge_i18n-0.0.1-py3-none-any.whl.
File metadata
- Download URL: toolforge_i18n-0.0.1-py3-none-any.whl
- Upload date:
- Size: 18.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: python-httpx/0.27.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 9ff0152a13a4c1dcfe53b4b12daf0fac20dce12756ddeffe7ed8f0560026c1a1 |
|
| MD5 | 7eba743cb2ea942377cc3ba69780c7cd |
|
| BLAKE2b-256 | e0c110aaa95124fb48ece899b2fc4a06c418e1206f295ca1564d28c4d2f9166a |
