Project

i18n-js

2.76
A long-lived project that still receives updates
Export i18n translations and use them on JavaScript.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

Runtime

>= 0
>= 0
 Project Readme

i18n.js

Export i18n translations to JSON.
A perfect fit if you want to export translations to JavaScript.

Oh, you don't use Ruby? No problem! You can still use i18n-js
and the companion JavaScript package.

Tests Gem Gem MIT License

Warning: This branch contains the code for v4, our next major release.

Installation

gem install i18n-js

Or add the following line to your project's Gemfile:

gem "i18n-js", "~> 4.0.0.alpha1"

Usage

About patterns:

  • Patterns can use * as a wildcard and can appear more than once.
    • * will include everything
    • *.messages.*
  • Patterns starting with ! are excluded.
    • !*.activerecord.* will exclude all ActiveRecord translations.

The config file:

---
translations:
  - file: app/frontend/locales/en.json
    patterns:
      - "*"
      - "!*.activerecord"
      - "!*.errors"
      - "!*.number.nth"

  - file: app/frontend/locales/:locale.:digest.json
    patterns:
      - "*"

The output path can use the following placeholders:

  • :locale: the language that's being exported.
  • :digest: the MD5 hex digest of the exported file.

The Ruby API:

require "i18n-js"

I18nJS.call(config_file: "config/i18n.yml")
I18nJS.call(config: config)

The CLI API:

$ i18n --help
Usage: i18n COMMAND FLAGS

Commands:

- init: Initialize a project
- export: Export translations as JSON files
- version: Show package version
- check: Check for missing translations

Run `i18n COMMAND --help` for more information on specific commands.

By default, i18n will use config/i18n.yml and config/environment.rb as the configuration files. If you don't have these files, then you'll need to specify both --config and --require.

Listing missing translations

To list missing and extraneous translations, you can use i18n check. This command will load your translations similarly to how i18n export does, but will output the list of keys that don't have a matching translation against the default locale. Here's an example:

i18n check command in action

This command will exist with status 1 whenever there are missing translations. This way you can use it as a CI linting.

You can ignore keys by adding a list to the config file:

---
translations:
  - file: app/frontend/locales/en.json
    patterns:
      - "*"
      - "!*.activerecord"
      - "!*.errors"
      - "!*.number.nth"

  - file: app/frontend/locales/:locale.:digest.json
    patterns:
      - "*"

check:
  ignore:
    - en.mailer.login.subject
    - en.mailer.login.body

Note: In order to avoid mistakenly ignoring keys, this configuration option only accepts the full translation scope, rather than accepting a pattern like pt.ignored.scope.*.

Automatically export translations

Using watchman

Create a script at bin/i18n-watch.

#!/usr/bin/env bash

root=`pwd`

watchman watch-del "$root"
watchman watch-project "$root"
watchman trigger-del "$root" i18n

watchman -j <<-JSON
[
  "trigger",
  "$root",
  {
    "name": "i18n",
    "expression": [
      "anyof",
      ["match", "config/locales/**/*.yml", "wholename"],
      ["match", "config/i18n.yml", "wholename"]
    ],
    "command": ["i18n", "export"]
  }
]
JSON

# If you're running this through Foreman,
# the uncomment the following lines:
# while true; do
#   sleep 1
# done

Make it executable with chmod +x bin/i18n-watch. To watch for changes, run ./bin/i18n-watch. If you're using Foreman, make sure you uncommented the lines that keep the process running (while..), and add something like the following line to your Procfile:

i18n: ./bin/i18n-watch

Using guard

Install guard and guard-compat. Then create a Guardfile with the following configuration:

guard(:"i18n-js",
      run_on_start: true,
      config_file: "./config/i18n.yml",
      require_file: "./config/environment.rb") do
  watch(%r{^(app|config)/locales/.+\.(yml|po)$})
  watch(%r{^config/i18n.yml$})
  watch("Gemfile")
end

If your files are located in a different path, remember to configure file paths accordingly.

Now you can run guard start -i.

Using listen

Create a file under config/initializers/i18n.rb with the following content:

Rails.application.config.after_initialize do
  require "i18n-js/listen"
  I18nJS.listen
end

The code above will watch for changes based on config/i18n.yml and config/locales. You can customize these options with I18nJS.listen(config_file: "config/i18n.yml", locales_dir: "config/locales").

Integrating with your frontend

You're done exporting files, now what? Well, go to i18n to discover how to use the NPM package that loads all the exported translation.

FAQ

How can I export translations without having a database around?

Some people may have a build process using something like Docker that don't necessarily have a database available. In this case, you may define your own loading file by using something like i18n export --require ./config/i18n_export.rb, where i18n_export.rb may look like this:

# frozen_string_literal: true

require "bundler/setup"
require "rails"
require "active_support/railtie"
require "action_view/railtie"

I18n.load_path += Dir["./config/locales/**/*.yml"]

Notice that you may not need to load ActiveSupport and ActionView lines, or even may need to add additional requires for other libs. With this approach you have full control on what's going to be loaded.

Maintainer

Contributors

Contributing

For more details about how to contribute, please read https://github.com/fnando/i18n-js/blob/main/CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License. A copy of the license can be found at https://github.com/fnando/i18n-js/blob/main/LICENSE.md.

Code of Conduct

Everyone interacting in the i18n-js project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.