Commit 3869dfb7 authored by Peter Serwylo's avatar Peter Serwylo

Add documentation for working with Weblate.

There are some specific needs we have when setting up Weblate, which are
now documented here.
parent 0487463f
## Configuring Weblate
The translation setup is designed to work with three different Weblate Components:
* Website (navigation, home page, sidebars)
* Documentation
* Website News
Below is the list of important properties to set when adding a new Weblate component.
These are important or else the translation system will not work.
It does not document the more simple things such as Name/URL/etc.
### Website
* **File mask:** `_data/*/strings.json`
* **Monolingual base language file:** `_data/strings.json`
* **Edit base file:** No
* **Base file for new translations:** `_data/strings.json`
* **File format:** JSON file
* **Pre-commit script:** `hook-json_restore_hierarchy` ([info about this script](
* **Priority:** Very high
The priority doesn't _need_ to be "Very high", but it is the most front-facing of all parts of the website.
In addition, it is also the smallest part and hopefully the easiest to translate.
## Pulling translations
This section documents pulling translations from Weblate and integrating them with the website.
As with the Weblate documentation, it will describe the three different projects.
From your local repository, ensure you have a `git` remote for each Weblate component.
Here is an example for the "Website" component, where `` is the weblate server you are using (e.g. ``):
git remote add weblate-website
### Website
Merge the latest translations, for example:
git fetch weblate-website
git merge weblate-website/master
Once the translations are available, we need to update the `_config.yml` to ensure it is aware of the translations which are available.
The following script will update the `languages: [ 'en', ... ]` attribute in the config file.
In addition, it will also attempt to download a flag for any new translations for the language chooser widget:
#### Troubleshooting
**A new translation was added, but all the strings are blank when viewing the translation on the website.**
This can happen if the **Pre-commit script** in the Weblate component is not setup correctly.
Check the newly added `_data/[LANG]/strings.json` file and see if it is a flat file like this:
"navigation.browse": "...",
"navigation.documentation": "...",
instead of what it should be:
"navigation": {
"browse": "...",
"documentation": "...",
If so, the `hook-json_restore_hierarchy` [script needs to be configured correctly]( in Weblate.
This script can also be downloaded and run locally on the problem file, e.g. `hook-json_restore_hierarchy _data/[LANG]/strings.json`.
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment