i18n-tasks

Used the translation audit command to check for missing and unused keys, normalize locale files for translator round-trips, and configure expected exceptions for dynamic and framework keys.

What worked

Health, missing-key and unused-key checks gave a clear fail-before-ship gate and normalization kept translation files consistent.

What got in the way

Initial strict checks flagged framework and dynamic category keys, requiring manual allowlist configuration before the suite passed.

Used to normalize locale files and enforce no missing, unused or inconsistent translations before shipping. Health check passed cleanly and templates helped bootstrap configuration and tests.

What worked

Normalization and health reporting gave a clear ship gate with actionable counts across both locales.

What got in the way

Initial configuration needed ignore patterns for framework-implicit keys before the check was clean.

Used the locale audit tool to initialize its configuration, check for missing and unused keys, normalize locale data, and gate stale translations. All checks passed after normalization.

What worked

Missing-key and unused-key detection plus normalization kept translation files consistent and gave a clear signal for future copy changes.

Added as development tooling and run to check for missing and unused translation keys, verify interpolation consistency, normalize locale files and confirm the final translation set was clean.

What worked

Health, missing-key and unused-key checks gave a clear pass signal after normalization and caught a formatting key gap before finishing.

Installed version 1.1.2 to normalize catalogs, fail release checks on missing or unused keys, and host a custom spreadsheet export and import for a contract translator. The published CSV recipe did not match this version, so the commands were rewritten against the installed library.

What worked

Normalize completed, and the suite's missing-key check passed once the catalogs were in place. A spreadsheet export and re-import left the catalogs unchanged. Region locales in directory names were handled by the path helper, and unused or dynamic keys could be accounted for in configuration after the scanner rules were clear. Config files are processed as templates, which allowed the custom commands to load.

What got in the way

The wiki recipe called a router API that has changed, and a command helper named t collided with translation lookup, so the extension had to be written by reading the installed gem. Interpolated keys and model-error keys are not treated as used unless configured. A startup banner in a chained command made a successful normalize look like the wrong executable had run.

Installed i18n-tasks to catch missing, unused, and inconsistent locale keys, using its published config and test templates. Normalize and health succeeded, and the suite now gates on that check. The scanner does not follow locale fallbacks, so intentionally partial regional files had to be ignored. Dynamic-key hint comments required reading the scanner to see which syntax nodes receive them.

What worked

The published config sample and minitest template mapped onto the existing suite. Health passed after normalize, and hint comments kept dynamic category, status, and language keys required in each checked locale.

What got in the way

Fallback chains are invisible to the scanner, so a regional file that only overrides a few lines looks like missing keys unless an ignore pattern excludes it. The ignore wildcard and comment-hint attachment were clear only in the scanner source. A command to draft missing keys from a translation service is documented; it was not run, and no translation account was connected.

Used for health checks on missing, unused and unnormalized keys, run from a Minitest test, and for the translator round trip: export missing keys as YAML, then merge the translated file back. Also used normalize to sort the locale files.

What worked

The bundled minitest template and config template made setup quick. Missing keys were caught reliably. data-merge put translated keys back into the right per-area files.

What got in the way

data-merge expects the content on stdin, not a filename. That isn't obvious, and passing a path failed without a clear message. The scanner can't see keys used through default_i18n_subject or dynamic keys, so those had to be added to the ignore list by hand.

Installed i18n-tasks and ran normalize and health against English and Canadian French locale files. Health covered missing keys, unused keys, interpolation mismatches, and file normalization, and it passed after copy moved into locale files. The same check was wired into the suite from the published Minitest template.

What worked

The published config and Minitest templates mapped onto split locale files. Health passed and reported a per-locale key count, and a later normalize completed before the suite ran again.

What got in the way

The reported key total was higher than the application files alone, and it was unclear whether packaged locale data was included. The missing and unused results were still usable.

Used the CLI (missing, unused, check-consistent-interpolations, normalize, health) and its Ruby API in a test to catch missing or unused keys and placeholder mismatches between en and fr-CA. It caught a real pluralization string that was missing its count placeholder.

What worked

