I18n::Transformers

Transformers for I18n ruby library

I18n::Transformers is a I18n ruby library plugin that allows transform translations.

I18n::Transformers can be used if some or even all translations keys require some transformation. For example parsing markdown or replacing some symbol.

Installation

Add this line to your application's Gemfile:

gem 'i18n-transformers'

And then execute:

$ bundle

Or install it yourself as:

$ gem install i18n-transformers

Usage

The core of this library is I18n.transformers.register method. It can be used to register various transformers or reset all available transformers. It is designed to register transformers globally. It returns transformer instance that can be later used with before/after options.

If some transformers have to be applied only for some set of keys then this logic has to implemented in the transformer class itself. Also, it is very important to return original value in this case(see Transformers chain section)

The gem comes with a few built-in transformers:

• generic transformer
• markdown transformer

If symbol was passed as the first argument to .register call it will search thought built-in transformers and try to register it. If there is no match generic adapter will be used.

Generic transformer

Generic transformer is designed to handle custom transformers defined as a block. It is useful for simple transformations.

To register generic transformer call:

I18n.transformers.register do |key, value|
  "transformered-#{value}"
end

I18n.translate key and translation value will be passed to the block.

Each transformer has its name that helps to register transformer after or before some specific transformer. By default generic transformer generates unique name for each transformer, but it can be also explicitly specified by passing name as the first argument.

I18n.transformers.register 'my_transformer' do |key, value|
  "transformered-#{value}"
end

All transformers can be registered before, after or at specific position. before, after and at options are used for that.

I18n.transformers.register 'my_transformer' do |key, value|
  "transformered1-#{value}"
end

another_transformer = I18n.transformers.register after: 'my_transformer' do |key, value|
  "transformered2-#{value}"
end

I18n.transformers.register before: another_transformer, do |key, value|
  "transformered3-#{value}"
end

I18n.transformers.register at: 1, do |key, value|
  "transformered4-#{value}"
end

Markdown transformer

To register built-in markdown transformer use:

I18n.transformers.register :markdown

Currently it supports redcarpet and kramdown markdown parsers.

It uses first available adapter so if both are available redcarpet will be picked. To specify adapter use:

I18n.transformers.register :markdown, adapter: :redcarpet

Markdown transformer is designed to be triggered only for some set of keys. By default it triggers only for keys ended with _md and .md.

So specify custom key pattern use:

I18n.transformers.register :markdown, key_pattern: /_markdown$/

In the example above markdown transformer will be triggered only if key ended with _markdown.

If block was specified it will be used instead. It can be useful to override default transformation behavior.

I18n.transformers.register :markdown do |key, value|
  MyMarkdownParser.parse(value)
end

Please note that it will be still running only if key matches key_pattern option.

Markdown transformer always uses the same name - 'markdown' - so to register some transformer after/before it use

I18n.transformers.register :markdown

I18n.transformers.register 'my_custom_transformer', after: 'markdown' do |key, value|
  Smth.transform(key, value)
end

It is designed to be registered only once that's why name is always markdown.

Custom transformers

To register custom transformer use:

I18n.transformers.register MyCustomTransformer

MyCustomTransformer has to be inherited from I18n::Transformers::Collection::Base class. Also, to not break transformers chain(see Transformers chain section), it is responsible for returning correct value if it needs to be applied only for some set of keys

All options except before, after and at will be passed as the first argument to .new call.

Transformer instance can be passed too:

I18n.transformers.register MyCustomTransformer.new(:val1, :val2)

Transformers chain

It is very important to return some value from either block or #transform method from the custom transformer class otherwise transformers chain will be broken.

Here is the bad example of custom transformer:

I18n.transformers.register do |key, value|
  if key.to_s.start_with? 'key_prefix'
    value.gsub('^symbol^', 'REPLACED_SYMBOL')
  end
end

The code above most likely will be broken for all keys that don't start with key_prefix. To fix that we should always fallback to the original value

I18n.transformers.register do |key, value|
  if key.to_s.start_with? 'key_prefix'
    value.gsub('^symbol^', 'REPLACED_SYMBOL')
  else
    value
  end
end

Reseting transformers

This library is designed to register all transformers globally. In a rails app it can be done in initializer. But if there is a need to reset all transformers .reset method can be used.

I18n.transformers.reset

Example

To illustrate how this gem works let's assume the following setup

en:
  key: my key1 value ^symbol^
  key_md: '**Text with ^symbol^**'
  key_markdown: '*^symbol^*'

I18n.transformers.register :markdown # let's assume redcarpet gem is available

I18n.transformers.register do |key, value|
  value.gsub('^symbol^', 'REPLACED_SYMBOL')
end

Then

I18n.translate :key # => my key1 value REPLACED_SYMBOL

I18n.translate :key_md # => <p><strong>Text with REPLACED_SYMBOL</strong></p>

I18n.translate :key_markdown # => *REPLACED_SYMBOL*

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

TODO

• Think more about missing translations and find a nice way to handle them

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/timsly/i18n-transformers.

License

The gem is available as open source under the terms of the MIT License.