README.md in i18n-tasks-0.6.3 vs README.md in i18n-tasks-0.7.0

- old
+ new

@@ -1,9 +1,16 @@ -# i18n-tasks [![Build Status][badge-travis]][travis] [![Coverage Status][badge-coveralls]][coveralls] [![Code Climate][badge-code-climate]][code-climate] [![Gemnasium][badge-gemnasium]][gemnasium] +# i18n-tasks [![Build Status][badge-travis]][travis] [![Coverage Status][badge-coverage]][coverage] [![Code Climate][badge-code-climate]][code-climate] [![Gemnasium][badge-gemnasium]][gemnasium] i18n-tasks helps you find and manage missing and unused translations. +## What? + +i18n-tasks scans calls such as `I18n.t('some.key')` and provides reports on key usage, missing, and unused keys. +i18n-tasks can also can pre-fill missing keys, including from Google Translate, and it can remove unused keys as well. + +## Why? + The default approach to locale data management with gems such as [i18n][i18n-gem] is flawed. If you use a key that does not exist, this will only blow up at runtime. Keys left over from removed code accumulate in the resource files and introduce unnecessary overhead on the translators. Translation files can quickly turn to disarray. i18n-tasks improves this by analysing code statically, without running it. It scans calls such as `I18n.t('some.key')` and provides reports on key usage, missing, and unused keys. @@ -16,118 +23,119 @@ ## Installation Add to Gemfile: ```ruby -gem 'i18n-tasks', '~> 0.6.3' +gem 'i18n-tasks', '~> 0.7.0' ``` -Copy default [config file](#configuration) (optional): +Copy default [configuration file](#configuration) (optional): ```console $ cp $(i18n-tasks gem-path)/templates/config/i18n-tasks.yml config/ ``` -Copy [rspec test](#rspec-integration) (optional): +Copy rspec test to test for missing and unused translations as part of the suite (optional): ```console $ cp $(i18n-tasks gem-path)/templates/rspec/i18n_spec.rb spec/ ``` ## Usage -Run `i18n-tasks` to get the list of tasks with short descriptions. +Run `i18n-tasks` to get the list of all the tasks with short descriptions. -```bash -$ i18n-tasks -Usage: i18n-tasks [command] [options] - -v, --version Print the version - -h, --help Display this help message. +### Check health -Available commands: +`i18n-tasks health` will tell you any keys are missing or not used: - missing show missing translations - unused show unused translations - eq-base show translations equal to base value - find show where the keys are used in the code - data show locale data - translate-missing translate missing keys with Google Translate - add-missing add missing keys to the locales - normalize normalize translation data: sort and move to the right files - remove-unused remove unused keys - config display i18n-tasks configuration - xlsx-report save missing and unused translations to an Excel file - irb REPL session within i18n-tasks context - gem-path show path to the gem +```console +$ i18n-tasks health +``` -See `<command> --help` for more information on a specific command. +### Add missing keys + +Add missing keys with placeholders (base value or humanized key): + +```console +$ i18n-tasks add-missing ``` -Show tasks accept a format option, and all but `find` accept locales as arguments, e.g: +Most tasks also accept arguments: -```bash -$ i18n-tasks data --help -Usage: i18n-tasks data [options] - -l, --locales Filter by locale(s), comma-separated list (en,fr) or all (default), or pass arguments without -l +```console +$ i18n-tasks add-missing -v 'TRME %{value}' fr +$ 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}. Default: %{value_or_human_key} -h, --help Display this help message. -$ i18n-tasks data -fkeys en es fr ``` -#### Add missing keys +`i18n-tasks` also provides low-level composable tasks for fine-grained locale data manipulation. The above is equivalent to: -You can add missing values, generated from the key (for base locale) or copied from the base locale (for other locales). -To add missing values to the base locale only: - -```bash -# most task accept locales as first argument. `base` and `all` are special -i18n-tasks add-missing base -# add-missing accepts a placeholder argument, with optional base_value interpolation -i18n-tasks add-missing -p 'PLEASE-TRANSLATE %{base_value}' fr +```console +$ i18n-tasks missing -fyaml fr | i18n-tasks tree-set-value 'TRME %{value}' | i18n-tasks data-merge ``` -#### Google Translate missing keys +See command help for more information. +### Google Translate missing keys + Translate missing values with Google Translate ([more below on the API key](#translation-config)). -```bash -i18n-tasks translate-missing +```console +$ i18n-tasks translate-missing # accepts from and locales options: -i18n-tasks translate-missing --from base es fr +$ i18n-tasks translate-missing --from base es fr ``` -Sort the keys and write them to their respective files with `i18n-tasks normalize`. -This always happens on `i18n-tasks add-missing` and `i18n-tasks translate-missing`. +### Find usages +See where the keys are used with `i18n-tasks find`: + ```bash -i18n-tasks normalize +$ i18n-tasks find common.help +$ i18n-tasks find 'auth.*' +$ i18n-tasks find '{number,currency}.format.*' ``` -#### Find usages +<img width="437" height="129" src="https://raw.github.com/glebm/i18n-tasks/master/doc/img/i18n-usages.png"> -See where the keys are used with `i18n-tasks find`: +### Remove unused keys ```bash -i18n-tasks find common.help -i18n-tasks find 'auth.*' -i18n-tasks find '{number,currency}.format.*' +$ i18n-tasks unused +$ i18n-tasks remove-unused ``` -![i18n-screenshot][screenshot-find] +These tasks will infer dynamic key usage such as `t("category.\#{category.name}")` by default. +Pass `-s` or `--strict` to disable this feature. -### Find / remove unused keys +`i18n-tasks remove-unused` is roughly equivalent to: ```bash -i18n-tasks unused -i18n-tasks remove-unused +$ i18n-tasks unused -fyaml | i18n-tasks data-remove ``` -These tasks will infer dynamic key usage such as `t("category.\#{category.name}")` by default. -Pass `-s` or `--strict` to disable this feature. +### Normalize data -#### Features +Sort the keys: +```console +$ i18n-tasks normalize +``` + +Sort the keys, and move them to the respective files as defined by (`config.write`)[#multiple-locale-files]: + +```console +$ i18n-tasks normalize -p +``` + +### Features + Relative keys (`t '.title'`) and plural keys (`key.{one,many,other,...}`) are fully supported. Scope argument is supported, but only when it is the first keyword argument ([improvements welcome](/lib/i18n/tasks/scanners/pattern_with_scope_scanner.rb)): ```ruby # this is supported @@ -342,19 +350,10 @@ ## Interactive Console `i18n-tasks irb` starts an IRB session in i18n-tasks context. Type `guide` for more information. -## RSpec integration - -You might want to test for missing and unused translations as part of your test suite. -Install the spec file: - -```console -$ cp $(i18n-tasks gem-path)/templates/rspec/i18n_spec.rb spec/ -``` - ### XLSX Export missing and unused data to XLSX: ```console @@ -366,27 +365,30 @@ While i18n-tasks does not provide an HTML version of the report, you can add [one like this](https://gist.github.com/glebm/bdd3ab6d12d915f0c81b). ## Add New Tasks -Tasks that come with the gem are defined in [lib/i18n/tasks/commands.rb](lib/i18n/tasks/commands.rb). +Tasks that come with the gem are defined in [lib/i18n/tasks/command/commands](lib/i18n/tasks/command/commands). -You can add a new task by re-opening the class and loading it in i18n-tasks.yml: +Add a custom task like the ones defined by the gem: ```ruby -# lib/i18n/tasks/my_task.rb -I18n::Tasks::Commands.class_eval do - desc 'my task' - cmd :my_task do |opts = {}| - puts i18n.data[opts[:arguments].try(:first) || base_locale] +# my_commands.rb +class MyCommands + include ::I18n::Tasks::Command::Collection + cmd :my_command, desc: 'my custom command' + def my_command(opts = {}) end end ``` ```yaml # config/i18n-tasks.yml -<% require 'i18n/tasks/my_task' %> +<% + require 'my_commands' + I18n::Tasks::Commands.send :include, MyCommands +%> ``` Run with: ```console @@ -394,11 +396,11 @@ ``` [MIT license]: /LICENSE.txt [travis]: https://travis-ci.org/glebm/i18n-tasks [badge-travis]: http://img.shields.io/travis/glebm/i18n-tasks.svg -[coveralls]: https://coveralls.io/r/glebm/i18n-tasks?branch=master -[badge-coveralls]: http://img.shields.io/coveralls/glebm/i18n-tasks.svg +[coverage]: https://codeclimate.com/github/glebm/i18n-tasks +[badge-coverage]: https://img.shields.io/codeclimate/coverage/github/glebm/i18n-tasks.svg [gemnasium]: https://gemnasium.com/glebm/i18n-tasks [badge-gemnasium]: https://gemnasium.com/glebm/i18n-tasks.svg [code-climate]: https://codeclimate.com/github/glebm/i18n-tasks [badge-code-climate]: http://img.shields.io/codeclimate/github/glebm/i18n-tasks.svg [i18n-gem]: https://github.com/svenfuchs/i18n "svenfuchs/i18n on Github"