Weblate Configuration

Last modified by Simon Urli on 2021/09/17 10:28

Weblate is an open source web-based translation tool written in Python. We use it as the implementation behind l10n.xwiki.org.
This page documents the operations contributors are able to perform with Weblate UI. For more information about maintaining Weblate, check this page.

Add new component

Each source translation file on a git repository is handled by its own Weblate component. This means that you can have several components for the same git repository. Whenever a committer adds a new source translation file, they should also creates the corresponding Weblate component. Before adding the new component, there's two question the contributor should ask themselves:

  1. what's the format of the new source translation they add? The XWiki Translation Formats are described there.
  2. is there already an existing component for the repository where the source translation file has been added? if the file has been added to xwiki-commons, xwiki-rendering or xwiki-platform, the answer is yes. If the file has been added to a repository of xwiki-contrib, then they should check if there is already a component for this repository on Weblate.

When you answered those questions, click on the top-right menu on "Add a new translation component". If you don't see this menu then it means you don't have the rights for creating a component.

Then depending if you answered yes or no to the second question, you have two choices:

  • if there is no existing component for the repository, you need to add a component for a new repository
  • else you need to add a component for an already existing repository.

Adding a component for a new repository

For adding a component for a new repository, you need to select "From version control" on the UI of adding new components. That's normally the default option.
Adding a component from version control is done in two steps: 

  1. first step is to indicate the information for cloning the repository
  2. second step, when the repository is cloned, is to specify format and location of the translation source.

Information for cloning the repository

You need to fill the following information:

  • Component name: the pretty name of the component to display in Weblate UI, by convention it should be the name of the Maven module
  • URL slug: this should be automatically derived from the component name, in theory you should not have to modify it. Note that it cannot be changed after the component creation.
  • Project: you have the choice between XWiki Commons, XWiki Rendering, XWiki Platform or XWiki Contrib. In theory you should only create new component from version control for XWiki Contrib.
  • Version control system: pay attention to select GitHub, otherwise there will be issues with the credentials for cloning.
  • Source code repository: it should be the https URL of the Github repository.
  • Repository branch: it should be either master or main.

Once all those information are filled you can click Continue. The repository will be cloned, and Weblate might try to detect automatically the translation files to use: next screen will propose either to chose a path or to fill information manually.

Format and location of the translation source

In order to finish configuring the component, you need to fill the information about the exact location of the translation source, and its format:

  • Translation license: the license should be set and it should be the same than the repository, most of the time for XWiki it should be GNU Lesser Public License v2.1 only
  • Repository push URL: don't forget to copy the repository URL there, since leaving it blanks means the changes won't be push
  • File format: be careful to select the right XWiki format there: you should normally chose only option among "XWiki Java Properties", "XWiki Page Properties" or "XWiki Full Page". For information about the formats check the related documentation
  • File mask: this should be the exact location where the new translation file will be created with a mask represented by "*" which will be replaced by the actual locale of the language. For example: my/module/src/main/resources/ApplicationResources_*.properties
  • Monolingual base language file: this is the path of the source translation file, for example: my/module/src/main/resources/ApplicationResources.properties

Normally you should not have to modify the other options, you can click continue and Weblate will bring you to the component. If you made a mistake somewhere, you can always change one of the setting of the created component by going to the menu "Manage" and "Settings" when on the component.

Adding a component for an existing repository

If the second question's answer is yes, then you need to add a component for a repository already existing.


Get Connected