You can install i18n-js via the command line or by adding it to your project's Gemfile.

gem install i18n-js

Or in your Gemfile

gem "i18n-js"

To use guard for automatic exports, install guard and guard-compat, then create a Guardfile with the following configuration. Ensure you adjust the file paths if your locales are not in the standard app/config/locales directory.

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

When migrating to the pipeline: API, move plugin configurations from the top level of your configuration file (e.g., config/i18n.yml) into a single pipeline: array.

Key changes:

• Plugins are now listed as objects within the pipeline: array.
• Each entry must include a plugin: key specifying the plugin name.
• The order of entries in the pipeline: array determines the execution order.
• Plugin-specific options (like files: for export_files) must be moved inside the pipeline stage object, alongside plugin: and enabled:.

translations:
  - file: app/javascript/locales/%{locale}.json
    patterns:
      - "*"

pipeline:
  - plugin: embed_fallback_translations
    enabled: true

  - plugin: export_files
    enabled: true
    files:
      - template: path/to/template.erb
        output: "%{dir}/%{base_name}.ts"

The JavaScript package is now a separate dependency. Install it using your preferred package manager (yarn, npm, pnpm, etc.).

$ yarn add i18n-js@latest
$ npm i --save-dev i18n-js@latest

To temporarily disable a plugin without removing it from your configuration, set enabled: false on its specific pipeline stage. This allows you to re-enable it easily later.

pipeline:
  - plugin: embed_fallback_translations
    enabled: false   # temporarily disabled

You can use watchman to trigger the i18n export command whenever locale files or the configuration file change.

1. Create a script at bin/i18n-watch with the Watchman trigger configuration.
2. Make it executable: chmod +x bin/i18n-watch.
3. Run it: ./bin/i18n-watch.

If using Foreman, uncomment the while true loop in the script to keep the process running and add it to your Procfile:

i18n: ./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

Plugin configuration has moved from top-level YAML keys to a pipeline: array. Each entry in the array must include a plugin: key (using the snake_case name of the plugin) and the plugin's specific configuration keys.

Example Configuration Transformation:

Before:

embed_fallback_translations:
  enabled: true

export_files:
  enabled: true
  files:
    - template: templates/export.erb
      output: "%{dir}/%{base_name}-%{digest}.ts"

After:

pipeline:
  - plugin: embed_fallback_translations
    enabled: true

  - plugin: export_files
    enabled: true
    files:
      - template: templates/export.erb
        output: "%{dir}/%{base_name}-%{digest}.ts"

If you are running in an environment without a database (e.g., a Docker build process), you can use the --require flag with the i18n export command to provide a custom loading file. This allows you to manually load the necessary files (like ActiveSupport or specific locale paths) required for the export to function.

i18n export --require ./config/i18n_export.rb

You can use the i18n-js/listen integration to watch for changes in a Rails application. Create a file at config/initializers/i18n.rb and call I18nJS.listen within an after_initialize block.

Configuration Options for I18nJS.listen

• config_file: The i18n-js configuration file path.
• locales_dir: One or multiple directories to watch for locale changes.
• options: Options passed directly to the listen gem.
• run_on_start: Whether to export files on start. Defaults to true.

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