From 1a4923ef6039a9b3edb65b1bd700811bc1063982 Mon Sep 17 00:00:00 2001 From: Marcel Klehr Date: Sun, 23 Dec 2012 17:55:38 +0100 Subject: [PATCH] Update docs --- README.md | 5 ++- doc/localization.md | 90 ++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 83 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 71ce8e77..754e67f7 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,9 @@ documented codebase makes it easier for developers to improve the code and contr Etherpad Lite is designed to be easily embeddable and provides a [HTTP API](https://github.com/ether/etherpad-lite/wiki/HTTP-API) -that allows your web application to manage pads, users and groups. It is recommended to use the client implementations available for this API, listed on [this wiki page](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries). -There is also a [jQuery plugin](https://github.com/johnyma22/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website +that allows your web application to manage pads, users and groups. It is recommended to use the [available client implementations]((https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) in order to interact with this API. There is also a [jQuery plugin](https://github.com/johnyma22/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website. +There's also a full-featured plugin framework, allowing you to easily add your own features. +Finally, Etherpad Lite comes with translations into tons of different languages! **Visit [beta.etherpad.org](http://beta.etherpad.org) to test it live** diff --git a/doc/localization.md b/doc/localization.md index 2bc133d5..b050acad 100644 --- a/doc/localization.md +++ b/doc/localization.md @@ -3,7 +3,7 @@ Etherpad lite provides a multi-language user interface, that's apart from your ## Translating -We rely on http://translatewiki.net to handle the translation process for us, so +We rely on http://translatewiki.net to handle the translation process for us, so if you'd like to help... 1. sign up at http://translatewiki.net 2. Visit our [TWN project page](https://translatewiki.net/wiki/Translating:Etherpad_lite) @@ -16,17 +16,87 @@ Translations will be send back to us regularly and will eventually appear in the ## Implementation ### Server-side -`/src/locales` contains files for all supported languages which contain the translated strings. Translation files are simply `*.ini` files and look like this: +`/src/locales` contains files for all supported languages which contain the translated strings. Translation files are simple `*.json` files and look like this: -``` -pad.modals.connected = Connecté. -pad.modals.uderdup = Ouvrir dans une nouvelle fenêtre. -pad.toolbar.unindent.title = Désindenter -pad.toolbar.undo.title = Annuler (Ctrl-Z) -timeslider.pageTitle = {{appTitle}} Curseur temporel +```json +{ "fr": +{ "pad.modals.connected": "Connecté." +, "pad.modals.uderdup": "Ouvrir dans une nouvelle fenêtre." +, "pad.toolbar.unindent.title": "Désindenter" +, "pad.toolbar.undo.title": "Annuler (Ctrl-Z)" +, "timeslider.pageTitle": "{{appTitle}} Curseur temporel" +, ... +} +} ``` -There must be only one translation per line. Each translation consists of a key (the id of the string that is to be translated), an equal sign and the translated string. Anything after the equa sign will be used as the translated string (you may put some spaces after `=` for better readability, though). Terms in curly braces must not be touched but left as they are, since they represent a dynamically changing part of the string like a variable. Imagine a message welcoming a user: `Welcome, {{userName}}!` would be translated as `Ahoy, {{userName}}!` in pirate. +Each translation consists of a key (the id of the string that is to be translated) and the translated string. Terms in curly braces must not be touched but left as they are, since they represent a dynamically changing part of the string like a variable. Imagine a message welcoming a user: `Welcome, {{userName}}!` would be translated as `Ahoy, {{userName}}!` in pirate. ### Client-side -We use a `language` cookie to save your language settings if you change them. If you don't, we autodetect your locale using information from your browser. Now, that we know your preferred language this information is feeded into a very nice library called [webL10n](https://github.com/fabi1cazenave/webL10n), which loads the appropriate translations and applies them to our templates, providing translation params, pluralization, include rules and even a nice javascript API along the way. \ No newline at end of file +We use a `language` cookie to save your language settings if you change them. If you don't, we autodetect your locale using information from your browser. Now, that we know your preferred language this information is feeded into a very nice library called [html10n.js](https://github.com/marcelklehr/html10n.js), which loads the appropriate translations and applies them to our templates, providing translation params, pluralization, include rules and even a nice javascript API along the way. + + + +## Localizing plugins + +### 1. Mark the strings to translate + +In the template files of your plugin, change all hardcoded messages/strings... + +from: +```html + +``` +to: +```html + +``` + +In the javascript files of your plugin, chaneg all hardcoded messages/strings... + +from: +```js +alert ('Chat'); +``` +to: +```js +alert(window._('pad.chat')); +``` +### 2. Create translate files in the locales directory of your plugin + +* The name of the file must be the language code of the language it contains translations for (see [supported lang codes](http://joker-x.github.com/languages4translatewiki/test/); e.g. en ? English, es ? Spanish...) +* The extension of the file must be `.json` +* The default language is English, so your plugin should always provide `en.json` +* In order to avoid naming conflicts, your message keys should start with the name of your plugin followed by a dot (see below) + +*ep_your-plugin/locales/en.json* +``` +{ "en": +{ "ep_your-plugin.h1": "Heading 1" +} +} +``` + +*ep_your-plugin/locales/es.json* +``` +{ "es": +{ "ep_your-plugin.h1": "Título 1" +} +} +``` + +Everytime the http server is started, it will auto-detect your messages and merge them automatically with the core messages. + +### Overwrite core messages + +You can overwrite Etherpad Lite's core messages in your plugin's locale files. +For example, if you want to replace `Chat` with `Notes`, simply add... + +*ep_your-plugin/locales/en.json* +``` +{ "en": +{ "ep_your-plugin.h1": "Heading 1" +, "pad.chat": "Notes" +} +} +``` \ No newline at end of file