README.md in i18n-js-3.0.0.rc5 vs README.md in i18n-js-3.0.0.rc6
- old
+ new
@@ -1,9 +1,12 @@
# I18n.js
-It's a small library to provide the Rails I18n translations on the Javascript.
+[](https://travis-ci.org/fnando/i18n-js)
+[](https://codeclimate.com/github/fnando/i18n-js)
+It's a small library to provide the Rails I18n translations on the JavaScript.
+
Features:
- Pluralization
- Date/Time localization
- Number localization
@@ -17,69 +20,132 @@
#### Rails app
Add the gem to your Gemfile.
- source :rubygems
+ source "https://rubygems.org"
gem "rails", "3.2.3"
gem "i18n-js"
+#### Rails app with [Asset Pipeline](http://guides.rubyonrails.org/asset_pipeline.html)
+
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`.
- //= require i18n/translations
+```javascript
+//= 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.
- <%= javascript_include_tag "i18n", "translations" %>
+```erb
+<%= javascript_include_tag "i18n", "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)!
config.middleware.use I18n::JS::Middleware
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.
- $ rails runner I18n::JS.export
+ $ rake i18n:js:export
This will export all translation files, including the custom scopes you may have
-defined on `config/i18n-js.yml`.
+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:
+- file: 'public/javascripts/path-to-your-messages-file.js'
+ only: '*.date.formats'
+- file: 'public/javascripts/path-to-your-second-file.js'
+ only: ['*.activerecord', '*.admin.*.title']
+```
+
+If `only` is omitted all the translations will be saved. Also, make sure you add that initial `*`; it specifies that all languages will be exported. If you want to export only one language, you can do something like this:
+```yaml
+translations:
+- file: 'public/javascripts/en.js'
+ only: 'en.*'
+- file: 'public/javascripts/pt-BR.js'
+ only: 'pt-BR.*'
+```
+
+Optionally, you can auto generate a translation file per available locale if you specify the `%{locale}` placeholder.
+```yaml
+translations:
+- file: "public/javascripts/i18n/%{locale}.js"
+ only: '*'
+- file: "public/javascripts/frontend/i18n/%{locale}.js"
+ only: ['frontend', 'users']
+```
+
+You can also include ERB in your config file.
+```yaml
+translations:
+<% Widgets.each do |widget| %>
+- file: <%= "'#{widget.file}'" %>
+ only: <%= "'#{widget.only}'" %>
+<% end %>
+```
+
+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
by hand or using your favorite programming language. More info below.
### Setting up
You **don't** need to set up a thing. The default settings will work just okay. But if you want to split translations into several files or specify specific contexts, you can follow the rest of this setting up section.
Set your locale is easy as
+```javascript
+I18n.defaultLocale = "pt-BR";
+I18n.locale = "pt-BR";
+I18n.currentLocale();
+// pt-BR
+```
- I18n.defaultLocale = "pt-BR";
- I18n.locale = "pt-BR";
- I18n.currentLocale();
- // pt-BR
+**NOTE:** You can now apply your configuration **before I18n** is loaded like this:
+```javascript
+I18n = {} // You must define this object in top namespace, which should be `window`
+I18n.defaultLocale = "pt-BR";
+I18n.locale = "pt-BR";
-**NOTE:** Just make sure you apply your configuration **after i18n.js** is loaded. Otherwise, your settings will be ignored.
+// Load I18n from `i18n.js`, `application.js` or whatever
+I18n.currentLocale();
+// pt-BR
+```
+
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>
You can use translate your messages:
I18n.t("some.scoped.translation");
- // or translate with explicite setting of locale
+ // 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"});
@@ -90,10 +156,25 @@
I18n.t("some.missing.scope", {defaultValue: "A default message"});
// 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"}]});
+
+ // As a simple translation
+ I18n.t("some.missing.scope", {defaults: [{message: "some.existing.scope"}]});
+
+ 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.
+
Translation fallback can be enabled by enabling the `I18n.fallbacks` option:
<script type="text/javascript">
I18n.fallbacks = true;
</script>
@@ -112,11 +193,11 @@
I18n.locales.no = ["nb", "en"];
I18n.locales.no = "nb";
I18n.locales.no = function(locale){ return ["nb"]; };
-Pluralization is possible as well and by default provides english rules:
+Pluralization is possible as well and by default provides English rules:
I18n.t("inbox.counting", {count: 10}); // You have 10 messages
The sample above expects the following translation:
@@ -125,11 +206,11 @@
counting:
one: You have 1 new message
other: You have {{count}} new messages
zero: You have no messages
-**NOTE:** Rais I18n recognizes the `zero` option.
+**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";
@@ -230,11 +311,10 @@
%a - The abbreviated weekday name (Sun)
%A - The full weekday name (Sunday)
%b - The abbreviated month name (Jan)
%B - The full month name (January)
- %c - The preferred local date and time representation
%d - Day of the month (01..31)
%-d - Day of the month (1..31)
%H - Hour of the day, 24-hour clock (00..23)
%-H - Hour of the day, 24-hour clock (0..23)
%I - Hour of the day, 12-hour clock (01..12)
@@ -254,11 +334,11 @@
Check out `spec/*.spec.js` files for more examples!
## Using I18n.js with other languages (Python, PHP, ...)
-The JavaScript library is language agnostic; so you can use it with PHP, Python, [you favorite language here].
+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 = {};
I18n.translations["en"] = {
@@ -276,13 +356,14 @@
## Contributing
Once you've made your great commits:
1. [Fork](http://help.github.com/forking/) I18n.js
-2. Create a topic branch - `git checkout -b my_branch`
-3. Push to your branch - `git push origin my_branch`
-4. [Create an Issue](http://github.com/fnando/i18n-js/issues) with a link to your branch
-5. That's it!
+2. Create a branch with a clear name
+3. Make your changes (Please also add/change spec, README and CHANGELOG if applicable)
+4. Push changes to the created branch
+5. [Create an Pull Request](http://github.com/fnando/i18n-js/pulls)
+6. That's it!
Please respect the indentation rules and code style.
And use 2 spaces, not tabs. And don't touch the versioning thing.
## Running tests