Now Particularly Misnamed

    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/i18n-js package

    3.9.2 • Public • Published


    It's a small library to provide the Rails I18n translations on the JavaScript.

    Tests Gem Version npm License: MIT Coverage Status Gitter


    • Pluralization
    • Date/Time localization
    • Number localization
    • Locale fallback
    • Asset pipeline support
    • Lots more! :)

    Version Notice

    The main branch (including this README) is for latest 3.0.0 instead of 2.x.



    Rails app

    Add the gem to your Gemfile.

    gem "i18n-js"

    Rails with webpacker

    If you're using webpacker, you may need to add the dependencies to your client with:

    yarn add i18n-js
    # or, if you're using npm,
    npm install i18n-js

    For more details, see:

    Rails app with Asset Pipeline

    If you're using the asset pipeline, then you must add the following line to your app/assets/javascripts/application.js.

    // 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
    // Some people even need to add the extension to make it work, see
    //= require i18n.js
    // This is a must
    //= require i18n/translations

    Rails app without Asset Pipeline

    First, put this in your application.html (layout file). Then get the JS files following the instructions below.

    <%# 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", skip_pipeline: true %>

    There are two ways to get translations.js (For Rails app without Asset Pipeline).

    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.
    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.

    Export Configuration (For translations)

    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. The config file also affects developers using Asset Pipeline to require translations. Except the option file, since all translations are required by adding //= require i18n/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:

      - 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.

      - 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.

    <% Widgets.each do |widget| %>
    - file: <%= "'#{widget.file}'" %>
      only: <%= "'#{widget.only}'" %>
    <% end %>

    You are able to exclude certain phrases or whole groups of phrases by specifying the YAML key(s) in the except configuration option. The outputted JS translations file (exported or generated by the middleware) will omit any keys listed in except configuration param:

      - except: ["*.active_admin", "*.ransack", "*.activerecord.errors"]

    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
      • Any non-String (nil, false, :none, etc): Disable i18n.js exporting
    • I18n::JS.sort_translation_keys Expected Type: Boolean Default: true Behaviour:

      • Sets whether or not to deep sort all translation keys in order to generate identical output for the same translations
      • Set to true to ensure identical asset fingerprints for the asset pipeline
    • You may also set export_i18n_js and sort_translation_keys in your config file, e.g.:

    export_i18n_js: false
    # OR
    export_i18n_js: "my/path"
    sort_translation_keys: false
      - ...

    To find more examples on how to use the configuration file please refer to the tests.


    If you specify the fallbacks option, you will be able to fill missing translations with those inside fallback locale(s). Default value is true.


    fallbacks: true
      - file: "public/javascripts/i18n/%{locale}.js"
        only: "*"

    This will enable merging fallbacks into each file. (set to false to disable). If you use I18n with fallbacks, the fallbacks defined there will be used. Otherwise I18n.default_locale will be used.

    fallbacks: :de
      - file: "public/javascripts/i18n/%{locale}.js"
        only: "*"

    Here, the specified locale :de will be used as fallback for all locales.

      fr: ["de", "en"]
      de: "en"
      - file: "public/javascripts/i18n/%{locale}.js"
        only: "*"

    Fallbacks defined will be used, if not defined (e.g. :pl) I18n.fallbacks or I18n.default_locale will be used.

    fallbacks: :default_locale
      - file: "public/javascripts/i18n/%{locale}.js"
        only: "*"

    Setting the option to :default_locale will enforce the fallback to use the I18n.default_locale, ignoring I18n.fallbacks.


    fallbacks: false
      - file: "public/javascripts/i18n/%{locale}.js"
        only: "*"

    You must disable this feature by setting the option to false.

    To find more examples on how to use the configuration file please refer to the tests.

    Available locales

    By specifying option js_available_locales with a list of locales, this list would be used instead of default I18n.available_locales to generate translations.


    js_available_locales: ["de", "en"]


    Setting the namespace option will change the namespace of the output Javascript file to something other than I18n. This can be useful in no-conflict scenarios. Example:

      - file: "public/javascripts/i18n/translations.js"
        namespace: "MyNamespace"

    will create:

    MyNamespace.translations || (MyNamespace.translations = {});
    MyNamespace.translations["en"] = { ... }

    Adding prefix & suffix to the translations file(s)

    Setting the prefix: "import I18n from 'i18n-js';\n" option will add the line at the beginning of the resultant translation file. This can be useful to use this gem with the i18n-js npm package, which is quite useful to use it with webpack. The user should provide the semi-colon and the newline character if needed.

    For example:

      - file: "public/javascripts/i18n/translations.js"
        prefix: "import I18n from 'i18n-js';\n"

    will create:

    import I18n from 'i18n-js';
    I18n.translations || (I18n.translations = {});

    suffix option is added in
    It's similar to prefix so won't explain it in details.

    Pretty Print

    Set the pretty_print option if you would like whitespace and indentation in your output file (default: false)

      - file: "public/javascripts/i18n/translations.js"
        pretty_print: true

    Javascript Deep Merge (:js_extend option)

    By default, the output file Javascript will call the I18n.extend method to ensure that newly loaded locale files are deep-merged with any locale data already in memory. To disable this either globally or per-file, set the js_extend option to false

    js_extend: false # this will disable Javascript I18n.extend globally
      - file: "public/javascripts/i18n/translations.js"
        js_extend: false # this will disable Javascript I18n.extend for this file

    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.

    Via NPM with webpack and CommonJS

    Add the following line to your package.json dependencies where version is the version you want:

    "i18n-js": "{version_constraint}"
    // Or if you want unreleased version
    // npm install requires it to be the gzipped tarball, see [npm install](
    "i18n-js": "{tag_name_or_branch_name_or_commit_sha}.tar.gz"

    Run npm install then use via

    var i18n = require("i18n-js");

    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 contexts, you can follow the rest of this setting up section.

    Set your locale is easy as

    I18n.defaultLocale = "pt-BR";
    I18n.locale = "pt-BR";
    // pt-BR

    NOTE: You can now apply your configuration before I18n is loaded like this:

    I18n = {}; // You must define this object in top namespace, which should be `window`
    I18n.defaultLocale = "pt-BR";
    I18n.locale = "pt-BR";
    // Load I18n from `i18n.js`, `application.js` or whatever
    // 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 %>";

    You can use translate your messages:

    // or translate with explicit setting of locale
    I18n.t("some.scoped.translation", { locale: "fr" });

    You can also interpolate values:

    // You need the `translations` object setup first
    I18n.translations["en"] = {
      greeting: "Hello %{name}",
    I18n.t("greeting", { name: "John Doe" });

    You can set default values for missing scopes:

    // simple translation
    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 message" }] });

    Default values must be provided as an array of hashes 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;

    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

    Custom fallback rules can also be specified for a particular language. There are three different ways of doing it so: = ["nb", "en"]; = "nb"; = function (locale) {
      return ["nb"];

    Translation Missing Behaviour Control

    By default a missing translation will be displayed as

    [missing "name of scope" translation]

    While you are developing or if you do not want to provide a translation in the default language you can set

    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


    becomes "what is your favorite Christmas present"

    Option missingTranslationPrefix

    In order to still detect untranslated strings, you can set I18n.missingTranslationPrefix to something like:

    I18n.missingTranslationPrefix = "EE: ";

    And result will be:

    "EE: what is your favorite Christmas present";

    This will help you doing automated tests against your localisation assets.

    Customize return when translation entry missing

    Some people prefer returning null/undefined for missing translation:

    I18n.missingTranslation = function (scope, options) {
      return undefined;

    Option defaultSeparator (global) / separator (local)

    Default separator of translation key is . (dot) Meaning I18n.t("scope.entry") would search for translation entry I18n.translations[locale].scope.entry Using a different separator can be done either globally or locally.

    Globally: I18n.defaultSeparator = newSeparator Locally: I18n.t("full_sentences|Server Busy. Please retry later", {separator: '|'})


    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:

          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];

    You can find all rules on

    If you're using the same scope over and over again, you may use the scope option.

    var options = { scope: "activerecord.attributes.user" };
    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"]);

    Number formatting

    Similar to Rails helpers, you have localized number and currency formatting.

    I18n.l("currency", 1990.99);
    // $1,990.99
    I18n.l("number", 1990.99);
    // 1,990.99
    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%

    The toNumber and toPercentage functions accept the following options:

    • precision: defaults to 3
    • separator: defaults to .
    • delimiter: defaults to ,
    • strip_insignificant_zeros: defaults to false

    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

    The toCurrency function accepts the following options:

    • precision: sets the level of precision
    • separator: sets the separator between the units
    • delimiter: sets the thousands delimiter
    • format: sets the format of the output string
    • unit: sets the denomination of the currency
    • strip_insignificant_zeros: defaults to false
    • sign_first: defaults to true

    You can provide only the options you want to override:

    I18n.toCurrency(1000, { precision: 0 }); // $1,000

    The toHumanSize function accepts the following options:

    • precision: defaults to 1
    • separator: defaults to .
    • delimiter: defaults to ""
    • strip_insignificant_zeros: defaults to false
    • format: defaults to %n%u
    • scope: defaults to ""
    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

    You can also add placeholders to the date format:

    I18n.translations["en"] = {
      date: {
        formats: {
          ordinal_day: "%B %{day}",
    I18n.l("date.formats.ordinal_day", "2009-09-18", { day: "18th" }); // Sep 18th

    If you prefer, you can use the I18n.toTime and I18n.strftime functions to format dates.

    var date = new Date();
    I18n.toTime("date.formats.short", "2009-09-18");
    I18n.toTime("date.formats.short", date);
    I18n.strftime(date, "%d/%m/%Y");

    The accepted formats for I18n.strftime are:

    %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/%k - Hour of the day, 24-hour clock (0..23)
    %I     - Hour of the day, 12-hour clock (01..12)
    %-I/%l - Hour of the day, 12-hour clock (1..12)
    %m     - Month of the year (01..12)
    %-m    - Month of the year (1..12)
    %M     - Minute of the hour (00..59)
    %-M    - Minute of the hour (0..59)
    %p     - Meridian indicator (AM  or  PM)
    %P     - Meridian indicator (am  or  pm)
    %S     - Second of the minute (00..60)
    %-S    - Second of the minute (0..60)
    %w     - Day of the week (Sunday is 0, 0..6)
    %y     - Year without a century (00..99)
    %-y    - Year without a century (0..99)
    %Y     - Year with century
    %z/%Z  - Timezone offset (+0545)

    Check out spec/*.spec.js files for more examples!

    Using pluralization and number formatting together

    Sometimes you might want to display translation with formatted number, like adding thousand delimiters to displayed number You can do this:

      "en": {
        "point": {
          "one": "1 Point",
          "other": "{{formatted_number}} Points",
          "zero": "0 Points"
    var point_in_number = 1000;
    I18n.t("point", {
      count: point_in_number,
      formatted_number: I18n.toNumber(point_in_number),

    Output should be 1,000 points

    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.
    sort_translation_keys: true
    fallbacks: false
      + file: "app/assets/javascript/nls/welcome.js"
          + '*.welcome.*'
      + file: "app/assets/javascript/nls/albums.js"
          + '*.albums.*'
      + file: "app/assets/javascript/nls/global.js"
          + '*'
        # Exempt any routes specific translations from being
        # included in the global translation file
          + '*.welcome.*'
          + '*.albums.*'

    When rake i18n:js:export is executed it will create 3 translations files that can be loaded via the javascript_include_tag

    1. Add the javascript_include_tag to your layout and to any route specific files that will require it.
      # views/layouts/application.html.erb
      <%= javascript_include_tag(
          ) %>

    and in the route specific

      # views/welcome/index.html.erb
      <%= javascript_include_tag(
          ) %>
    1. Make sure that you add these files to your config/application.rb
      config.assets.precompile += %w(

    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 to. You want to use this location so that it can be properly precompiled by r.js.
    export_i18n_js: "app/assets/javascript/nls"
    1. In your config/require.yml we need to add a map, shim all the translations, and include them into the appropriate modules
    # In your maps add (if you do not have this you will need to add it)
        i18n: 'nls/i18n'
    # In your shims
          + i18n
          + i18n
    # Finally in your modules
      + name: 'application'
          + i18n
          + 'nls/global'
      + name: 'welcome'
          + application
          + 'nls/welcome'
    1. 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.
    define(["welcome/other_asset", "nls/welcome"], function (otherAsset) {
      // ...
    1. (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.
    # lib/tasks/i18n.rake
    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}')]

    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 = {};
    I18n.translations["en"] = {
      message: "Some special message for you",
    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 the fingerprint of any asset file, including .erb files, is changed

    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:
    $ 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

    $ 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.

    1. You can change something in a different locale file.

    2. Finally, you can change config.assets.version.

    Note: See issue #213 for more details and discussion of this issue.

    Translations in JS are not updated when Sprockets not loaded before this gem

    The "rails engine" declaration will try to detect existence of "sprockets" before adding the initailizer If sprockets is loaded after this gem, the preprocessor for making JS translations file cache to depend on content of locale files will not be hooked. So ensure sprockets is loaded before this gem by moving the entry of sprockets in the Gemfile or adding "require" statements for sprockets somewhere.

    Note: See issue #404 for more details and discussion of this issue.

    JS I18n.toCurrency & I18n.toNumber cannot handle large integers

    The above methods use toFixed and it only supports 53 bit integers. Ref:

    Feel free to find & discuss possible solution(s) at issue #511

    May not work with all backend implementations

    I18n backend implementations have to conform to a specific interface to work with i18n-js. For backends that do not conform to the interface, you will likely get an exception like this:

    Undefined method 'initialized?' for <your backend class>

    For now, i18n-js is compatible with the Simple backend and with I18n::Backend::ActiveRecord (>= 0.4.0).

    If you need a more sophisticated backend for your rails application that doesn't implement the required methods, you can setup i18n-js to get translations from a separate Simple backend, by adding the following in an initializer:

    I18n::JS.backend = I18n.backend
    I18n.backend =<your other backend(s)>, I18n.backend)

    This will use your backend with the default Simple backend as fallback, while i18n-js only sees and uses the simple backend. This means however, that only translations from your static locale files will be present in JavaScript.

    If you do cannot use a Chain-Backend for some reason, you can also set

    I18n::JS.backend =
    I18n.backend = <something different>

    However, the automatic reloading of translations in developement will not work in this case. This is because Rails calls I18n.reload! for each request in development, but reload! will not be called on I18n::JS.backend, since it is a different object. One option would be to patch I18n.reload! in an initializer:

    module I18n
      def self.reload!

    See issue #428 for more details and discussion of this issue.



    Once you've made your great commits:

    1. Fork I18n.js
    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
    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

    You can run I18n tests using Node.js or your browser.

    To use Node.js, install the jasmine-node library:

    $ npm install jasmine-node

    Then execute the following command from the lib's root directory:

    $ npm test

    To run using your browser, just open the spec/js/specs.html file.

    You can run both Ruby and JavaScript specs with rake spec.


    (The MIT License)

    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.




    npm i i18n-js

    DownloadsWeekly Downloads






    Unpacked Size

    98.4 kB

    Total Files


    Last publish


    • fnando
    • pikachuexe