i18n-js 3.0.0.rc11 → 3.0.0.rc12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a4b7236b1fa082ab83114e4015b4a4ba230c1f5
-  data.tar.gz: 8e55ab185ee081ea88b5452d1caedfc0f4feb44b
+  metadata.gz: 38feae5eaf2de86fcedd5ebaa0eaf008a1a33f8d
+  data.tar.gz: fe63577ccdbce4f49d6f998f68fad0d58791eaf4
 SHA512:
-  metadata.gz: 0127486af42b8210f21513c91eadaf1481f639be02cb4197335619e11609d877c9ab7ce8f372818127c9dc04744e9251e2aef21a5d38ac82276b5dfb87684631
-  data.tar.gz: 9b3bd3240f25b722eb8e00332cbafc72b01f872c5ffb2e5f2236736ec4ff32026e5f317ef5dff20c30cafd8bd17f4b4a21a0e4577a7eba9cf95804e4e23c524a
+  metadata.gz: 00405a7c557557f13effc0088a9f13c56fe1fd9105d2cfd87951e8b9df1f55089f4610206a39dce7fed0b2d1780da36b1819f0fa4aed8c24d21875e538044cd2
+  data.tar.gz: 76240818ad36435dd3dfdf99324bb336c9832de408bd0c02104e5255e399d241f941a7d65bf903f2e505b1b311b39611fb34504884ebf0eeb14ba0caf35609d9

data/Appraisals

@@ -1,8 +1,8 @@
 
 appraise "i18n_0_6" do
-  gem 'i18n', '0.6.11'
+  gem "i18n", "~> 0.6.0", ">= 0.6.6"
 end
 
 appraise "i18n_0_7" do
-  gem 'i18n', '0.7.0'
+  gem "i18n", "~> 0.7.0"
 end

data/CHANGELOG.md

@@ -1,12 +1,39 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
 
-## Unreleased
+## [Unreleased]
 
-### breaking changes
+### Added
 
-### enhancements
+- Nothing
 
-### bug fixes
+### Changed
+
+- Nothing
+
+### Fixed
+
+- Nothing
+
+
+## [3.0.0.rc12] - 2015-12-30
 
