README.md in i18n-js-3.0.0.rc6 vs README.md in i18n-js-3.0.0.rc7
- old
+ new
@@ -30,42 +30,47 @@
If you're using the [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html),
then you must add the following line to your `app/assets/javascripts/application.js`.
```javascript
+//
+// This is optional (in case you have `I18n is not defined` error)
+// If you want to put this line, you must put it BEFORE `i18n/translations`
+//= require i18n
+//
+// This is a must
//= require i18n/translations
```
#### Rails app without [Asset Pipeline](http://guides.rubyonrails.org/asset_pipeline.html)
-If you're not using the asset pipeline, download the JavaScript file at
-<https://github.com/fnando/i18n-js/tree/master/lib/i18n.js> and load it on your page.
-Also load the `translations.js` file.
+First, put this in your `application.html` (layout file).
+Then get the JS files following the instructions below.
```erb
-<%= javascript_include_tag "i18n", "translations" %>
+<%# This is just an example, you can put `i18n.js` and `translations.js` anywhere you like %>
+<%# Unlike the Asset Pipeline example, you need to require both **in order** %>
+<%= javascript_include_tag "i18n" %>
+<%= javascript_include_tag "translations" %>
```
-This `translations.js` file can be automatically generated by the `I18n::JS::Middleware`.
-Just add it to your `config/application.rb` file.
-Don't add this middleware if you are using [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html)!
+**There are two ways to get `translations.js`.**
- config.middleware.use I18n::JS::Middleware
+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
+ you may have defined on `config/i18n-js.yml`.
+ 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.
-If you can't generate this file in production (Heroku anyone?), you can "precompile"
-it by running the following command. Move the middleware line to your
-`config/environments/development.rb` file and run the following command before
-deploying.
+#### Export Configuration (For translations)
- $ rake i18n:js:export
-
-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) then only the specified locales will be exported.
-
-#### Export Configuration
-
Exported translation files generated by `I18n::JS::Middleware` or `rake i18n:js:export` can be customized with config file `config/i18n-js.yml` (use `rails generate i18n:js:config` to create it). You can even get more files generated to different folders and with different translations to best suit your needs. But this does not affect anything if you use Asset Pipeline.
Examples:
```yaml
translations:
@@ -100,10 +105,22 @@
- file: <%= "'#{widget.file}'" %>
only: <%= "'#{widget.only}'" %>
<% end %>
```
+#### Export Configuration (For other things)
+- `I18n::JS.config_file_path`
+ Expected Type: `String`
+ Default: `config/i18n-js.yml`
+ Behaviour: Try to read the config file from that location
+- `I18n::JS.export_i18n_js_dir_path`
+ Expected Type: `String`
+ Default: `public/javascripts`
+ Behaviour:
+ - Any `String`: considered as a relative path for a folder to `Rails.root` and export `i18n.js` to that folder for `rake i18n:js:export`
+ - `nil`: Disable `i18n.js` exporting
+
To find more examples on how to use the configuration file please refer to the tests.
#### Vanilla JavaScript
Just add the `i18n.js` file to your page. You'll have to build the translations object
@@ -211,11 +228,12 @@
**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) {
- return 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";
+ 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.
@@ -346,9 +364,35 @@
}
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
+
+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`
+
+**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.
+
+Please see issue #213 for detail & related discussion.
+
## Maintainer
- Nando Vieira - <http://nandovieira.com.br>