Initial commit.

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+locale.*
+TODO.md

.npmignore

@@ -0,0 +1,4 @@
+.git*
+*.sublime*
+i18n.min.js
+TODO.md

LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2012 Dmitry A. Chleck <dmitrychleck@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,316 @@
+# Locale for Javascript
+
+# Features
+---
+* Multiple target languages (translate to)
+* Any base language (translate from)
+* Plural forms for any language
+* Simultaneous support of multiple languages
+* Flexible placeholders
+* Remote translation
+
+## It's simple
+---
+    // Translate
+    var who = 'world';
+    __('Hello, %s!', who);
+
+    // Translate plural
+    __([
+      'There is %n item in your cart (total $%s).',
+      'There are %n items in your cart (total $%s).'
+      ], cart.items.length, cart.total
+    );
+
+# Installation
+---
+
+Install node.js library:
+
+    npm install locale-js
+
+or download minified library [i18n.min.js](https://bitbucket.org/chleck/locale-js/raw/stable/i18n.min.js "Minified i18n.js") (for browser apps).
+
+# API
+---
+
+## Library import
+---
+
+### For node.js:
+
+    var locale = require('locale-js');
+
+### For browser:
+
+    <script type="text/javascript" src="i18n.min.js"></script>
+
+## Configuration
+---
+
+### Library initialization (browser):
+
+    locale.init(base, rule)
+
+, where:
+
+- *base* (string) - id of application's base language;
+- *rule* (string) - plural rule for base language.
+
+You should use locale.add() to add translation for each used language.
+
+### Library initialization (node.js):
+
+    locale.init(path)
+
+, where *path* is the path to the translation files.
+
+This function searches for and loads all translations automatically.
+
+### Example:
+
+    // In browser:
+    locale.init('ru', '(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)');
+    // You can skip parameters if your base language is English
+    locale.init();
+
+    // In node.js app:
+    locale.init('./i18n/');
+
+### Add translation:
+
+    locale.add(lang, translation)
+
+, where:
+
+- *lang* (string) - language id;
+- *translation* (object) - translation JSON.
+
+## Creating i18n object
+---
+
+### Create translation object for the given target:
+
+    new locale.i18n(target)
+
+, where *target* (string or null) - 1) id of the target language, 2) empty string or 3) null.
+
+Sets target language to base language if *target* is *''* (empty string).  
+Enables remote translation mode if *target* is *null*.  
+
+### Example:
+
+    // Create translation object for Russian language
+    var i18n = new locale.i18n('ru');
+    // Create translation object for base language (no translation)
+    var i18n = new locale.i18n('');
+    // Create translation object for remote translation
+    var i18n = new locale.i18n(null);
+    // And pull up __() function to the local scope
+    var __ = i18n.__;
+
+## Translation target
+---
+
+This methods are accessible for *locale* and *i18n* objects.
+
+### Get current target:
+
+    to()
+
+Returns (string or null) current translation target.
+
+### Set target:
+
+    to(target)
+
+, where *target* (string or null) - 1) id of target language, 2) empty string or 3) null.
+
+Sets target language to base language if *target* is *''* (empty string).  
+Switches i18n object to remote translation mode if *target* is *null*.  
+
+### Example:
+
+    // Set target language for library to German
+    locale.to('de');
+    // Create i18n object and set its target language to Russian
+    var i18n = new locale.i18n();
+    i18n.to('ru');
+    // Enable remote translation mode
+    i18n.to(null);
+
+## Translation
+---
+
+This methods are accessible for *locale* and *i18n* objects.
+
+### For simple form:
+
+    __(phrase)
+    __(phrase, ...)
+    __(phrase, array)
+    __(phrase, object)
+
+, where:
+
+- *phrase* (string) - string for translation (can contains placeholders);
+- *...* (mixed) - any number of additional args;
+- *array* (Array) - array of args;
+- *object* (object) - map of args.
+
+Returns translated string or remote translation data (in case of remote translation target).
+
+### For plural form:
+
+    __(phrase, n)
+    __(phrase, n, ...)
+    __(phrase, n, array)
+    __(phrase, n, object)
+
+, where:
+
+- *phrase* (array) - array of strings each of them is a plural form for translation (can contains placeholders);
+- *n* (numeric) - base number of plural form;
+- *...* (mixed) - any number of additional args;
+- *array* (Array) - array of args;
+- *object* (object) - map of args.
+
+Returns translated string or remote translation data (in case of remote translation target).
+
+### Example:
+
+    // Simple:
+
+    // Hello!
+    __('Hello!');
+    // Hello, anonymous!
+    __('Hello, %s!', 'anonymous');
+    // Hello, John Smith!
+    __('Hello, %s(2) %s(1)!', [ 'Smith', 'John' ]);
+    // Hello, Foo (bar)!
+    __('Hello, %s(name) (%s(login))!', { name: 'Foo', login: 'bar' });
+
+    // Plural:
+
+    // Inbox: 1 unreaded message.
+    __([ 'Inbox: %n unreaded message.', 'Inbox: %n unreaded messages.' ], 1);
+    // Inbox: 7 unreaded messages.
+    __([ '%s(1): %n unreaded message.', '%s(1): %n unreaded messages.' ], 7, 'Inbox');
+    // Anonymous, you have 365 unreaded messages in the "Spam" folder.
+    __([
+        '%s(1), you have %n unreaded message in the "%s(2)" folder.',
+        '%s(1), you have %n unreaded messages in the "%s(2)" folder.'
+       ], 365, [ 'Anonymous', 'Spam' ]);
+    // The second way
+    __([
+        '%s(login), you have %n unreaded message in the "%s(folder)" folder.',
+        '%s(login), you have %n unreaded messages in the "%s(folder)" folder.'
+       ], 365, { login: 'Anonymous', folder: 'Spam' });
+
+    // Remote:
+
+    // { __i18n: true, phrase: 'Hello!', n: undefined, args: {} }
+    __('Hello!');
+
+See also: Remote translation.
+
+## Strings format
+---
+
+### Phrase, id and comment
+
+Each string consists of *phrase*, *id* and *comment*.
+Both *id* and *comment* are optional, *id* separates from *phrase* by '#' sign, *comment* separates from *id* by space.
+
+    <phrase>[#<id>[ <comment>]]
+
+*phrase* + *id* is unique key for translation dictionary. You can create several variants of translation of the same *phrase* using different *id*s.
+
+Also you can place any useful info for translator to *comment*.
+
+### Example:
+
+    // No id, no comment
+    __('Hello!');
+    // Both id and comment
+    __('Hello!#another This is a comment for translator');
+    // Only id
+    __('Hello!#another');
+    // Only comment
+    __('Hello!# This is a comment for translator');
+
+### Placeholders
+
+Phrases can contains placeholders.
+
+Placeholder's format is:
+
+**%s** - fills with the next arg.  
+**%s(id)** - fills with the *id* arg (arg number *id* for additional args or arg[id] for array and map args).  
+**%n** - fills with base number of plural form (valid for plural form only).  
+
+### Example:
+
+See example of __() function.
+
+### Special characters
+
+Special characters are '#' and '%'. If you need it in your string you should type it twice.
+
+    // 40%
+    __('%s%%', 40);
+    // It's # not a comment!
+    __('It\'s ## not a comment!);
+
+Also you can use '(' character after placeholder. Type it twice too:
+
+    // Order by name(asc)
+    __('Order by %s((asc)', 'name');
+
+## Remote translation
+---
+
+### Search for remote translation data in the *obj* and replace it by translated string:
+
+    i18n.tr(obj)
+
+, where *obj* (object) - object for translation.
+
+### Remote translation data structure:
+
+    {
+      __i18n: true,
+      phrase: <phrase>,
+      n: <number>,
+      args: <arguments>
+    }
+
+See also: Creating i18n object.
+
+### Example:
+
+    // Server:
+
+    // Create i18n object for the remote mode
+    var i18n = new locale.i18n(null);
+    var __ = i18n.__();
+    submit({
+      id: 832367,
+      errno: 404,
+      error: __('Path not found!')
+    });
+
+    // Client:
+
+    var i18n = new locale.i18n('ru');
+    var msg = receive();
+    i18n.tr(msg);
+    /*
+
+      {
+        id: 832367,
+        errno: 404,
+        error: 'Путь не найден!'
+      }
+
+    */

example/i18n.json

@@ -0,0 +1,7 @@
+{
+  "base": "en",
+  "rule": "(n == 1 ? 0 : 1)",
+  "targets": [
+    "ru"
+  ]
+}