+### Added
+
+- [JS] Allow extending of translation files ([#354](https://github.com/fnando/i18n-js/pull/354))
+- [JS] Allow missingPlaceholder to receive extra data for debugging ([#380](https://github.com/fnando/i18n-js/pull/380))
+
+### Changed
+
+- Nothing
+
+### Fixed
+
+- [Ruby] Fix of missing initializer at sprockets. ([#371](https://github.com/fnando/i18n-js/pull/371))
+- [Ruby] Use proper method to register preprocessor documented by sprockets-rails. ([#376](https://github.com/fnando/i18n-js/pull/376))
+- [JS] Correctly round unprecise floating point numbers.
+- [JS] Ensure objects are recognized when passed in from an iframe. ([#375](https://github.com/fnando/i18n-js/pull/375))
 
 
 ## 3.0.0.rc11
@@ -128,3 +155,8 @@
 ## Before 3.0.0.rc5
 
 - Things happened.
+
+
+
+[Unreleased]: https://github.com/fnando/i18n-js/compare/v3.0.0.rc12...HEAD
+[3.0.0.rc12]: https://github.com/fnando/i18n-js/compare/v3.0.0.rc11...v3.0.0.rc12

data/README.md

@@ -22,12 +22,13 @@ Features:
 #### Rails app
 
 Add the gem to your Gemfile.
-
-    source "https://rubygems.org"
-    gem "rails", "your_rails_version"
-    # You only need this RC version constraint during the development of `3.0.0`, once stable version is released you can remove `rc8` suffix
-    # `3.0.0.rc8` is the latest version of released RC version when this entry is changed, you might want to change it later
-    gem "i18n-js", ">= 3.0.0.rc8" 
+```ruby
+source "https://rubygems.org"
+gem "rails", "your_rails_version"
+# You only need this RC version constraint during the development of `3.0.0`, once stable version is released you can remove `rc11` suffix
+# `3.0.0.rc11` is the latest version of released RC version when this entry is changed, you might want to change it later
+gem "i18n-js", ">= 3.0.0.rc11"
+```
 
 #### Rails app with [Asset Pipeline](http://guides.rubyonrails.org/asset_pipeline.html)
 
@@ -62,13 +63,12 @@ Then get the JS files following the instructions below.
 
 1. This `translations.js` file can be automatically generated by the `I18n::JS::Middleware`.  
   Just add `config.middleware.use I18n::JS::Middleware` to your `config/application.rb` file.  
-  Notice: Don't add this middleware if you are using [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html)!
 2. If you can't or prefer not to generate this file,
   you can move the middleware line to your `config/environments/development.rb` file
   and run `rake i18n:js:export` before deploying.
-  This will export all translation files, including the custom scopes 
+  This will export all translation files, including the custom scopes
   you may have defined on `config/i18n-js.yml`.  
-  If `I18n.available_locales` is set (e.g. in your Rails `config/application.rb` file) 
+  If `I18n.available_locales` is set (e.g. in your Rails `config/application.rb` file)
   then only the specified locales will be exported.  
   Current version of `i18n.js` will also be exported to avoid version mismatching by downloading.
 
@@ -151,7 +151,7 @@ translations:
 - You may also set `export_i18n_js` and `sort_translation_keys` in your config file, e.g.:
 
 ```yaml
-export_i18n_js_: false
+export_i18n_js: false
 # OR
 export_i18n_js: "my/path"
 
@@ -296,65 +296,79 @@ I18n.currentLocale();
 
 In practice, you'll have something like the following in your `application.html.erb`:
 
-    <script type="text/javascript">
-      I18n.defaultLocale = "<%= I18n.default_locale %>";
-      I18n.locale = "<%= I18n.locale %>";
-    </script>
+```erb
+<script type="text/javascript">
+  I18n.defaultLocale = "<%= I18n.default_locale %>";
+  I18n.locale = "<%= I18n.locale %>";
+</script>
+```
 
 You can use translate your messages:
 
-    I18n.t("some.scoped.translation");
-    // or translate with explicit setting of locale
-    I18n.t("some.scoped.translation", {locale: "fr"});
+```javascript
+I18n.t("some.scoped.translation");
+// or translate with explicit setting of locale
+I18n.t("some.scoped.translation", {locale: "fr"});
+```
 
 You can also interpolate values:
 
-    I18n.t("hello", {name: "John Doe"});
-
+```javascript
+I18n.t("hello", {name: "John Doe"});
+```
 You can set default values for missing scopes:
+```javascript
+// simple translation
+I18n.t("some.missing.scope", {defaultValue: "A default message"});
 
-    // simple translation
-    I18n.t("some.missing.scope", {defaultValue: "A default message"});
-
-    // with interpolation
-    I18n.t("noun", {defaultValue: "I'm a {{noun}}", noun: "Mac"});
+// with interpolation
+I18n.t("noun", {defaultValue: "I'm a {{noun}}", noun: "Mac"});
+```
 
 You can also provide a list of default fallbacks for missing scopes:
 
-    // As a scope
-    I18n.t("some.missing.scope", {defaults: [{scope: "some.existing.scope"}]});
+```javascript
+// As a scope
+I18n.t("some.missing.scope", {defaults: [{scope: "some.existing.scope"}]});
 
-    // As a simple translation
-    I18n.t("some.missing.scope", {defaults: [{message: "Some message"}]});
+// As a simple translation
+I18n.t("some.missing.scope", {defaults: [{message: "Some message"}]});
+```
 
-    Default values must be provided as an array of hashs where the key is the
-    type of translation desired, a `scope` or a `message`. The translation returned
-    will be either the first scope recognized, or the first message defined.
+Default values must be provided as an array of hashs where the key is the
+type of translation desired, a `scope` or a `message`. The translation returned
+will be either the first scope recognized, or the first message defined.
 
-    The translation will fallback to the `defaultValue` translation if no scope
-    in `defaults` matches and if no default of type `message` is found.
+The translation will fallback to the `defaultValue` translation if no scope
+in `defaults` matches and if no default of type `message` is found.
 
 Translation fallback can be enabled by enabling the `I18n.fallbacks` option:
 
-    <script type="text/javascript">
-      I18n.fallbacks = true;
-    </script>
+```erb
+<script type="text/javascript">
+  I18n.fallbacks = true;
+</script>
+```
 
 By default missing translations will first be looked for in less
 specific versions of the requested locale and if that fails by taking
 them from your `I18n.defaultLocale`.
 
-    // if I18n.defaultLocale = "en" and translation doesn't exist
-    // for I18n.locale = "de-DE" this key will be taken from "de" locale scope
-    // or, if that also doesn't exist, from "en" locale scope
-    I18n.t("some.missing.scope");
+```javascript
+// if I18n.defaultLocale = "en" and translation doesn't exist
+// for I18n.locale = "de-DE" this key will be taken from "de" locale scope
+// or, if that also doesn't exist, from "en" locale scope
+I18n.t("some.missing.scope");
+```
 
 Custom fallback rules can also be specified for a particular language. There
 are three different ways of doing it so:
 
-    I18n.locales.no = ["nb", "en"];
-    I18n.locales.no = "nb";
-    I18n.locales.no = function(locale){ return ["nb"]; };
+```javascript
+I18n.locales.no = ["nb", "en"];
+I18n.locales.no = "nb";
+I18n.locales.no = function(locale){ return ["nb"]; };
+```
 
 By default a missing translation will be displayed as
 
@@ -363,7 +377,9 @@ By default a missing translation will be displayed as
 While you are developing or if you do not want to provide a translation
 in the default language you can set
 
-    I18n.missingBehaviour='guess';
+```javascript
+I18n.missingBehaviour='guess';
+```
 
 this will take the last section of your scope and guess the intended value.
 Camel case becomes lower cased text and underscores are replaced with space
@@ -392,61 +408,75 @@ I18n.missingTranslation = function () { return undefined; };
 
 Pluralization is possible as well and by default provides English rules:
 
-    I18n.t("inbox.counting", {count: 10}); // You have 10 messages
+```javascript
+I18n.t("inbox.counting", {count: 10}); // You have 10 messages
+```
 
 The sample above expects the following translation:
 
-    en:
-      inbox:
-        counting:
-          one: You have 1 new message
-          other: You have {{count}} new messages
-          zero: You have no messages
+```yaml
+en:
+  inbox:
+    counting:
+      one: You have 1 new message
+      other: You have {{count}} new messages
+      zero: You have no messages
+```
 
 **NOTE:** Rails I18n recognizes the `zero` option.
 
 If you need special rules just define them for your language, for example Russian, just add a new pluralizer:
 
-    I18n.pluralization["ru"] = function (count) {
-      var key = count % 10 == 1 && count % 100 != 11 ? "one" : [2, 3, 4].indexOf(count % 10) >= 0 && [12, 13, 14].indexOf(count % 100) < 0 ? "few" : count % 10 == 0 || [5, 6, 7, 8, 9].indexOf(count % 10) >= 0 || [11, 12, 13, 14].indexOf(count % 100) >= 0 ? "many" : "other";
-      return [key];
-    };
+```javascript
+I18n.pluralization["ru"] = function (count) {
+  var key = count % 10 == 1 && count % 100 != 11 ? "one" : [2, 3, 4].indexOf(count % 10) >= 0 && [12, 13, 14].indexOf(count % 100) < 0 ? "few" : count % 10 == 0 || [5, 6, 7, 8, 9].indexOf(count % 10) >= 0 || [11, 12, 13, 14].indexOf(count % 100) >= 0 ? "many" : "other";
+  return [key];
+};
+```
 
 You can find all rules on <http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html>.
 
 If you're using the same scope over and over again, you may use the `scope` option.
 
-    var options = {scope: "activerecord.attributes.user"};
+```javascript
+var options = {scope: "activerecord.attributes.user"};
 
-    I18n.t("name", options);
-    I18n.t("email", options);
-    I18n.t("username", options);
+I18n.t("name", options);
+I18n.t("email", options);
+I18n.t("username", options);
+```
 
 You can also provide an array as scope.
 
-    // use the greetings.hello scope
-    I18n.t(["greetings", "hello"]);
+```javascript
+// use the greetings.hello scope
+I18n.t(["greetings", "hello"]);
+```
 
 #### Number formatting
 
 Similar to Rails helpers, you have localized number and currency formatting.
 
-    I18n.l("currency", 1990.99);
-    // $1,990.99
+```javascript
+I18n.l("currency", 1990.99);
+// $1,990.99
 
-    I18n.l("number", 1990.99);
-    // 1,990.99
+I18n.l("number", 1990.99);
+// 1,990.99
 
-    I18n.l("percentage", 123.45);
-    // 123.450%
+I18n.l("percentage", 123.45);
+// 123.450%
+```
 
 To have more control over number formatting, you can use the
 `I18n.toNumber`, `I18n.toPercentage`, `I18n.toCurrency` and `I18n.toHumanSize`
 functions.
 
-    I18n.toNumber(1000);     // 1,000.000
-    I18n.toCurrency(1000);   // $1,000.00
-    I18n.toPercentage(100);  // 100.000%
+```javascript
+I18n.toNumber(1000);     // 1,000.000
+I18n.toCurrency(1000);   // $1,000.00
+I18n.toPercentage(100);  // 100.000%
+```
 
 The `toNumber` and `toPercentage` functions accept the following options:
 
@@ -457,9 +487,11 @@ The `toNumber` and `toPercentage` functions accept the following options:
 
 See some number formatting examples:
 
-    I18n.toNumber(1000, {precision: 0});                   // 1,000
-    I18n.toNumber(1000, {delimiter: ".", separator: ","}); // 1.000,000
-    I18n.toNumber(1000, {delimiter: ".", precision: 0});   // 1.000
+```javascript
+I18n.toNumber(1000, {precision: 0});                   // 1,000
+I18n.toNumber(1000, {delimiter: ".", separator: ","}); // 1.000,000
+I18n.toNumber(1000, {delimiter: ".", precision: 0});   // 1.000
+```
 
 The `toCurrency` function accepts the following options:
 
@@ -473,7 +505,9 @@ The `toCurrency` function accepts the following options:
 
 You can provide only the options you want to override:
 
-    I18n.toCurrency(1000, {precision: 0}); // $1,000
+```javascript
+I18n.toCurrency(1000, {precision: 0}); // $1,000
+```
 
 The `toHumanSize` function accepts the following options:
 
@@ -485,35 +519,44 @@ The `toHumanSize` function accepts the following options:
 
 <!---->
 
-    I18n.toHumanSize(1234); // 1KB
-    I18n.toHumanSize(1234 * 1024); // 1MB
+```javascript
+I18n.toHumanSize(1234); // 1KB
+I18n.toHumanSize(1234 * 1024); // 1MB
+```
+
 
 #### Date formatting
 
-    // accepted formats
-    I18n.l("date.formats.short", "2009-09-18");           // yyyy-mm-dd
-    I18n.l("time.formats.short", "2009-09-18 23:12:43");  // yyyy-mm-dd hh:mm:ss
-    I18n.l("time.formats.short", "2009-11-09T18:10:34");  // JSON format with local Timezone (part of ISO-8601)
-    I18n.l("time.formats.short", "2009-11-09T18:10:34Z"); // JSON format in UTC (part of ISO-8601)
-    I18n.l("date.formats.short", 1251862029000);          // Epoch time
-    I18n.l("date.formats.short", "09/18/2009");           // mm/dd/yyyy
-    I18n.l("date.formats.short", (new Date()));           // Date object
+```javascript
+// accepted formats
+I18n.l("date.formats.short", "2009-09-18");           // yyyy-mm-dd
+I18n.l("time.formats.short", "2009-09-18 23:12:43");  // yyyy-mm-dd hh:mm:ss
+I18n.l("time.formats.short", "2009-11-09T18:10:34");  // JSON format with local Timezone (part of ISO-8601)
+I18n.l("time.formats.short", "2009-11-09T18:10:34Z"); // JSON format in UTC (part of ISO-8601)
+I18n.l("date.formats.short", 1251862029000);          // Epoch time
+I18n.l("date.formats.short", "09/18/2009");           // mm/dd/yyyy
+I18n.l("date.formats.short", (new Date()));           // Date object
+```
 
 You can also add placeholders to the date format:
 
-    I18n.translations["en"] = {
-      date: {
-        formats: {
-          ordinal_day: "%B %{day}"
-        }
-      }
+```javascript
+I18n.translations["en"] = {
+  date: {
+    formats: {
+      ordinal_day: "%B %{day}"
     }
-    I18n.l("date.formats.ordinal_day", "2009-09-18", { day: '18th' }); // Sep 18th
+  }
+}
+I18n.l("date.formats.ordinal_day", "2009-09-18", { day: '18th' }); // Sep 18th
+```
 
 If you prefer, you can use the `I18n.strftime` function to format dates.
 
-    var date = new Date();
-    I18n.strftime(date, "%d/%m/%Y");
+```javascript
+var date = new Date();
+I18n.strftime(date, "%d/%m/%Y");
+```
 
 The accepted formats are:
 
@@ -542,46 +585,176 @@ The accepted formats are:
 
 Check out `spec/*.spec.js` files for more examples!
 
+## Using multiple exported translation files on a page.
+This method is useful for very large apps where a single contained translations.js file is not desirable. Examples would be a global translations file and a more specific route translation file.
+
+### Rails without asset pipeline
+1. Setup your `config/i18n-js.yml` to have multiple files and try to minimize any overlap.
+
+  ```yaml
+  sort_translation_keys: true
+  fallbacks: false
+
+  translations:
+    + file: "app/assets/javascript/nls/welcome.js"
+      only:
+        + '*.welcome.*'
+    
+    + file: "app/assets/javascript/nls/albums.js"
+      only:
+        + '*.albums.*'
+
+    + file: "app/assets/javascript/nls/global.js"
+      only:
+        + '*'
+      # Exempt any routes specific translations from being
+      # included in the global translation file
+      except:
+        + '*.welcome.*'
+        + '*.albums.*'
+  ```
+  When `rake i18n:js:export` is executed it will create 3 translations files that can be loaded via the `javascript_include_tag`
+
+2. Add the `javascript_include_tag` to your layout and to any route specific files that will require it.
+  ```ruby
+    # views/layouts/application.html.erb
+    <%= javascript_include_tag(
+          "i18n"
+          "nls/global"
+        ) %>
+  ```
+  and in the route specific
+
+  ```ruby
+    # views/welcome/index.html.erb
+    <%= javascript_include_tag(
+          "nls/welcome"
+        ) %>
+  ```
+
+3. Make sure that you add these files to your `config/application.rb`
+
+  ```ruby
+    config.assets.precompile += %w(
+      i18n
+      nls/*
+    )
+  ```
+
+### Using require.js / r.js
+
+To use this with require.js we are only going to change a few things from above.
+
+1. In your `config/i18n-js.yml` we need to add a better location for the i18n to be exported. You want to use this location so that it can be properly precompiled by r.js.
+
+  ```yaml
+  export_i18n_js: "app/assets/javascript/nls"
+  ```
+
+2. In your `config/require.yml` we need to add a map, shim all the translations, and include them into the appropriate modules
+
+  ```yaml
+  # In your maps add (if you do not have this you will need to add it)
+  map:
+    '*':
+      i18n: 'nls/i18n'
+
+  # In your shims
+  shims:
+    nls/welcome:
+      deps:
+        + i18n
+
+    nls/global:
+      deps:
+        + i18n
+
+  # Finally in your modules 
+  modules:
+    + name: 'application'
+      include:
+        + i18n
+        + 'nls/global'
+    
+    + name: 'welcome'
+      exclude:
+        + application
+      include:
+        + 'nls/welcome'
+  ```
+3. When `rake assets:precompile` is executed it will optimize the translations into the correct modules so they are loaded with their assigned module, and loading them with requirejs is as simple as requiring any other shim.
+
+  ```javascript
+  define(['welcome/other_asset','nls/welcome'], function (otherAsset){
+      // ...
+  });
+  ```
+4. (optional) As an additional configuration we can make a task to be run before the requirejs optimizer. This will allow any automated scripts that run the requirejs optimizer to export the strings before we run r.js
+
+  ```rake
+  # lib/tasks/i18n.rake
+  Rake::Task[:'i18n:js:export'].prerequisites.clear
+  task :'i18n:js:export' => :'i18n:js:before_export'
+  task :'requirejs:precompile:external' => :'i18n:js:export'
+
+  namespace :i18n do
+    namespace :js do
+      task :before_export => :'assets:environment' do
+        I18n.load_path += Dir[Rails.root.join('config', 'locales', '*.{yml,rb}')]
+        I18n.backend.load_translations
+      end
+    end
+  end
+  ```
+
 ## Using I18n.js with other languages (Python, PHP, ...)
 
 The JavaScript library is language agnostic; so you can use it with PHP, Python, [your favorite language here].
 The only requirement is that you need to set the `translations` attribute like following:
 
-    I18n.translations = {};
+```javascript
+I18n.translations = {};
 
-    I18n.translations["en"] = {
-      message: "Some special message for you"
-    }
+I18n.translations["en"] = {
+  message: "Some special message for you"
+}
 
-    I18n.translations["pt-BR"] = {
-      message: "Uma mensagem especial para você"
-    }
+I18n.translations["pt-BR"] = {
+  message: "Uma mensagem especial para você"
+}
+```
 
 ## Known Issues
 
 ### Missing translations in precompiled file(s) after adding any new locale file
 
 Due to the design of `sprockets`:
+
 - `depend_on` only takes file paths, not directory paths
-- registered `preprocessors` are only run when fingerprint of any asset file, including `.erb` files, is changed
+- registered `preprocessors` are only run when the fingerprint of any asset file, including `.erb` files, is changed
 
-New locale files won't be picked up unless any existing locale file content is changed.  
-You can workaround it manually by running
-```bash
-$ rake assets:clobber
-```
-to clear the asset cache.  
-**Or**  
-Change something in existing locale file.  
-**Or**  
-Change `config.assets.version`  
+This means that new locale files will not be detected, and so they will not trigger a i18n-js refresh. There are a few approaches to work around this:
+
+1. You can force i18n-js to update its translations by completely clearing the assets cache. Use one of the following:
+
+  ```bash
+  $ rake assets:clobber
+  # Or, with older versions of Rails:
+  $ rake tmp:cache:clear
+  ```
+
+    These commands will remove *all* fingerprinted assets, and you will have to recompile them with
 
-**Note:** `rake assets:clobber` will also remove all fingerprinted assets.  
-If you are precompiling assets on target machine(s),
-old assets might be removed and cannot be served in cached pages.
+    ```
+    $ rake assets:precompile
+    ```
+    or similar commands.  If you are precompiling assets on the target machine(s), cached pages may be broken by this, so they will need to be refreshed.
+    
+2. You can change something in a different locale file.
 
-Please see issue #213 for detail & related discussion.
+3. Finally, you can change `config.assets.version`.
 
+**Note:** See issue [#213](https://github.com/fnando/i18n-js/issues/213) for more details and discussion of this issue.
 
 ## Maintainer