Update docs

1 files changed, 80 insertions, 10 deletions

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
+<option value="0">Heading 1</option>
+```
+to:
+```html
+<option data-l10n-id="ep_heading.h1" value="0"></option>
+```
+
+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