commit 68ec79de376eaee18bba592c5f3ba6bdee4052de
parent 4ce02fc38c228384a6c221c0fabcc74610976bf5
Author: Stefan Kügel <stefan.kuegel@taler.net>
Date: Thu, 16 Oct 2025 12:31:04 +0200
update translation standards and practices to the developer manual (internationalisation)
Diffstat:
1 file changed, 51 insertions(+), 29 deletions(-)
diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst
@@ -891,7 +891,7 @@ only reserved to "admin" users.
Internationalisation
====================
-Internationalisation (a.k.a "translation") is handled with Weblate (https://weblate.org) via our instance at https://weblate.taler.net/ organised as so-called strings in a bunch of Git repositories.
+Internationalisation (a.k.a "translation") is handled with Weblate (https://weblate.org) via our instance at https://weblate.taler.net/ organised as so-called *strings* in a bunch of Git repositories.
Who can register
----------------
@@ -913,15 +913,60 @@ This is the breakdown of privilege levels in Weblate:
* **Superusers** = Can create new *projects*, moreover they manage Weblate's settings and repository maintenance, can edit all user accounts, deactivate users, trigger commits from Weblate's local repositories with pushes to Git and perform backups of language files
-Upgrading privileges
---------------------
+How to contribute with your translation
+---------------------------------------
+
+1 - Log into https://weblate.taler.net
+
+2 - Navigate to *Projects* and *Browse all projects*
+
+3 - Choose the *project* you wish to contribute to
+
+4 - Choose the *component* you wish to contribute to
+
+5 - Find the language you want to translate into
+
+6 - Find a phrase and translate it
+
+7 - While translating, take into consideration at each string to translate
+
+* the comments
+
+* the context
+
+* the string location in the source code
+
+* the "nearby strings" in Weblate as one of the sorting options on the translation form
+
+* "other languages" as another sorting option to compare strings in a way translatologists would do
+
+* if applicable, the history of string changes and the message ID or key of a string
+
+8 - **Always test your translations in the actual apps** after they have been pushed by the platform to the apps
+
+9 - Be aware of ambiguities and immediately **report inconsistencies or bugs** by using Mantis bug tickets
+
+10 - If you want to contribute your translation in a language which does not yet exist in a Taler component, navigate to the *component* you want to translate for and click "Start new translation" to begin. In case you require a privilege upgrade, please contact a *Superuser* with your request. Currently, *Superusers* are Christian, Florian, Martin, and Stefan.
+
+Translation standards and practices
+-----------------------------------
-To upgrade from **Users**/**Viewers**, a *Superuser* must manually elevate your privileges. Currently, *Superusers* are Christian, Florian, Martin, and Stefan.
+1 - *Developers*, Weblate *reviewers* and *managers* MUST look into **design documents** for the specific component or software project, like e.g. for the Taler wallets DD53 https://docs.taler.net/design-documents/053-wallet-ui.html and stick close to the documentation, especially the **text to use** and **text to avoid**
+
+2 - To every ambiguous string *developers* MUST add **context** or **comments** to the strings on Weblate
+
+3 - *Developers*, Weblate *reviewers* and *managers* SHOULD add **screenshots** where needed to the strings on Weblate
+
+4 - Weblate *managers* MUST take care of **checks** in the translations overview and keep the repositories consistent and up-to-date, t.i. to perform regularly **synchronisation** between Git and Weblate repositories and vice-versa
+
+5 - *Weblate admins* MUST set the **commit and push rules** to *manual* only, and when asked, set the license to *GPLv3 or later*
+
+6 - You MAY also wish to refer to https://docs.weblate.org/ and to the ``README files`` in components like web pages to find out more specific variables if prompted
How to create a project
-----------------------
-The *GNU Taler* project is probably the correct project for most Weblate components and Taler-related translations falling under this guide. Please contact a *Superuser* if you need another project created.
+The *GNU Taler* project is probably the correct project for most Weblate components and Taler-related translations. Please contact a *Superuser* if you need another project created.
How to create a component
-------------------------
@@ -993,6 +1038,7 @@ Translation: {{ project_name }}/{{ component_name }}
Translate-URL: {{ url }}
At the tab *Files*
+
* **File format** - Mostly ``gettext PO file`` for web pages, ``Android String Resource`` for Android app strings, ``XLIFF 1.2 translation file`` for iOS apps, or ``TermBase eXchange file`` for some of the glossaries
* **Language filter** - Dependent on the respective folder structure of the project, for structures used with gettext PO files mostly ``locale/*/LC_MESSAGES/messages.po``
@@ -1015,30 +1061,6 @@ At the tab *Files*
* **Screenshot file mask** - Leave empty (unless we do not dispose of a dedicated screenshot folder with a path relative to repository root)
-How to create a translation
----------------------------
-
-1 - Log into https://weblate.taler.net
-
-2 - Navigate to *Projects* and *Browse all projects*
-
-3 - Choose the *project* you wish to contribute to
-
-4 - Choose the *component* you wish to contribute to
-
-5 - Find the language you want to translate into
-
-6 - Find a phrase and translate it
-
-Translation standards and practices
------------------------------------
-
-If you want to contribute a translation in a different language, navigate to the *Component* you want to translate for and click "Start new translation" to begin. If you require a privilege upgrade, please contact a Superuser with your request.
-
-*Managers* and admins should set the commit and push rules to manual only. When asked, set the license to GPLv3 or later.
-
-You may also wish to refer to https://docs.weblate.org/ and to the ``README files`` in components like web pages to find out more specific variables if prompted.
-
GPG signing of translations
---------------------------
