commit 464c6f3179ef953f911926fe8d160245746cc9c4
parent 5aa48cdbccb89c350b0d96fde0431fcae9c0599f
Author: Stefan Kügel <stefan.kuegel@taler.net>
Date: Tue, 14 Oct 2025 11:41:15 +0200
update instructions how to use Weblate in the developer manual documentation
Diffstat:
1 file changed, 106 insertions(+), 43 deletions(-)
diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst
@@ -888,100 +888,163 @@ There is also the possibility to trigger builds manually, but this is
only reserved to "admin" users.
-Internationalization
+Internationalisation
====================
-Internationalization (a.k.a "Translation") is handled with Weblate (https://weblate.org) via our instance at https://weblate.taler.net/ .
+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.
-At this time, this system is still very new for Taler.net and this documentation may be incorrect and is certainly incomplete.
-
-Who can Register
+Who can register
----------------
-At this time, anyone can register an account at https://weblate.taler.net/ to create translations. Registered users default to the **Users** and **Viewers** privilege level.
+At this time, anyone can register an account at https://weblate.taler.net/ to create translations. Registered users default to the **Users** and **Viewers** privilege levels.
-About Privilege Levels
+About privilege levels
----------------------
This is the breakdown of privilege levels in Weblate:
-* **Users**/**Viewers** = Can log in, view Translations (*applies to new users*)
+* **Viewers** = Have access to translations and can view them but are not entitled to translate
+
+* **Users** = Can log in and perform translations (*applies to new users*)
-* **Reviewers** = Can contribute Translations to existing *Components*
+* **Reviewers** = Can contribute translations to existing *components* and review translations
-* **Managers** = Can create new *Components* of existing *Projects*
+* **Managers** = Can create new *components* of existing *projects*
-* **Superusers** = Can create new *Projects*
+* **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
+Upgrading privileges
--------------------
-To upgrade from **Users**/**Viewers**, a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck.
+To upgrade from **Users**/**Viewers**, a *Superuser* must manually elevate your privileges. Currently, *Superusers* are Christian, Florian, Martin, and Stefan.
-How to Create a Project
+How to create a project
-----------------------
-The *GNU Taler* project is probably the correct project for most Components and 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 falling under this guide. Please contact a *Superuser* if you need another project created.
-How to Create a Component
+How to create a component
-------------------------
-Reference: https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#component-configuration
+Reference: https://docs.weblate.org/en/weblate-5.13.2/admin/projects.html#component-configuration
+
+In Weblate, a *component* is a subset of a *project* and each component contains N translations. A component is generally associated with a Git repository.
+
+To create a component, log into https://weblate.taler.net/ with your credentials for a *Manager* privilege level (or higher) and choose **+ Add** from the upper-right corner.
+
+What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your component to the Taler Git repository:
+
+On the component level, choose *Operations* from the menu bar, select *Settings*, then add at the tab *Basic* these settings:
+
+* **Component name** - The distinctive name of the software project, e.g. ``Main web site``
+
+* **Translation license** - Choose *GNU Affero General Public License v3.0 or Later*
+
+* **Contributor license agreement** - left empty as the *Translation license* defaults
+
+* **Source string bug reporting address** - This requires an email address of the Weblate admin or *Superuser* in charge or just ``languages@taler.net``
+
+* **Priority** - Generally ``Medium``
+
+* **Restricted component** - ``deactivated``
+
+* **Share in projects** - ``deactivated``
+
+* **Use as a glossary** - ``deactivated``
+
+At the tab *Translation* settings are generally:
+
+* **Turn on suggestions** - ``activated``
+
+* **Allow translation propagation** - ``activated``
-In Weblate, a *Component* is a subset of a *Project* and each Component contains N translations. A Component is generally associated with a Git repo.
+* **Contribute to project translation memory** - ``activated``
-To create a Component, log into https://weblate.taler.net/ with your *Manager* or higher credentials and choose **+ Add** from the upper-right corner.
+* **Secondary language** - Leave empty (respectively ``--------`` )
-What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your Component to the Taler Git repository:
+At the tab *Version control* ( *https://weblate.taler.net/create/component/vcs/* ) settings require variables as follows:
-Under *https://weblate.taler.net/create/component/vcs/*:
+* **Version Control System** - Generally ``Git``
-* **Source code repository** - Generally ``git+ssh://git@git.taler.net/<reponame>```. Check with ``git remote -v``.
+* **Source code repository** - Generally ``git+ssh://git@git.taler.net/<repositoryname>.git``, check with ``git remote -v``
-* **Repository branch** - Choose the correct branch to draw from and commit to.
+* **Repository branch** - Choose the correct branch to draw from and commit to which is generally ``master``
-* **Repository push URL** - This is generally ``git+ssh://git@git.taler.net/<reponame>``` Check with ``git remote -v``.
+* **Repository push URL** - Generally ``git+ssh://git@git.taler.net/<repositoryname>.git``, check with ``git remote -v``
-* **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ``<repositoryname>`` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string.
+* **Push branch** - Choose the correct branch to push to, this is generally ``master``
-* **Merge style** - *Rebase*, in line with GNU Taler development procedures
+* **Repository browser** - Normally, this field is left empty. If you are required to have this field pointing to the www URL of the Git repo's file browser, it could be filled with ``https://git.taler.net/<repositoryname>.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ``<repositoryname>`` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string
-* **Translation license** - *GNU Affero General Public License v3.0 or Later*
+* **Push on commit** - ``deactivated``
-* **Adding new translation** - Decide how to handle adding new translations
+* **Age of changes to commit** - 24 (hours after which any pending changes will be committed to the VCS)
-How to Create a Translation
+* **Merge style** - Generally ``Rebase``, in line with GNU Taler development procedures
+
+* **Lock on error** - ``activated``
+
+At the tab *Commit messages* you can leave the defaults:
+
+* **Commit message when translating** has the most important message:
+Translated using Weblate ({{ language_name }})
+Currently translated at {{ stats.translated_percent }}% ({{ stats.translated }} of {{ stats.all }} strings)
+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``
+
+* **Language filter** - Generally ``^[^.]+$``
+
+* **Source language** - ``English``
+
+* **Monolingual translations / Monolingual base language file** - Leave empty
+
+* **Edit base file** - ``deactivated``
+
+* **Intermediate language file** - Leave empty
+
+* **Template for new translations** - Dependent on the respective folder structure of the project, for structures used with gettext PO files ``locale/messages.pot``
+
+* **Adding new translation** - Generally ``Create new language file``
+
+* **Language code style** - Generally ``Default based on the file format``
+
+* **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* > *Browse all projects*
-
-3 - Choose the *Project* you wish to contribute to.
+2 - Navigate to *Projects* and *Browse all projects*
-4 - Choose the *Component* you wish to contribute to.
+3 - Choose the *project* you wish to contribute to
-5 - Find the language you want to translate into. Click "Translate" on that line.
+4 - Choose the *component* you wish to contribute to
-6 - Find a phrase and translate it.
+5 - Find the language you want to translate into
-You may also wish to refer to https://docs.weblate.org/ .
+6 - Find a phrase and translate it
-Translation Standards and Practices
+Translation standards and practices
-----------------------------------
-By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. 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.
+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.
-When asked, set the license to GPLv3 or later.
+*Managers* and admins should set the commit and push rules to manual only. When asked, set the license to GPLv3 or later.
-Set commit/push to manual only.
+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
+GPG signing of translations
---------------------------
-weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at https://weblate.taler.net/keys/.
+Weblate signs its GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at https://weblate.taler.net/keys/.
-This means that contributions made through weblate will not be signed with the individual contributor's key when they are checked into the Git repository, but with the weblate key.
+This means that contributions made through Weblate will not be signed with the individual contributor's key when they are checked into the Git repository but with Weblate's public key.
