i18n-tasks 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b615d3bad6d043fd662de2ba05caba8230ab6d5a
-  data.tar.gz: 0e16ff6699e70fa0ac00aecddfe674d9e56d4352
+  metadata.gz: b7b2e4af8b66aed1ff33eba3cb802322ceea57db
+  data.tar.gz: 951337877ce07c613b5765b609dd0c3508742a89
 SHA512:
-  metadata.gz: 613137fe779a345d90bafec320ed973e16823e460b2a772bf947ac4e885aae87391e311133842b9d78de69945942214a67bc92151b3e66c6e02fb622bd01e7fc
-  data.tar.gz: 9f7b694d7c4c012d19935089311b87809fbe6279e0184bd1d4b8619e10336de5afca4539c111dbd610bb8786965d890b2eaf4374bc985afb8572702f81ea1fc3
+  metadata.gz: 8b04b6fbabcd0598b2473162142679e81ef5eec9301c3c9362bc44a81084517fbf8d254c1015b0b5dc5365261730550c1356db3cc7d57e56a78ff3a85be1e471
+  data.tar.gz: 2ecb5edaa048079936459dc1f8d607aafe441abb352e7ee0e8585c1a5e251336d8206cc0e7840a3a95a84de78963baafd181a46f779120322ef5736466bfbb35

data/.travis.yml

@@ -8,4 +8,7 @@ rvm:
 env:
   global:
   - TRAVIS=1
+  # google translate api key:
   - secure: Clln+r2rG6adnmVjS0zGMVHs1hOq58UPIqRE73xW3MPLOdozGUyIZ0RrAU2new1h4sqk/5HVwG5NSW7AsUJDGgkNCDx4saJbf/G+oKIity1zNxlHZu5ijZOZGyxYNzGGM4cb2OO6RS6lfzA6TFv2TQtw8DDfKjzG2gpuJOje8sU=
+  # codeclimate repo token:
+  - secure: Qz5xzCujPHN5jGZYiCcsZ73BN5DzJTQwDMuj0kJ+W2nBzGQuQDvADT0rHFsHOhdQ/epZe89pVL8wEbr5GaCZ+iZCt1JfasZpvyvCtwMUkPtjrLxpWwVKlH3u7xqAzyYj7Z8ru0VqHni19d6DPzAaNGyV3gaiI1pR6Y63Ux+msM0=

data/Gemfile

@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
-  gem 'coveralls', require: false
   gem 'byebug', platform: :mri_21, require: false
 end
+
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/README.md

