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.
- 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.
i18n-tasks can be used with any project using the ruby i18n gem (default in Rails).
Add i18n-tasks to the Gemfile:
gem 'i18n-tasks', '~> 0.9.4'Copy the default configuration file:
$ cp $(i18n-tasks gem-path)/templates/config/i18n-tasks.yml config/Copy rspec test to test for missing and unused translations as part of the suite (optional):
$ cp $(i18n-tasks gem-path)/templates/rspec/i18n_spec.rb spec/Run i18n-tasks to get the list of all the tasks with short descriptions.
i18n-tasks health checks if any keys are missing or not used:
$ i18n-tasks healthAdd missing keys with placeholders (base value or humanized key):
$ i18n-tasks add-missingThis and other tasks accept arguments:
$ i18n-tasks add-missing -v 'TRME %{value}' frPass --help for more information:
$ 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 values with Google Translate (more below on the API key).
$ i18n-tasks translate-missing
# accepts from and locales options:
$ i18n-tasks translate-missing --from base es frSee where the keys are used with i18n-tasks find:
$ i18n-tasks find common.help
$ i18n-tasks find 'auth.*'
$ i18n-tasks find '{number,currency}.format.*'
$ i18n-tasks unused
$ i18n-tasks remove-unusedThese 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.
Sort the keys:
$ i18n-tasks normalizeSort the keys, and move them to the respective files as defined by config.write:
$ i18n-tasks normalize -pi18n-tasks also provides composable tasks for reading, writing and manipulating locale data. Examples below.
add-missing implemented with missing, tree-set-value and data-merge:
$ i18n-tasks missing -f yaml fr | i18n-tasks tree-set-value 'TRME %{value}' | i18n-tasks data-mergeremove-unused implemented with unused and data-remove (sans the confirmation):
$ i18n-tasks unused -f yaml | i18n-tasks data-removeRemove all keys in fr but not en from fr:
$ i18n-tasks missing -t diff -f yaml en | i18n-tasks tree-rename-key en fr | i18n-tasks data-removeSee the full list of tasks with i18n-tasks --help.
i18n-tasks uses an AST scanner for .rb files, and a regexp-based scanner for other files, such as .haml.
i18n-tasks offers support for relative keys, such as t '.title'.
✔ Keys relative to the file path they are used in (see relative roots configuration) are supported.
✔ Keys relative to controller.action_name in Rails controllers are supported. The closest def name is used.
✔ Plural keys, such as key.{one,many,other,...} are fully supported.
✔ Reference keys (keys with :symbol values) are fully supported. These keys are copied as-is in
add/translate-missing, and can be looked up by reference or value in find.
✔ scope keyword argument is fully supported by the AST scanner, and also by the Regexp scanner but only when it is the first argument.
✔ default argument can be used to pre-fill locale files (AST scanner only).
By default, dynamic keys such as t "cats.#{cat}.name" are not recognized.
I encourage you to mark these with i18n-tasks-use hints.
Alternatively, you can enable dynamic key inference by setting search.strict to false in the config. In this case,
all the dynamic parts of the key will be considered used, e.g. cats.tenderlove.name would not be reported as unused.
Note that only one section of the key is treated as a wildcard for each string interpolation; i.e. in this example,
cats.tenderlove.special.name will be reported as unused.
Configuration is read from config/i18n-tasks.yml or config/i18n-tasks.yml.erb.
Inspect the configuration with i18n-tasks config.
Install the default config file with:
$ cp $(i18n-tasks gem-path)/templates/config/i18n-tasks.yml config/Settings are compatible with Rails by default.
By default, base_locale is set to en and locales are inferred from the paths to data files.
You can override these in the config.
The default data adapter supports YAML and JSON files.
i18n-tasks can manage multiple translation files and read translations from other gems.
To find out more see the data options in the config.
NB: By default, only %{locale}.yml files are read, not namespace.%{locale}.yml. Make sure to check the config.
For writing to locale files i18n-tasks provides 2 options.
Pattern router organizes keys based on a list of key patterns, as in the example below:
data:
router: pattern_router
# a list of {key pattern => file} routes, matched top to bottom
write:
# write models.* and views.* keys to the respective files
- ['{models,views}.*', 'config/locales/\1.%{locale}.yml']
# or, write every top-level key namespace to its own file
- ['{:}.*', 'config/locales/\1.%{locale}.yml']
# default, sugar for ['*', path]
- 'config/locales/%{locale}.yml'
Conservative router keeps the keys where they are found, or infers the path from base locale. If the key is completely new, conservative router will fall back to pattern router behaviour. Conservative router is the default router.
data:
router: conservative_router
write:
- ['devise.*', 'config/locales/devise.%{locale}.yml']
- 'config/locales/%{locale}.yml'
If you want to have i18n-tasks reorganize your existing keys using data.write, either set the router to
pattern_router as above, or run i18n-tasks normalize -p (forcing the use of the pattern router for that run).
A special syntax similar to file glob patterns is used throughout i18n-tasks to match translation keys:
| syntax | description |
|---|---|
* |
matches everything |
: |
matches a single key |
{a, b.c} |
match any in set, can use : and *, match is captured |
If you store data somewhere but in the filesystem, e.g. in the database or mongodb, you can implement a custom adapter. If you have implemented a custom adapter please share it on the wiki.
i18n-tasks uses an AST scanner for .rb files, and a regexp scanner for all other files.
New scanners can be added easily: please refer to this example.
See the search section in the config file for all available configuration options.
NB: By default, only the app/ directory is searched.
Add hints to static analysis with magic comment hints (lines starting with (#|/) i18n-tasks-use by default):
# i18n-tasks-use t('activerecord.models.user') # let i18n-tasks know the key is used
User.model_name.humanYou can also explicitly ignore keys appearing in locale files via ignore* settings.
See the config file to find out more.
i18n-tasks translate-missing requires a Google Translate API key, get it at Google API Console.
Where this key is depends on your Google API console:
- Old console: API Access -> Simple API Access -> Key for server apps.
- New console: Project -> APIS & AUTH -> Credentials -> Public API access -> Key for server applications.
In both cases, you may need to create the key if it doesn't exist.
Put the key in GOOGLE_TRANSLATE_API_KEY environment variable or in the config file.
# config/i18n-tasks.yml
translation:
api_key: <Google Translate API key>i18n-tasks irb starts an IRB session in i18n-tasks context. Type guide for more information.
Export missing and unused data to XLSX:
$ i18n-tasks xlsx-reportTasks that come with the gem are defined in lib/i18n/tasks/command/commands. Custom tasks can be added easily, see the examples on the wiki.