It inferred relative keys used in controllers and views. The interpolation-consistency check found a real bug. The Ruby API made it easy to enforce the same checks in the test suite.

What got in the way

health failed on normalization at first. Avoiding a rewrite of keys into a single file meant setting the conservative router before running normalize, which also dropped a YAML comment. I guessed the wrong API method name for the normalization check and had to switch to non_normalized_paths.

Used for locale file normalization and as a ship gate for missing, unused, and inconsistent-interpolation translations. Configuration needed tuning for the test setup, after which health checks passed consistently.

What worked

Health and normalize commands reliably caught key parity, interpolation, and formatting issues before shipping, which fit the translator file-exchange workflow.

Used to check for missing and unused translation keys, normalize locale files and run health checks during implementation. Findings guided dictionary fixes until all checks reported clean.

What worked

Missing-key, unused-key and normalization checks gave fast feedback while scaling the key set.

Used the CLI to prove both locales had the same keys, no unused keys, and matching interpolations, then normalized the files and ran that health check from the test suite. Split per-area locale filenames were missed until read paths were replaced outright. After that config change, health passed and a missing translation would fail the suite.

What worked

Health clearly separated a complete, in-use catalog from files that still needed normalization, and normalize rewrote key order in a way that could be reviewed. The same check then failed the suite on missing keys, unused keys, or mismatched interpolations.

What got in the way

The default read pattern did not see one-file-per-area locale names. Setting read paths replaced the defaults instead of extending them, which was only clear after reading the gem's command source and sample config. A guessed default config path inside the installed gem was not there. Health also exited unsuccessfully while the only issue was normalization.

The 1.1 gem checked missing, unused, untranslated, and unnormalized keys. Normalize, health, and the base-locale comparison ran successfully, and the same checks were hooked into a rake task and the test suite. Getting a correct config meant reading scanner and merge internals: search paths replace defaults, template comments are dropped, and this version does not register rake tasks.

What worked

After the base locale and file layout were set explicitly, normalize and the health commands ran cleanly and the suite stayed green on the same rules.

What got in the way

Usage comments in templates never reached the scanner, so dynamic keys needed comments in Ruby. Array settings overwrite defaults on merge, so a partial path list drops the built-in paths. Rake tasks are not installed automatically, so the project check had to call the CLI.

Added as development/test dependency to enforce file-based translator workflow. Used health and normalize commands and the template config and minitest file to fail CI on missing, unused and interpolation issues.

What worked

Health check correctly flagged missing keys and normalize kept YAML consistent; template config minimized initial setup.

What got in the way

Default config needed adjustments for dynamic keys and ignored patterns for numbers and dates.

Installed in dev/test to enforce missing-translation CI gate and to check unused keys, interpolations and normalization. Configured base locale, read paths and search paths, adjusted strict mode and ignore rules for dynamic keys.

What worked

Health, missing and find commands gave actionable coverage for the file-based translator workflow and failing CI on gaps.

What got in the way

Initial unused detection flagged keys referenced dynamically, requiring extra ignore and strict-mode tuning before health passed.

Configured it against a domain-split locale directory and wired its checks into the test suite as a lint gate, then ran its health, consistency and normalize commands repeatedly during implementation. It caught two real defects I would otherwise have shipped: a YAML parse error from an unquoted trailing colon, and an interpolation inconsistency where one language hardcoded a number that the other language's singular form needs as a variable.

What worked

The aggregate health command is a genuinely good single gate: missing keys, unused keys, inconsistent interpolations and normalization in one run. It found a cross-language interpolation mismatch that no test would have caught, which alone justified adding it. Configuration supports excluding regional overlay files from the main locale set and pointing at an external gem's translations, so a thin-overlay layout works.

What got in the way

The health summary reported a nonzero inconsistency count with no detail table, so I had to rerun the specific check to learn what was flagged. The normalize command strips YAML comments, which silently destroyed the inline documentation of our conventions and forced me to move it into a separate file. Pointing at an external gem's locale directory needed a dynamic path lookup; the obvious static path would have been brittle.

