Commit c9589562 authored by Arlo James Barnes's avatar Arlo James Barnes 💭
Browse files

Update 110_Translate_the_website.md

parent 14b882c7
# How to translate the website
Merge requests about translation, correction, proofreading are all very welcome. The translation uses Gettext and PO files. The files are located in the ``po/`` directory of the [website
Merge requests about translation, correction, and proofreading are all very welcome. The translation uses Gettext and PO files. The files are located in the ``po/`` directory of the [website
repository](https://framagit.org/peppercarrot/website-2021) on Framagit. In this directory, the translation consists of 3 parts:
1. A [`<locale>.po`](#1-localepo) file with the actual translation source code.
......@@ -21,12 +21,12 @@ repository](https://framagit.org/peppercarrot/website-2021) on Framagit. In this
To start a new translation, open the `_catalog.pot` file in a Po editor (see recommended tools below) and save it under `po/<locale>.po` (replacing `<locale>` with your language's code from [langs.json](https://framagit.org/peppercarrot/webcomics/-/blob/master/langs.json)). Using an editor like this will update the file header correctly for your language. If you need help, please [open an issue on GitLab](https://framagit.org/peppercarrot/website-2021/-/issues/new) and tag @gunchleoc, or use any of the contact options on the bottom of the website.
The po file format is human-readable, so you can edit it in a plain text editor if you want. We recommend continuing translation on our [Weblate project](https://weblate.framasoft.org/projects/peppercarrot/) after creating and submitting an initial file (see the [Weblate Guide](#weblate-guide) below). This will give you some automated quality checks on your translation, and you can still download the files to translate in any editor that you like and then upload again. The Weblate project is hosted by Framasoft, just like our GitLab repository.
The Po file format is human-readable, so you can edit it in a plain text editor if you want. We recommend continuing translation on our [Weblate project](https://weblate.framasoft.org/projects/peppercarrot) after creating and submitting an initial file (see the [Weblate Guide](#weblate-guide) below). This will give you some automated quality checks on your translation, and you can still download the files to translate in any editor that you like and then upload again. The Weblate project is hosted by Framasoft, just like our GitLab repository.
For translating offline, there are Free/libre and open-source tools available on all operating systems, for example:
* [PoEdit](https://poedit.net/) - This tool comes with some automated translation checks that are useful.
* [Virtaal](https://docs.translatehouse.org/projects/virtaal/en/latest/) - This tool comes with a translation memory function and will be helpful in restoring older translations. Load the `.po` file for your locale from the [archive](https://framagit.org/peppercarrot/website-2021/-/tree/main/po/archive) into the tool to fill the translation memory before translating the new website files.
* [PoEdit](https://poedit.net) - This tool comes with some automated translation checks that are useful.
* [Virtaal](https://docs.translatehouse.org/projects/virtaal/en/latest) - This tool comes with a translation memory function and will be helpful in restoring older translations. Load the `.po` file for your locale from the [archive](https://framagit.org/peppercarrot/website-2021/-/tree/main/po/archive) into the tool to fill the translation memory before translating the new website files.
Once you opened your file with the tool, you just need to click on the line to translate and fill it. Just repeat the
process until you are done and save. Simple! Virtaal also has a lot of convenient [keyboard shortcuts](https://docs.translatehouse.org/projects/virtaal/en/latest/using_virtaal.html).
......@@ -37,11 +37,11 @@ The previous version of the website was translated into 33 languages. Unfortunat
the new website and it was hard to translate. But the work done has been preserved in the
[po/archive](https://framagit.org/peppercarrot/website-2021/-/tree/main/po/archive) folder. If you find a translation, you can open it with a text-editor and see,
copy/paste the best ideas. They are archived for reference.
We have also created a po version that you can load into your tool to fill its translation memory, and they are also searchable on [Weblate](https://weblate.framasoft.org/projects/peppercarrot/archive/).
We have also created a po version that you can load into your tool to fill its translation memory, and they are also searchable on [Weblate](https://weblate.framasoft.org/projects/peppercarrot/archive).
#### Special cases:
Sometime you'll come across texts that looks like this:
Sometime you'll come across strings that looks like this:
```
"Join the <a href=\"%s\">Pepper&Carrot chat room</a> to share your projects!"
......@@ -54,7 +54,7 @@ You'll also come across the ``%s`` symbol:
```
The website will replace this special character ``%s`` with a string (in this case, the name of the author), so, please preserve this symbol.
For numbers, we use `%d` instead of `%s`. These are fetched using plural rules. Check the [Translatehouse Lozalization Guide](https://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html) if you don't know the plural rules for your language. If you need further help with understanding the plural rules for your language, open an issue and tag `@gunchleoc`.
For numbers, we use `%d` instead of `%s`. These are fetched using plural rules. Check the [Translatehouse Localization Guide](https://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html) if you don't know the plural rules for your language. If you need further help with understanding the plural rules for your language, open an issue and tag `@gunchleoc`.
When the same string contains more than one of these placeholders, we number them so that you can change the word order, e.g. from:
```
......@@ -80,7 +80,8 @@ the translation.
]
}
```
The name field supports Nicknames (single word) or composed name (many words) and you can add an URL of your choice to
The name field supports nicknames (single word) or composed names (many words) and you can add an URL of your choice to
it between brackets. Proofreaders and Contributors can also be added. In its full form, the file might look like that:
```
......@@ -91,7 +92,7 @@ it between brackets. Proofreaders and Contributors can also be added. In its ful
],
"proofreading": [
"Koala Yellow <http://www.forest.com>",
"Girafe Green"
"Giraffe Green"
],
"contribution": [
"Cat Carrot <https://www.peppercarrot.com>",
......@@ -111,12 +112,11 @@ This Inkscape (svg) vector file customise the title used on the front cover of t
the navigation bar. This file is optional, no file provided will force the website to use the en.svg version as a
fallback. Specifications:
- **560x120px SVG** (you can duplicate en.svg to get same geometry)
- **560×120px SVG** (you can duplicate en.svg to get same geometry)
- **Black colors** to fill the shape.
- **Saved as "Optimized SVG"** in Inkscape to crunch the weight of the SVG.
You'll find font artwork already done on many of the header files of the webcomic. If you have trouble making a good
looking title, ask help to other translator (eg. opening [an issue on the webcomic
You'll find font artwork already done on many of the header files of the webcomic. If you have trouble making a good-looking title, ask help to other translator (e.g. by opening [an issue on the webcomic
repository](https://framagit.org/peppercarrot/webcomics/-/issues)).
<hr/>
......@@ -134,9 +134,9 @@ Before the website can use the files, they need to be transformed into binary fi
### Define your Languages
After [registering an account](https://weblate.framasoft.org/accounts/register/) with Framasoft's Weblate, you need to define which languages you translate. Click on your avatar, then choose Settings, which will put you in the "Languages" tab:
After [registering an account](https://weblate.framasoft.org/accounts/register) with Framasoft's Weblate, you need to define which languages you translate. Click on your avatar, then choose Settings, which will put you in the "Languages" tab:
![Weblate language settings](https://www.peppercarrot.com/data/documentation/medias/img/weblate-settings-language.png)
![Weblate language settings](https://peppercarrot.com/data/documentation/medias/img/weblate-settings-language.png)
The "Secondary languages" are also useful if you want those languages' translations to appear next to the English source strings while translating.
......@@ -148,7 +148,7 @@ Notification settings are important so that you will know when there are new str
Click on your avatar, then choose Settings → Notifications
![Weblate notification settings](https://www.peppercarrot.com/data/documentation/medias/img/weblate-settings-watching.png)
![Weblate notification settings](https://peppercarrot.com/data/documentation/medias/img/weblate-settings-watching.png)
You can also define special notification settings just for Pepper & Carrot if you want, from the project's main page (see screenshot below).
......@@ -156,9 +156,9 @@ You can also define special notification settings just for Pepper & Carrot if yo
### Translation Project Overview
The [Pepper&Carrot Weblate project](https://weblate.framasoft.org/projects/peppercarrot/) consists of 3 components:
The [Pepper&Carrot Weblate project](https://weblate.framasoft.org/projects/peppercarrot) consists of 3 components:
![Weblate project overview](https://www.peppercarrot.com/data/documentation/medias/img/weblate-overview-watching.png)
![Weblate project overview](https://peppercarrot.com/data/documentation/medias/img/weblate-overview-watching.png)
* **archive - DO NOT TRANSLATE**: Translations of the legacy website, so that you can search them. This is especially useful for the "Author" page, because we split a very long string into separate parts there.
* **Website**: The file to translate.
......@@ -170,7 +170,7 @@ The [Pepper&Carrot Weblate project](https://weblate.framasoft.org/projects/peppe
This what the main page of the Website file for your language will look like:
![Weblate language ovierview](https://www.peppercarrot.com/data/documentation/medias/img/weblate-language-overview.png)
![Weblate language overview](https://peppercarrot.com/data/documentation/medias/img/weblate-language-overview.png)
Note the translation checks - you can click on a check description to start fixing. Once the checks are clear, use the "Translate" button to translate.
......@@ -180,7 +180,7 @@ Note the translation checks - you can click on a check description to start fixi
While translating, there are different sections with information to help you get context.
![Weblate translation interface](https://www.peppercarrot.com/data/documentation/medias/img/weblate-item.png)
![Weblate translation interface](https://peppercarrot.com/data/documentation/medias/img/weblate-item.png)
* The "Translation" section is where you do your work. Note that this screenshot shows the French translation along with the English source strings in this screenshot, because I chose it as one of my "Secondary languages" (see [Define your Languages](#define-your-languages) above). You can see additional languages' translations in the "Other languages" tab below the "Translation" section.
* The "Things to Check" section shows any failing automated checks. Make sure to either fix your translation, or dismiss the check if you disagree with it.
......@@ -193,10 +193,10 @@ While translating, there are different sections with information to help you get
If you prefer to translate in your own tool (eg. because you prefer your own tool, or because your internet connection is limited), you can download and upload files in Weblate too.
1. Visit the [Website component](https://weblate.framasoft.org/projects/peppercarrot/website/)
1. Visit the [Website component](https://weblate.framasoft.org/projects/peppercarrot/website)
2. Click on your language
3. Choose "Customise download" from the "Files" menu
![Weblate offline translation](https://www.peppercarrot.com/data/documentation/medias/img/weblate-file-download.png)
![Weblate offline translation](https://peppercarrot.com/data/documentation/medias/img/weblate-file-download.png)
If your translation is incomplete, this page will also offer to only download the untranslated strings in order to save bandwidth. Note that it's better to use the complete file if you can though, because it will give you a bit more context for each translation via the surrounding strings.
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