From 439a9981cc08a6fe3d659671e17067c22185cee1 Mon Sep 17 00:00:00 2001 From: ansuz Date: Fri, 4 Nov 2016 14:10:32 +0100 Subject: [PATCH] add documentation for submitting a translation --- customize.dist/translations/README.md | 126 ++++++++++++++++++++++++++ readme.md | 15 +++ 2 files changed, 141 insertions(+) create mode 100644 customize.dist/translations/README.md diff --git a/customize.dist/translations/README.md b/customize.dist/translations/README.md new file mode 100644 index 000000000..36c43448e --- /dev/null +++ b/customize.dist/translations/README.md @@ -0,0 +1,126 @@ +# Adding 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. + +## Getting started + +Once everything is working, copy the default (English) source file (`/customize.dist/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 `/customize.dist/translations/messages.fr.js`. +There is no ISO 639-1 language code for _English-pirate_, so we'll just call it `messages.pirate.js`. + +```Bash +cd /customize.dist/translations/ +cp messages.js messages.pirate.js +``` + +## Including your translation + +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: + +```javascript +define(['/customize/languageSelector.js', + '/customize/translations/messages.js', + '/customize/translations/messages.es.js', + '/customize/translations/messages.fr.js', + + // 1) additional translation files can be added here... + + '/bower_components/jquery/dist/jquery.min.js'], + + // 2) name your language module here... + function(LS, Default, Spanish, French) { + var $ = window.jQuery; + + // 3) add your module to this map so it gets used + var map = { + 'fr': French, + 'es': Spanish, + }; +``` + +We need to modify these three places to include our file: + +```javascript +define(['/customize/languageSelector.js', + '/customize/translations/messages.js', + '/customize/translations/messages.es.js', + '/customize/translations/messages.fr.js', + + // 1) additional translation files can be added here... + '/customize/translations/messages.pirate.js', // add our module via its path + + '/bower_components/jquery/dist/jquery.min.js'], + + // 2) name your language module here... + function(LS, Default, Spanish, French, Pirate) { // name our module 'Pirate' for use as a variable + var $ = window.jQuery; + + // 3) add your module to this map so it gets used + var map = { + 'fr': French, + 'es': Spanish, + 'pirate': Pirate, // add our module to the map of languages + }; +``` + +Note that the path to the file is `/customize/translations/`, not `/customize.dist/translations`. +Cryptpad's server is configured to search for files in `/customize/` first. +If a file is not found, it falls back to `/customize.dist/`. +This allows administrators of a Cryptpad installation to override the default behaviour with their own files. + +We want translations to be the default behaviour, so we'll place it in `/customize.dist/translations/`, but resolve it via `/customize/translations/`. + +The second and third steps are simpler. +Just add your module in a similar fashion to the existing translations, save your changes, and close `/customize.dist/messages.js`. +That's all! + + +## Actually translating content + +Now we can go back to our file, `/customize.dist/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 = {}; + + // translations must set this key for their language to be available in + // the language dropdowns that are shown throughout Cryptpad's interface + out._languageName = 'English'; +``` + +Now you just need to work through this file, updating the strings like so: + +```javascript +define(function () { + var out = {}; + + // translations must set this key for their language to be available in + // the language dropdowns that are shown throughout Cryptpad's interface + out._languageName = 'Pirate'; +``` + +It's important that you modify just the string, and not the variable name which is used to access its content. +For instance, changing `_languageName` to `_language_name` would make the string `'Pirate'` inaccessible to the rest of the codebase. + +## 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/ to view Cryptpad's tests. +Among other things, 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. + diff --git a/readme.md b/readme.md index c80766ad0..e2dab9d9c 100644 --- a/readme.md +++ b/readme.md @@ -101,6 +101,21 @@ the battery out of your computer before it spawns Agent Smith. Still there are other low-lives in the world so using CryptPad over HTTPS is probably a good idea. +## Translations + +We'd like to make it easy for more people to use encryption in their routine activities. +As such, we've tried to make language-specific parts of Cryptpad translatable. If you're +able to translate Cryptpad's interface, and would like to help, please contact us! + +You can also see [our translation guide](/customize.dist/translations/README.md). + +## Contacting Us + +You can reach members of the Cryptpad development team on [twitter](https://twitter.com/cryptpad), +via our [github issue tracker](https://github.com/xwiki-labs/cryptpad/issues/), on the +[freenode](http://webchat.freenode.net/?channels=%23cryptpad&uio=MT1mYWxzZSY5PXRydWUmMTE9Mjg3JjE1PXRydWUe7) +irc network, or by [email](mailto:research@xwiki.com). + ## Contributing We love Open Source and we love contribution. It is our intent to keep this project available