@@ -1,7 +1,14 @@
-# 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.
@@ -18,16 +25,16 @@ i18n-tasks can be used with any project using [i18n][i18n-gem] (default in Rails
 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/
@@ -35,96 +42,97 @@ $ 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
+```
+
+### Add missing keys
 
-See `<command> --help` for more information on a specific command.
+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
-
-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:
+`i18n-tasks` also provides low-level composable tasks for fine-grained locale data manipulation. The above is equivalent to:
 
-```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)):
@@ -344,15 +352,6 @@ translation:
 
 `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:
@@ -368,23 +367,26 @@ While i18n-tasks does not provide an HTML version of the report, you can add [on
 
 ## 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:
@@ -396,8 +398,8 @@ $ i18n-tasks my-task
 [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

data/bin/i18n-tasks

@@ -1,6 +1,13 @@
 #!/usr/bin/env ruby
 # coding: utf-8
 
+# prevent i18n gem warning
+require 'i18n'
+i18n_gem_config = I18n.config
+if i18n_gem_config.respond_to?(:enforce_available_locales=) && i18n_gem_config.enforce_available_locales.nil?
+  i18n_gem_config.enforce_available_locales = true
+end
+
 require 'i18n/tasks'
 require 'i18n/tasks/commands'
 require 'slop'
@@ -14,47 +21,34 @@ err = proc { |message, exit_code|
   exit exit_code
 }
 
-command = nil
 begin
+  ran = false
+  commander = ::I18n::Tasks::Commands
+  slop_adapter = ::I18n::Tasks::SlopCommand
   args = ARGV.dup
   args = ['--help'] if args.empty?
-  slop = Slop.parse(args, help: true) do
+  Slop.parse(args, help: true) do
     on('-v', '--version', 'Print the version') {
       puts I18n::Tasks::VERSION
       exit
     }
-    ::I18n::Tasks::Commands.cmds.each do |name, attr|
-      command name.tr('_', '-') do
-        description attr.desc if attr.desc
-        instance_exec(&attr.opts) if attr.opts
-        run do |opts, args|
-          command = [name, opts, args]
+    commander.cmds.each do |name, attr|
+      slop_dsl = slop_adapter.slop_command(name, attr) { |name, opts, args|
+        begin
+          ran = true
+          commander.run_command name, slop_adapter.parse_slop_opts_args(opts, args)
+        rescue Errno::EPIPE
+          # ignore Errno::EPIPE which is throw when pipe breaks, e.g.:
+          # i18n-tasks missing | head
+          exit 1
         end
-      end
+      }
+      instance_exec &slop_dsl
     end
   end
 rescue Slop::Error => e
   err.call(e.message, 64)
 end
 
-if command
-  cmd  = ::I18n::Tasks::Commands.new
-  meth = command[0]
-  opts = command[1].to_hash.reject { |k, v| v.nil? }
-  args = command[2]
-  begin
-    if opts.empty? && args.empty?
-      cmd.log_verbose "run #{meth.tr('_', '-')} without arguments"
-      cmd.send meth
-    else
-      opts = opts.merge(arguments: args) unless args.empty?
-      cmd.log_verbose "run #{meth.tr('_', '-')} with #{opts.map { |k, v| "#{k}=#{v}" } * ' '}"
-      cmd.send meth, opts
-    end
-  rescue Errno::EPIPE
-    # ignore Errno::EPIPE which is throw when pipe breaks, e.g.:
-    # i18n-tasks missing | head
-  end
-else
-  err.call("Command unknown: #{ARGV[0]}", 64) if ARGV[0]
-end
+
+err.call("Command unknown: #{args[0]}", 64) if !ran && args[0]

data/config/i18n-tasks.yml

@@ -0,0 +1,87 @@
+# i18n-tasks works on itself! this is the internal config
+
+base_locale: en
+## i18n-tasks detects locales automatically from the existing locale files
+## uncomment to set locales explicitly
+# locales: [en, es, fr]
+
+# Read and write locale data
+data:
+  ## by default, translation data are read from the file system, or you can provide a custom data adapter
+  # adapter: I18n::Tasks::Data::FileSystem
+
+  # Locale files to read from
+  read:
+    - config/locales/%{locale}.yml
+    # - config/locales/*.%{locale}.yml
+    # - config/locales/**/*.%{locale}.yml
+
+  # key => file routes, matched top to bottom
+  write:
+    ## E.g., write devise and simple form keys to their respective files
+    # - ['{devise, simple_form}.*', 'config/locales/\1.%{locale.yml}']
+    # Catch-all
+    - config/locales/%{locale}.yml
+    # `i18n-tasks normalize -p` will force move the keys according to these rules
+
+  # YAML / JSON serializer options, passed to load / dump / parse / serialize
+  yaml:
+    write:
+      ## do not wrap lines at 80 characters (override default)
+      line_width: 96
+  json:
+    write:
+      # pretty print JSON
+      indent: '  '
+      space: ' '
+      object_nl: "\n"
+      array_nl: "\n"
+
+# Find translate calls
+search:
+  ## Default scanner finds t() and I18n.t() calls
+  # scanner: I18n::Tasks::Scanners::PatternWithScopeScanner
+
+  ## Paths to search in, passed to File.find
+  paths:
+    - lib/
+
+  ## Root for resolving relative keys (default)
+  # relative_roots:
+  #   - app/views
+
+  ## File.fnmatch patterns to exclude from search (default)
+  # exclude: ["*.jpg", "*.png", "*.gif", "*.svg", "*.ico", "*.eot", "*.ttf", "*.woff", "*.pdf"]
+
+  ## Or, File.fnmatch patterns to include
+  # include: ["*.rb", "*.html.slim"]
+
+  ## Lines starting with # or / are ignored by default
+  # ignore_lines:
+  #  - "^\\s*[#/](?!\\si18n-tasks-use)"
+
+## Google Translate
+# translation:
+#   # Get an API key and set billing info at https://code.google.com/apis/console to use Google Translate
+#   api_key: "AbC-dEf5"
+
+## Consider these keys not missing
+# ignore_missing:
+#   - pagination.views.*
+
+## Consider these keys used
+# ignore_unused:
+#   - 'simple_form.{yes,no}'
+#   - 'simple_form.{placeholders,hints,labels}.*'
+#   - 'simple_form.{error_notification,required}.:'
+
+## Exclude these keys from `i18n-tasks eq-base' report
+# ignore_eq_base:
+#   all:
+#     - common.ok
+#   fr,es:
+#     - common.brand
+
+## Exclude these keys from all of the reports
+# ignore:
+#  - kaminari.*

