i18n-tasks

i18n-tasks helps you find and manage missing and unused translations.

This gem analyses code statically for key usages, such as I18n.t('some.key'), in order to:

• Report keys that are missing or unused.
• Pre-fill missing keys, optionally from Google Translate or DeepL (Pro or Free).
• Remove unused keys.

Thus addressing the two main problems of i18n gem design:

• Missing keys only blow up at runtime.
• Keys no longer in use may accumulate and introduce overhead, without you knowing it.

Table of Contents

• Quick Start
• Commands
  • Check health
  • Find usages
  • Add missing keys
  • Translate missing keys
  • Remove unused keys
  • Prune
  • Normalize
  • Move / rename / merge keys
  • Delete keys
  • Compose tasks
• Configuration
  • Locales
  • Storage & locale files
    • Pattern router
    • Conservative router
    • Isolating router
    • Key pattern syntax
    • Custom adapters
    • Rails credentials
  • Usage search
    • Prism-based scanner
  • Fine-tuning
  • Environment variables & dotenv
• Translation backends
  • Google Translate
  • DeepL
  • Yandex
  • OpenAI
  • watsonx
• Features & limitations
  • Relative keys
  • Plural keys
  • Reference keys
  • Dynamic keys
  • I18n.localize
  • t() keyword arguments
  • Unexpected normalization
• Advanced
  • Interactive console
  • CSV import / export
  • Add custom tasks
• Development

Quick Start

i18n-tasks can be used with any project using the ruby i18n gem (default in Rails).

1. Add to your Gemfile:

   gem 'i18n-tasks', '~> 1.2.1', group: :development
   

2. Copy the default configuration file:

   $ cp $(bundle exec i18n-tasks gem-path)/templates/config/i18n-tasks.yml config/
   

3. Run your first health check:

   $ bundle exec i18n-tasks health
   

That's it. See Commands for the full list of tasks, or Configuration to tailor the setup to your project.

Optional: copy a test that checks for missing/unused translations on every CI run:

# RSpec
$ cp $(bundle exec i18n-tasks gem-path)/templates/rspec/i18n_spec.rb spec/

# Minitest
$ cp $(bundle exec i18n-tasks gem-path)/templates/minitest/i18n_test.rb test/

Commands

Run bundle exec i18n-tasks to get the list of all the tasks with short descriptions.

Check health

bundle exec i18n-tasks health checks if any keys are missing or not used, that interpolation variables are consistent across locales, and that all the locale files are normalized (auto-formatted):

$ bundle exec i18n-tasks health

Find usages

See where the keys are used with bundle exec i18n-tasks find:

$ bundle exec i18n-tasks find common.help
$ bundle exec i18n-tasks find 'auth.*'
$ bundle exec i18n-tasks find '{number,currency}.format.*'

Add missing keys

Add missing keys with placeholders (base value or humanized key):

$ bundle exec i18n-tasks add-missing

This and other tasks accept arguments:

$ bundle exec i18n-tasks add-missing -v 'TRME %{value}' fr

Pass --help for more information:

$ bundle exec i18n-tasks add-missing --help
Usage: i18n-tasks add-missing [options] [locale ...]
    -l, --locales  Comma-separated list of locale(s) to process. Default: all. Special: base.
    -f, --format   Output format: terminal-table, yaml, json, keys, inspect. Default: terminal-table.
    -v, --value    Value. Interpolates: %{value}, %{human_key}, %{value_or_human_key}, %{key}. Default: %{value_or_human_key}.
    -h, --help     Display this help message.

Translate missing keys

Translate missing keys using a backend service of your choice.

$ bundle exec i18n-tasks translate-missing

# accepts backend, from and locales options
$ bundle exec i18n-tasks translate-missing --from=base es fr --backend=google

Available backends:

• google – Google Translate
• deepl – DeepL
• yandex – Yandex
• openai – OpenAI
• watsonx – watsonx

Remove unused keys

$ bundle exec i18n-tasks unused
$ bundle exec i18n-tasks remove-unused

These tasks can infer dynamic keys such as t("category.\#{category.name}") if you set search.strict to false, or pass --no-strict on the command line.

If you want to keep the ordering from the original language file when using remove-unused, pass -k or --keep-order.

Prune keys not in base locale

Remove keys from non-base locales that are absent in the base locale:

$ i18n-tasks prune

Pass -k or --keep-order to preserve the original key ordering in the locale files.

Normalize

Sort the keys:

$ bundle exec i18n-tasks normalize

Sort the keys, and move them to the respective files as defined by config.write:

This is the beginning of the README. Read the rest at the original. Read the full README ↗