Skip to content

Commit

Permalink
Update the default config file, edit the Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
glebm committed Mar 31, 2015
1 parent 865f309 commit 5eb98a1
Show file tree
Hide file tree
Showing 3 changed files with 74 additions and 165 deletions.
151 changes: 26 additions & 125 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ For now, you can disable dynamic key inference by passing `-s` or `--strict` to
Configuration is read from `config/i18n-tasks.yml` or `config/i18n-tasks.yml.erb`.
Inspect configuration with `i18n-tasks config`.

Install the default config file with:
Install the [default config file][config] with:

```console
$ cp $(i18n-tasks gem-path)/templates/config/i18n-tasks.yml config/
Expand All @@ -188,60 +188,16 @@ Settings are compatible with Rails by default.
### Locales

By default, `base_locale` is set to `en` and `locales` are inferred from the paths to data files.
You can override these in the config:

```yaml
# config/i18n-tasks.yml
base_locale: en
locales: [es, fr] # This includes base_locale by default
```
`internal_locale` controls the language i18n-tasks reports in. Locales available are `en` and `ru` (pull request to add more!).

```yaml
internal_locale: en
```
You can override these in the [config][config].

### Storage

The default data adapter supports YAML and JSON files.

```yaml
# config/i18n-tasks.yml
data:
# configure YAML / JSON serializer options
# passed directly to load / dump / parse / serialize.
yaml:
write:
# do not wrap lines at 80 characters (override default)
line_width: -1
```

#### Multiple locale files

Use `data` options to work with locale data spread over multiple files.

`data.read` accepts a list of file globs to read from per-locale:

```
# config/i18n-tasks.yml
data:
read:
# read from namespaced files, e.g. simple_form.en.yml
- 'config/locales/*.%{locale}.yml'
# read from a gem (config is parsed with ERB first, then YAML)
- "<%= %x[bundle show vagrant].chomp %>/templates/locales/%{locale}.yml"
# default
- 'config/locales/%{locale}.yml'
```

#### Key pattern syntax

| syntax | description |
|:------------:|:----------------------------------------------------------|
| `*` | matches everything |
| `:` | matches a single key |
| `{a, b.c}` | match any in set, can use `:` and `*`, match is captured |
i18n-tasks can manage multiple translation files and read translations from other gems.
To find out more the `data` options in the [config][config].

For writing to locale files i18n-tasks provides 2 options.

Expand All @@ -266,7 +222,7 @@ data:

Conservative router keeps the keys where they are found, or infers the path from base locale.
If the key is completely new, conservative router will fall back to pattern router behaviour.
Conservative router is the default router.
Conservative router is the **default** router.

```
data:
Expand All @@ -276,55 +232,26 @@ data:
- 'config/locales/%{locale}.yml'
```

#### Custom adapters
If you store data somewhere but in the filesystem, e.g. in the database or mongodb, you can implement a custom adapter.
Implement [a handful of methods][adapter-example], then set `data.adapter` to the class name; the rest of the `data` config is passed to the initializer.
##### Key pattern syntax

```yaml
# config/i18n-tasks.yml
data:
# file_system is the default adapter, you can provide a custom class name here:
adapter: file_system
```
A special syntax similar to file glob patterns is used throughout i18n-tasks to match translation keys:

### Usage search
| syntax | description |
|:------------:|:----------------------------------------------------------|
| `*` | matches everything |
| `:` | matches a single key |
| `{a, b.c}` | match any in set, can use `:` and `*`, match is captured |


Configure usage search in `config/i18n-tasks.yml`:
#### Custom adapters

```yaml
# config/i18n-tasks.yml
# i18n usage search in source
search:
# search these directories (relative to your Rails.root directory, default: 'app/')
paths:
- 'app/'
- 'vendor/'
# paths for relative key resolution:
relative_roots:
# default:
- app/views
# add a custom one:
- app/views-mobile
# include only files matching this glob pattern (default: blank = include all files)
include:
- '*.rb'
- '*.html.*'
- '*.text.*'
# explicitly exclude files (default: exclude common binary files)
exclude:
- '*.js'
# you can override the default key regex pattern:
pattern: "\\bt[( ]\\s*(:?\".+?\"|:?'.+?'|:\\w+)"
# comments are ignored by default
ignore_lines:
- "^\\s*[#/](?!\\si18n-tasks-use)"
```
If you store data somewhere but in the filesystem, e.g. in the database or mongodb, you can implement a custom adapter.
If you have implemented a custom adapter please share it on [the wiki][wiki].

It is also possible to use a custom key usage scanner by setting `search.scanner` to a class name.
See this basic [pattern scanner](/lib/i18n/tasks/scanners/pattern_scanner.rb) for reference.
### Usage search

See the `search` section in the [config file][config] for all available configuration options.
An example of a custom scanner can be found here: https://github.com/glebm/i18n-tasks/issues/138#issuecomment-87255708.

### Fine-tuning

Expand All @@ -335,33 +262,8 @@ Add hints to static analysis with magic comment hints (lines starting with `(#|/
User.model_name.human
```

You can also explicitly ignore keys appearing in locale files:

```yaml
# config/i18n-tasks.yml
# do not report these keys as unused
ignore_unused:
- category.*.db_name
# do not report these keys as missing (both on blank value and no key)
ignore_missing:
- devise.errors.unauthorized # ignore this key
- pagination.views.* # ignore the whole pattern
# E.g to ignore all Rails number / currency keys:
- 'number.{format, percentage.format, precision.format, human.format, currency.format}.{strip_insignificant_zeros,significant,delimiter}'
- 'time.{pm,am}'
# do not report these keys when they have the same value as the base locale version
ignore_eq_base:
all:
- common.ok
es,fr:
- common.brand
# do not report these keys ever
ignore:
- kaminari.*
```
You can also explicitly ignore keys appearing in locale files via `ignore*` settings.
See the [config file][config] to find out more.

<a name="translation-config"></a>
### Google Translate
Expand All @@ -383,7 +285,7 @@ translation:
api_key: <Google Translate API key>
```
## Interactive Console
## Interactive console
`i18n-tasks irb` starts an IRB session in i18n-tasks context. Type `guide` for more information.

Expand All @@ -395,12 +297,7 @@ Export missing and unused data to XLSX:
$ i18n-tasks xlsx-report
```

### HTML

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
## Add new tasks

Tasks that come with the gem are defined in [lib/i18n/tasks/command/commands](lib/i18n/tasks/command/commands).

Expand Down Expand Up @@ -430,6 +327,8 @@ Run with:
$ i18n-tasks my-task
```

See more examples of custom tasks [on the wiki](https://github.com/glebm/i18n-tasks/wiki#custom-tasks).

[MIT license]: /LICENSE.txt
[travis]: https://travis-ci.org/glebm/i18n-tasks
[badge-travis]: http://img.shields.io/travis/glebm/i18n-tasks.svg
Expand All @@ -439,6 +338,8 @@ $ i18n-tasks my-task
[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
[config]: https://github.com/glebm/i18n-tasks/blob/master/templates/config/i18n-tasks.yml
[wiki]: https://github.com/glebm/i18n-tasks/wiki "i18n-tasks wiki"
[i18n-gem]: https://github.com/svenfuchs/i18n "svenfuchs/i18n on Github"
[screenshot-find]: https://raw.github.com/glebm/i18n-tasks/master/doc/img/i18n-usages.png "i18n-tasks find output screenshot"
[adapter-example]: https://github.com/glebm/i18n-tasks/blob/master/lib/i18n/tasks/data/file_system_base.rb
1 change: 0 additions & 1 deletion lib/i18n/tasks/command/commands/missing.rb
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ module Missing
proc { |invalid, valid| I18n.t('i18n_tasks.cmd.errors.invalid_missing_type',
invalid: invalid * ', ', valid: valid * ', ', count: invalid.length) })


cmd :missing,
pos: '[locale ...]',
desc: t('i18n_tasks.cmd.desc.missing'),
Expand Down
87 changes: 48 additions & 39 deletions templates/config/i18n-tasks.yml
Original file line number Diff line number Diff line change
@@ -1,92 +1,101 @@
# i18n-tasks finds and manages missing and unused translations https://github.com/glebm/i18n-tasks
# i18n-tasks finds and manages missing and unused translations: https://github.com/glebm/i18n-tasks

# The "main" locale.
base_locale: en
## i18n-tasks detects locales automatically from the existing locale files
## uncomment to set locales explicitly
# locales: [en, es, fr]
## All available locales are inferred from the data by default. Alternatively, specify them explicitly:
# locales: [es, fr]
## Reporting locale, default: en. Available: en, ru.
# internal_locale: en

## i18n-tasks report locale, default: en, available: en, ru
# internal_locale: ru

# Read and write locale data
# Read and write translations.
data:
## by default, translation data are read from the file system, or you can provide a custom data adapter
## Translations are read from the file system. Supported format: YAML, JSON.
## Provide a custom adapter:
# adapter: I18n::Tasks::Data::FileSystem

# Locale files to read from
# Locale files or `File.find` patterns where translations are read from:
read:
- config/locales/%{locale}.yml
# - config/locales/*.%{locale}.yml
## Default:
# - config/locales/%{locale}.yml
## More files:
# - config/locales/**/*.%{locale}.yml
## Another gem:
# - "<%= %x[bundle show vagrant].chomp %>/templates/locales/%{locale}.yml"

# key => file routes, matched top to bottom
# Locale files to write new keys to, based on a list of key pattern => file rules. Matched from top to bottom:
# `i18n-tasks normalize -p` will force move the keys according to these rules
write:
## E.g., write devise and simple form keys to their respective files
## For example, 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
## Catch-all default:
# - config/locales/%{locale}.yml

## Specify the router (see Readme for details). Valid values: conservative_router, pattern_router, or a custom class.
# router: convervative_router

# YAML / JSON serializer options, passed to load / dump / parse / serialize
yaml:
write:
# do not wrap lines at 80 characters
line_width: -1
json:
write:
# pretty print JSON
indent: ' '
space: ' '
object_nl: "\n"
array_nl: "\n"

## Pretty-print JSON:
# json:
#
# write:
# 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:
- app/
## Paths or `File.find` patterns to search in:
# paths:
# - app/

## Root for resolving relative keys (default)
## Root directories for relative keys resolution.
# relative_roots:
# - app/views
# - app/controllers
# - app/helpers
# - app/presenters

## File.fnmatch patterns to exclude from search (default)
# exclude: ["*.jpg", "*.png", "*.gif", "*.svg", "*.ico", "*.eot", "*.ttf", "*.woff", "*.woff2", "*.pdf"]
## Files or `File.fnmatch` patterns to exclude from search. Some files are always excluded regardless of this setting:
## %w(*.jpg *.png *.gif *.svg *.ico *.eot *.ttf *.woff *.woff2 *.pdf *.css *.sass *.scss *.less *.yml *.json)
# exclude: []

## Or, File.fnmatch patterns to include
## Alternatively, the only files or `File.fnmatch patterns` to search in `paths`:
## If specified, this settings takes priority over `exclude`, but `exclude` still applies.
# include: ["*.rb", "*.html.slim"]

## Default scanner finds t() and I18n.t() calls.
# scanner: I18n::Tasks::Scanners::PatternWithScopeScanner

## 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
## Do not consider these keys missing:
# ignore_missing:
# - 'errors.messages.{accepted,blank,invalid,too_short,too_long}'
# - '{devise,simple_form}.*'

## Consider these keys used
## Consider these keys used:
# ignore_unused:
# - 'activerecord.attributes.*'
# - '{devise,kaminari,will_paginate}.*'
# - 'simple_form.{yes,no}'
# - 'simple_form.{placeholders,hints,labels}.*'
# - 'simple_form.{error_notification,required}.:'

## Exclude these keys from `i18n-tasks eq-base' report
## Exclude these keys from the `i18n-tasks eq-base' report:
# ignore_eq_base:
# all:
# - common.ok
# fr,es:
# - common.brand

## Exclude these keys from all of the reports
## Ignore these keys completely:
# ignore:
# - kaminari.*

0 comments on commit 5eb98a1

Please sign in to comment.