README.md in i18n-tasks-0.2.22 vs README.md in i18n-tasks-0.3.0.rc1
- old
+ new
@@ -5,101 +5,112 @@
## Installation
-Simply add to Gemfile:
+1. Add to Gemfile:
```ruby
-gem 'i18n-tasks', '~> 0.2.21'
+gem 'i18n-tasks', '~> 0.3.0'
```
-If not using Rails, require the tasks in Rakefile:
+2. Create a config file at `config/i18n-tasks.yml`:
-```ruby
-# Rakefile
-load 'tasks/i18n-tasks.rake'
+```yaml
+# config/i18n-tasks.yml
+base_locale: en
+locales: [es, fr]
```
## Usage
-Use `rake -T i18n` to get the list of tasks with descriptions. These are [the tasks](/lib/tasks/i18n-tasks.rake) available:
+Run `i18n-tasks` to get the list of tasks with short descriptions.
-There are reports for missing and unused translations:
-
```bash
-rake i18n:missing
-rake i18n:unused
-```
+$ i18n-tasks
+Usage: i18n-tasks [command] [options]
+ -v, --version Print the version
+ -h, --help Display this help message.
-To remove unused translations run:
+Available commands:
-```bash
-rake i18n:remove_unused # this will print the unused report and ask for confirmation before deleting keys
+ missing show missing translations
+ unused show unused translations
+ translate-missing translate missing keys with Google Translate
+ add-missing add missing keys to the locales
+ find show where the keys are used in the code
+ 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
+
+See `<command> --help` for more information on a specific command.
```
+There are reports for missing and unused translations.
i18n-tasks can add missing keys to the locale data, and it can also fill untranslated values.
-To add the keys that are not in the base locale but detected in the source do:
+Whenever you can pass locales as arguments, you can use special values `base` and `all`.
+Add placeholders for missing keys to the base locale only:
+
```bash
-# add missing keys to the base locale data (I18n.default_locale)
-# values set to to the optional [argument] or key.humanize
-rake i18n:add_missing
+i18n-tasks add-missing[base]
```
Prefill empty translations using Google Translate ([more below on the API key](#translation-config)).
```bash
-rake i18n:fill:google_translate
+i18n-tasks translate-missing
# this task and the ones below can also accept specific locales:
-rake i18n:fill:google_translate[es+de]
+i18n-tasks translate-missing -l es,de
```
-Prefill using values from the base locale - `I8n.default_locale`:
+Sort the keys and write them to their respective files:
+
```bash
-rake i18n:fill:base_value
+# always happens on add-missing or translate-missing
+i18n-tasks normalize
```
-i18n-tasks sorts the keys and writes them to their respective files:
+Unused report will detect pattern translations and not report them, e.g.:
-```bash
-# this happens automatically on any i18n:fill:* task
-rake i18n:normalize
+```ruby
+t 'category.' + category.key # all 'category.*' keys are considered used
+t "category.#{category.key}.name" # all 'category.*.name' keys are considered used
```
+Relative keys (`t '.title'`) and plural keys (key.one/many/other/etc) are fully supported.
-`i18n:unused` will detect pattern translations and not report them, e.g.:
+Scope argument is supported, but only when it is the first keyword argument ([this](/lib/i18n/tasks/scanners/pattern_with_scope_scanner.rb) can be improved):
```ruby
-t 'category.' + category.key # category.* keys are all considered used
-t "category.#{category.key}" # also works
+# this is supported
+t :invalid, scope: [:auth, :password], attempts: 5
+# but not this
+t :invalid, attempts: 5, scope: [:auth, :password]
```
-Relative keys (`t '.title'`) and plural keys (key.one/many/other/etc) are fully supported.
-
Translation data storage, key usage search, and other [settings](#configuration) are compatible with Rails by default.
## Configuration
Configuration is read from `config/i18n-tasks.yml` or `config/i18n-tasks.yml.erb`.
+See current configuration with `i18n-tasks config`.
-By default, `i18n-tasks` will work with `I18n.default_locale` and `I18n.available_locales`, but you can override this:
+### Locales
+By default, `i18n-tasks` will read `I18n.default_locale` and `I18n.available_locales`.
+However, i18n-tasks does not load application environment by default,
+so it is recommended to set locale settings explicitly:
+
```yaml
# config/i18n-tasks.yml
base_locale: en
locales: [es, fr]
```
-On Rails, if locales are set in the config file, you can make i18n tasks a lot faster by adding this to `Rakefile`:
-
-```ruby
-# disable loading :environment for i18n-tasks
-Rake::Task['i18n:setup'].clear_prerequisites
-```
-
### Storage
```yaml
# i18n data storage
data:
@@ -141,18 +152,17 @@
### Usage search
Inspect all the usages with:
```bash
-rake i18n:usages
+i18n-tasks find
# Filter by a key pattern
-rake i18n:usages[auth.*]
-# Because commas are not allowed inside rake arguments, + is used here instead
-rake i18n:usages['{number+currency}.format.*']
+i18n-tasks find 'auth.*
+i18n-tasks find '{number,currency}.format.*'
```
-
+
Configure usage search in `config/i18n-tasks.yml`:
```yaml
@@ -220,11 +230,11 @@
```
<a name="translation-config"></a>
### Google Translate
-`rake i18n:fill:google_translate` requires a Google Translate API key, get it at [Google API Console](https://code.google.com/apis/console).
+`i18n-tasks translate-missing` requires a Google Translate API key, get it at [Google API Console](https://code.google.com/apis/console).
Put the key in `GOOGLE_TRANSLATE_API_KEY` environment variable or in the config file.
```yaml
translation:
api_key: <Google Translate API key>
@@ -258,10 +268,10 @@
## XLSX
Export missing and unused data to XLSX:
```bash
-rake i18n:spreadsheet_report
+i18n-tasks xlsx-report
```
## HTML