TRANSLATIONS.md 5.67 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
## Adding/updating translatable content

There are two different ways in which content on the website is translated.

### Website

If you are adding content to the home page, sidebars, navigation, or other static parts of the website (i.e. not Jekyll posts/pages)
then it is done using [localized site data](https://github.com/untra/polyglot#localized-sitedata).

Say you want to add a new paragraph to the home page.
Firstly, add a new entry to the `_data/strings.json` file:

```json
{
  "home": {
    "my_new_paragraph": "Here is the paragraph to be added (and also translated)",
    ...
  },
  ...
}
```

Then, reference this from the `index.md` file:

```markdown
{{ site.data.strings.home.my_new_paragraph }}
```

If you need to reference many strings in a single `.md` file, then it may be more concise to first assign a variable:

```markdown
{% assign strings = site.data.strings.home %}
{{ strings.my_new_paragraph }}
```

### Documentation + Website News

When a new `.md` file is added to the `_docs/` or `_posts/` directory, then you need to run:

```bash
./tools/i18n.sh md2po
```

This will extract the strings from all Markdown files in these two directories and output them to either `po/_docs.po` or `po/_posts.po`.
These will then subsequently be translated by Weblate into additional files such as `po/_docs.fr.po`.

47 48 49 50
In addition, the script will update any already existing translations such as `po/_docs.fr.po`.
It does so by using the [msgmerge](https://www.gnu.org/software/gettext/manual/html_node/msgmerge-Invocation.html) program from GNU gettext.
This takes care of fuzzy string matches, new strings, and deleted strings.

51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
## 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](https://docs.weblate.org/en/latest/formats.html#json-files))
 * **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.

76 77 78 79 80 81 82 83
### Documentation + Website News

These two components are managed in exactly the same way.
The only difference is that one generates translations from `_docs/*.md` and the other from `_posts/*.md`.
As such, this will only document the process for Documentation.
For Website News, do the same, but wherever you see `_docs` replace it with `_posts`.

 * **File mask:** `po/_docs.*.po`
84
 * **Edit base file:** No
85 86 87 88 89
 * **Base file for new translations:** `po/_docs.po`
 * **File format:** Gettext PO file

It is suggested that the Documentation has a higher **Priority** than Website News.

90 91 92 93 94 95 96 97 98 99 100 101
## 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 `example.com` is the weblate server you are using (e.g. `hosted.weblate.org`):

```bash
git remote add weblate-website https://example.com/weblategit/fdroid/website/
```

102
Then, regardless of the component, you will need to pull the translations from the relevant remote, e.g:
103 104 105 106 107 108 109

```bash
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.
110 111
The following script will update the `languages: [ 'en', ... ]` attribute in the config file to those which are marked as 100% translated
in the ["Website" project on Weblate](https://hosted.weblate.org/projects/f-droid/website/):
112 113

```bash
114 115 116 117 118 119 120 121 122
$ ./tools/update_langs.py


```

For development, you can also request all translations be included, regardless of how complete they are:

```bash
./tools/update_langs.py --partial
123 124
```

125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
### Documentation + Website News

For these two components, all Weblate does is produce translated `.po` file.
Once you have merged the translations from Weblate, this `.po` file needs to be processed to generate localized versions of each `.md` file.
This is done by running:

```bash
./tools/i18n.sh po2md
```

### Website

There is no special requirements once the Website translations are pulled from Weblate.
This is because Jekyll directly uses the JSON files that Weblate created.

140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
#### 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:

```json
{
  "navigation.browse": "...",
  "navigation.documentation": "...",
  ...
}
```

instead of what it should be:

```json
{
  "navigation": {
    "browse": "...",
    "documentation": "...",
    ...
  }
}
```

If so, the `hook-json_restore_hierarchy` [script needs to be configured correctly](https://docs.weblate.org/en/latest/formats.html#json-files) in Weblate.
168
This script can also be downloaded and run locally on the problem file, e.g. `hook-json_restore_hierarchy _data/[LANG]/strings.json`.