i18n-tasks Documentation

i18n-tasks uses routers to determine how and where translation keys are written to files. There are three types:

1. Conservative router (Default): Keeps keys where they are found or infers the path from the base locale. If a key is entirely new, it falls back to pattern_router behavior.
2. Pattern router: Organizes keys based on a list of key patterns. Matches are processed from top to bottom.
3. Isolating router: Assumes each YAML file is independent. It writes translations to an alternate target file for each source file (only changing the %{locale} part). This is useful for avoiding collisions in setups like ViewComponent sidecars, though it cannot detect missing keys from code usage due to lack of scope awareness.

To reorganize existing keys using a pattern router, use the normalize -p command.

# Example Pattern Router configuration
data:
  router: pattern_router
  write:
    - ["{models,views}.*", 'config/locales/\1.%{locale}.yml']
    - ["{:}.*", 'config/locales/\1.%{locale}.yml']
    - "config/locales/%{locale}.yml"

Supported

• Relative keys: Keys relative to the file path (e.g., t '.title') and keys relative to controller.action_name in Rails controllers.
• Plural keys: Keys using pluralization syntax like key.{one,many,other,...}.
• Reference keys: Keys containing :symbol values are supported. They can be looked up by reference or value in find and are copied as-is during add/translate-missing.
• t() keyword arguments: The scope argument is fully supported. The default argument is supported by the AST scanner for pre-filling locale files.

Limitations

• Dynamic keys: Not recognized by default (see 'Handle dynamic translation keys' for solutions).
• I18n.localize: Not supported because the generated key depends on the object type and cannot be determined statically. Use i18n-tasks-use hints instead.
• YAML Normalization: Because the tool uses Psych, multi-line strings might undergo unexpected normalization (e.g., changing from literal block | to quoted "" if trailing spaces are present).

Tasks in i18n-tasks are composable. You can pipe the output of one task into another to perform complex manipulations.

Examples:

1. Add missing keys with a template: missing (finds keys) $\rightarrow$ tree-set-value (sets values) $\rightarrow$ data-merge (writes to files).

2. Remove unused keys without confirmation: unused $\rightarrow$ data-remove.

3. Remove keys from a target locale that don't exist in the base locale: missing (finds diff) $\rightarrow$ tree-mv (moves keys to target) $\rightarrow$ data-remove (removes them from target).

# Add missing keys with a template
$ bundle exec i18n-tasks missing -f yaml fr | bundle exec i18n-tasks tree-set-value 'TRME %{value}' | bundle exec i18n-tasks data-merge

# Remove unused keys
$ bundle exec i18n-tasks unused -f yaml | bundle exec i18n-tasks data-remove

# Remove all keys from 'fr' that do not exist in 'en'
$ bundle exec i18n-tasks missing -t diff -f yaml en | bundle exec i18n-tasks tree-mv en fr | bundle exec i18n-tasks data-remove