data/config/locales/en.yml

@@ -0,0 +1,95 @@
+---
+en:
+  i18n_tasks:
+    common:
+      locale: Locale
+      type: Type
+      key: Key
+      value: Value
+      base_value: Base Value
+      details: Details
+      continue_q: Continue?
+      n_more: "%{count} more"
+    google_translate:
+      errors:
+        no_results: Google Translate returned no results. Make sure billing information is set at
+          https://code.google.com/apis/console.
+    remove_unused:
+      confirm:
+        one: One translations will be removed from %{locales}.
+        other: "%{count} translation will be removed from %{locales}."
+      removed: Removed %{count} keys
+      noop: No unused keys to remove
+    translate_missing:
+      translated: Translated %{count} keys
+    add_missing:
+      added: Added %{count} keys
+    unused:
+      none: Every translation is in use.
+    missing:
+      none: No translations are missing.
+    usages:
+      none: No key usages found.
+    health:
+      no_keys_detected: No keys detected. Check data.read in config/i18n-tasks.yml.
+    data_stats:
+      title: Forest (%{locales})
+      text: has %{key_count} keys across %{locale_count} locales. On average, values are %{value_chars_avg}
+        characters long, keys have %{key_segments_avg} segments, a locale has %{per_locale_avg} keys.
+      text_single_locale: has %{key_count} keys in total. On average, values are %{value_chars_avg}
+        characters long, keys have %{key_segments_avg} segments.
+    cmd:
+      encourage:
+      - Good job!
+      - Well done!
+      - Perfect!
+      desc:
+        normalize: 'normalize translation data: sort and move to the right files'
+        data: show locale data
+        data_merge: merge locale data with trees
+        data_write: replace locale data with tree
+        data_remove: remove keys present in tree from data
+        health: is everything OK?
+        find: show where keys are used in the code
+        unused: show unused translations
+        missing: show missing translations
+        translate_missing: translate missing keys with Google Translate
+        add_missing: add missing keys to locale data
+        remove_unused: remove unused keys
+        eq_base: show translations equal to base value
+        tree_merge: merge trees
+        tree_filter: filter tree by key pattern
+        tree_rename_key: rename tree node
+        tree_subtract: tree A minus the keys in tree B
+        tree_set_value: set values of keys, optionally match a pattern
+        tree_convert: convert tree between formats
+        config: display i18n-tasks configuration
+        gem_path: show path to the gem
+        irb: start REPL session within i18n-tasks context
+      args:
+        default_text: 'Default: %{value}'
+        desc:
+          out_format: 'Output format: %{valid_text}. %{default_text}.'
+          data_format: 'Data format: %{valid_text}. %{default_text}.'
+          keys: List of keys separated by commas (,), spaces, or newlines.
+          locales_filter: 'Comma-separated list of locale(s) to process. Default: all. Special: base.'
+          locale: 'Locale. Default: base'
+          confirm: Confirm automatically
+          nostdin: Do not read from stdin
+          strict: Do not infer dynamic key usage such as `t("category.\#{category.name}")`
+          missing_types: 'Filter by types: %{valid}.'
+          key_pattern: Filter by key pattern (e.g. 'common.*')
+          value: 'Value. Interpolates: %{value}, %{human_key}, %{value_or_human_key}'
+          pattern_router: 'Use pattern router: keys moved per config data.write'
+      enum_opt:
+        desc:
+          default: "%{valid_text}. %{default_text}"
+        invalid_one: "%{invalid} is not one of: %{valid}."
+        invalid_list: "%{invalid} is not in: %{valid}."
+      errors:
+        pass_forest: Pass locale forest
+        invalid_locale: Invalid locale %{invalid}
+        invalid_format: 'Unknown format %{invalid}. Valid: %{valid}.'
+        invalid_missing_type:
+          one: 'Unknown type %{invalid}. Valid: %{valid}.'
+          other: 'Unknown types: %{invalid}. Valid: %{valid}.'