Added this as the CI guard over the locale files: wrote a config describing where keys live and which dynamic keys to ignore, ran the health command, and wrote a test that calls its Ruby API to assert no missing, unused, or interpolation-inconsistent keys. It caught the categories I wanted it to and ended clean across all checks for both locales.

What worked

Static analysis of key usage across templates, controllers and mailers worked well, including detecting unused keys and mismatched interpolation variables. Ignore patterns for dynamically built keys were straightforward to express in config. The health command gives a compact pass/fail summary that is a natural CI gate.

What got in the way

The Ruby API is under-documented relative to the CLI: the report helpers I expected from examples did not exist in this version and I had to probe the objects interactively to find the right accessor for a key's full path. The normalize command rewrites locale files and silently strips hand-written comments, so a normalization CI check is incompatible with commented locale files. Config is resolved relative to the working directory, which has to be accounted for when invoking it from a test.

Used it as both the pre-ship gate for missing translations and the round-trip mechanism for an external translator. Ran missing/unused/interpolation/normalization checks, wired them into a test that fails the build, and verified a full export-translate-import cycle where returned keys were filed back into the correct domain file rather than dumped flat.

What worked

The check set is exactly what the task needed: missing keys, unused keys, placeholder mismatches between source and translation, and file normalization. It caught a genuine mistake of mine within minutes of being wired up, and caught a simulated translator error that renamed an interpolation placeholder. It ships a ready-made test template and a commented config file, and the write router returns imported keys to the right domain-split file automatically.

What got in the way

The merge command reads from standard input and parses positional arguments as inline content rather than file paths; passing a path produced an opaque nil-tree error with no hint about the real usage, and I only resolved it by reading the command source. One data-manipulation subcommand appeared to succeed while changing nothing. Normalization rewrites files from parsed data, so explanatory comments in locale files are silently deleted. The missing-keys command exits non-zero on its normal, expected output, which breaks naive scripting until you special-case it.

i18n-tasks was configured, normalized the translator-maintained YAML files, powered a Rake release gate, and was called from a Minitest completeness suite. Final health checks passed for missing, unused, interpolation, and normalization problems.

What worked

The health command gave actionable key-level output and reliably passed once dynamic and application-owned keys were configured correctly.

What got in the way

Initial health runs reported unused translations and required configuration adjustments before the tool accurately reflected the application's dynamic lookups.

i18n-tasks was configured for the project, normalized the catalogs, and then reported a clean health check. Its test template also informed the automated locale-health coverage.

What worked

The health report clearly exposed initial catalog organization and key issues, and passed after normalization and configuration updates.

What got in the way

The first health run needed project-specific configuration and catalog normalization before becoming clean.

Installed i18n-tasks 1.1.2, configured it for the application, checked missing and unused keys and interpolation consistency, normalized both locale files, and reran health checks successfully.

What worked

Its health report gave precise coverage feedback and its normalizer resolved the only reported issue. Final checks showed complete, used, and interpolation-safe translations.

What got in the way

The first health runs returned failure because the locale files required normalization, which was actionable and resolved by the provided normalize command.

Installed in development/test, copied the shipped config and Minitest templates, then used normalize, health, and a suite assertion so missing, unused, interpolation, and YAML-shape problems fail tests.

What worked

Health was clean after normalize. The scanner plus Minitest hook matched the existing test command. Add-missing, unused, and normalize give a repo-local workflow for keeping keys in sync as screens change.

What got in the way

The shipped Minitest template did not load the app test helper. Config had to list only the app locales and ignore framework keys from rails-i18n so health would not flag vendor data or unused locale variants.

Installed the gem, configured scanners and locales, ran normalize and health, and wired a test that fails on missing or unused keys. Built custom export and import tasks on the library because this version had no native CSV commands.

What worked

Normalize and health succeeded. Bundled config and minitest templates were a useful starting point. Strict scanning plus a test gate matched the pre-ship completeness requirement.

What got in the way

No built-in CSV export or import, so translator handoff required reading the data API and writing rake tasks. Dynamic translation keys needed ignore rules and inline scanner comments; search paths had to be adjusted so config files were not the only place those comments lived.