Merge branch 'soon' into staging
ansuz
6 years ago
commit
62ece7dfa0
@ -1,129 +1,29 @@
|
||||
# Adding Translations
|
||||
# Translations
|
||||
|
||||
To illustrate the process of translating, this guide will make an english-pirate translation of Cryptpad.
|
||||
We'll assume that you have a work locally-installed, properly functioning installation of Cryptpad.
|
||||
If you don't have Cryptpad installed locally, start by following the steps in the main readme.
|
||||
Translations can now be made using [Weblate](https://weblate.cryptpad.fr). We may still accept PRs for the internal translation files, but we won't provide support for this.
|
||||
|
||||
## Getting started
|
||||
## Request a new language
|
||||
|
||||
Once everything is working, copy the default (English) source file (`/www/common/translations/messages.js`) to a file named according to your language's [ISO 639-1 Code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), like `/www/common/translations/messages.fr.js`.
|
||||
There is no ISO 639-1 language code for _English-pirate_, so we'll just call it `messages.pirate.js`.
|
||||
* New languages require some minor changes in the code which we have to apply manually. If you want to translate CryptPad into a new language, please send us an email at weblate@cryptpad.fr
|
||||
* Please note that members of the current development team are only fluent in English and French, so additional languages will require ongoing contributions in order to stay up to date.
|
||||
* If a language becomes too outdated, we will consider dropping it from the available language until it is fixed.
|
||||
* Please refrain from asking for a new language if you are not able to provide a sufficiently translated version and maintain it or to find other users that can do so.
|
||||
|
||||
```Bash
|
||||
cd www/common/translations/
|
||||
cp messages.js messages.pirate.js
|
||||
```
|
||||
## Become a reviewer
|
||||
|
||||
## Including your translation
|
||||
* We need reviewers for all the languages except English and French. Their job will be to approve/reject/discuss the translations made by other contributors to this language, using the Weblate UI.
|
||||
* If you want to become a reviewer for a language, please write us an email at weblate@cryptpad.fr
|
||||
* Please tell us if you want to stop being a reviewer (even momentarily) so that we can find a replacement as soon as posible
|
||||
|
||||
To include your translation in the list, you'll need to add it to `/customize.dist/messages.js`.
|
||||
There are comments indicating what to modify in three places:
|
||||
## Translate an existing language
|
||||
|
||||
```javascript
|
||||
(function () {
|
||||
// add your module to this map so it gets used
|
||||
// please use the translated name of your language ("Français" and not "French")
|
||||
var map = {
|
||||
'fr': 'Français',
|
||||
'es': 'Español',
|
||||
'pl': 'Polski',
|
||||
'de': 'Deutsch',
|
||||
'pt-br': 'Português do Brasil',
|
||||
'ro': 'Română',
|
||||
'zh': '繁體中文',
|
||||
'el': 'Ελληνικά',
|
||||
};
|
||||
```
|
||||
* All translations can be done using the Weblate UI. For better help about how to use the tool, please check the [Weblate documentation](https://docs.weblate.org/en/latest/user/index.html).
|
||||
* Our Weblate instance is configured to always require approval for changes.
|
||||
|
||||
We need to modify that map to include our translation:
|
||||
### Update an existing translation
|
||||
|
||||
```javascript
|
||||
(function () {
|
||||
// add your module to this map so it gets used
|
||||
// please use the translated name of your language ("Français" and not "French")
|
||||
var map = {
|
||||
'fr': 'Français',
|
||||
'es': 'Español',
|
||||
'pl': 'Polski',
|
||||
'de': 'Deutsch',
|
||||
'pt-br': 'Português do Brasil',
|
||||
'ro': 'Română',
|
||||
'zh': '繁體中文',
|
||||
'el': 'Ελληνικά',
|
||||
'pirate': 'English Pirate', // add our module to the map of languages
|
||||
};
|
||||
```
|
||||
Just add your module in a similar fashion to the existing translations, save your changes, and close `/customize.dist/messages.js`.
|
||||
* Existing translations that have already been approved can't be changed directly. Users can only make suggestions, and the reviewers will have to approve the changes if they agree.
|
||||
|
||||
### Translate a new key
|
||||
|
||||
You also need to add a customizable version of you translation. To do so, make a copy of the file `/customize.dist/translations/messages.js` with your translation name (`messages.pirate.js` in our case), and change its content to load the correct language file:
|
||||
|
||||
```javascript
|
||||
/*
|
||||
* You can override the translation text using this file.
|
||||
* The recommended method is to make a copy of this file (/customize.dist/translations/messages.{LANG}.js)
|
||||
in a 'customize' directory (/customize/translations/messages.{LANG}.js).
|
||||
* If you want to check all the existing translation keys, you can open the internal language file
|
||||
but you should not change it directly (/common/translations/messages.{LANG}.js)
|
||||
*/
|
||||
define(['/common/translations/messages.pirate.js'], function (Messages) { // Change the file name here
|
||||
// Replace the existing keys (in your copied file) here:
|
||||
// Messages.button_newpad = "New Rich Text Document";
|
||||
return Messages;
|
||||
});
|
||||
```
|
||||
|
||||
That's all!
|
||||
|
||||
## Actually translating content
|
||||
|
||||
Now we can go back to our file, `/www/common/translations/messages.pirate.js` and start to add our Pirate-language customizations.
|
||||
|
||||
Open the translation file you created in `/customize.dist/translations/`.
|
||||
You should see something like:
|
||||
|
||||
```javascript
|
||||
define(function () {
|
||||
var out = {};
|
||||
|
||||
out.main_title = "Cryptpad: Zero Knowledge, Collaborative Real Time Editing";
|
||||
```
|
||||
|
||||
Now you just need to work through this file, updating the strings like so:
|
||||
|
||||
```javascript
|
||||
define(function () {
|
||||
var out = {};
|
||||
|
||||
out.main_title = "Cryptpad: Knowledge lost at sea while ye scribble with yer mateys";
|
||||
```
|
||||
|
||||
It's important that you modify just the string, and not the variable name which is used to access its content.
|
||||
For instance, changing `main_title` to `mainTitle` would make the translated string inaccessible to the rest of the codebase.
|
||||
|
||||
If a key is not found in your translation, the default English version of that key will be used.
|
||||
This is to make sure that buttons and other interface elements are not empty, but it's obviously not ideal.
|
||||
|
||||
## Verifying Your Translations
|
||||
|
||||
It's advisable to save your translation file frequently, and reload Cryptpad in your browser to check that there are no errors in your translation file.
|
||||
If there are any errors in your code, the file will fail to parse, and the page will no load correctly.
|
||||
|
||||
Checking frequently will make it easier to know which change caused the error.
|
||||
|
||||
Additionally, we advise using the apps and visiting the various pages, to make sure that your translations make sense in context.
|
||||
|
||||
When you're happy with your translation file, you can visit http://localhost:3000/assert/translations/ to view Cryptpad's tests.
|
||||
These tests will check to make sure that your translation has an entry for every entry in the default English translation.
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you have any issues, reach out via any of the methods listed in the readme under **Contacting Us**.
|
||||
We're happy to help.
|
||||
|
||||
## Deleting a translation
|
||||
When a key is nolonger used (such as presentSuccess) you can delete it using this bash one-liner.
|
||||
|
||||
```shell
|
||||
( export KEY=presentSuccess && grep -nr "$KEY" ./www/common/translations/ | sed 's/:.*$//' | while read x; do sed -i -e "/out\.$KEY =/d" $x; done )
|
||||
```
|
||||
* Untranslated strings can be changed by any user and the translation can be edited by others as long as it has not been approved by a reviewer.
|
||||
|
||||
Loading…
Reference in New Issue