i18n-transformers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3821ea791dc50519a326ea4b283819bb98856e66
+  data.tar.gz: 5bb8cf9ecb191945bf972e9e041e52daa1351d4a
+SHA512:
+  metadata.gz: f03a43f72084e0972395565f5cf92c3ac16f7c6af28ee271bc4ac87affda2c9e7b6df59ecac3ebfb5821adddc4b953393c0344914dae093e6e48e05868c57f11
+  data.tar.gz: 8926319b1e500a4d2babc19a20a81361d638711bfb111882280775a221e07c9d4e410a0bb57081864b47974f7ef25d84004600e786e237a68fabf89d2fab1921

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,7 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.4
+before_install: gem install bundler -v 1.15.1
+notifications:
+  email: false

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in i18n-transformers.gemspec
+gemspec
+
+gem 'pry'
+gem 'byebug'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Tim Masliuchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,247 @@
+# I18n::Transformers
+
+[![Build Status](https://travis-ci.org/timsly/i18n-transformers.svg?branch=master)](https://travis-ci.org/timsly/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:
+
+```ruby
+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](#transformers-chain))
+
+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:
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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:
+
+```ruby
+I18n.transformers.register :markdown
+```
+
+Currently it supports [`redcarpet`](https://github.com/vmg/redcarpet) and [`kramdown`](https://github.com/gettalong/kramdown) markdown parsers.
+
+It uses first available adapter so if both are available `redcarpet` will be picked.
+To specify adapter use:
+
+```ruby
+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:
+
+```ruby
+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.
+
+```ruby
+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
+
+```ruby
+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:
+
+```ruby
+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](#transformers-chain)),
+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:
+
+```ruby
+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:
+
+```ruby
+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
+
+```ruby
+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.
+
+```ruby
+I18n.transformers.reset
+```
+
+## Example
+
+To illustrate how this gem works let's assume the following setup
+
+```yaml
+en:
+  key: my key1 value ^symbol^
+  key_md: '**Text with ^symbol^**'
+  key_markdown: '*^symbol^*'
+```
+
+```ruby
+I18n.transformers.register :markdown # let's assume redcarpet gem is available
+
+I18n.transformers.register do |key, value|
+  value.gsub('^symbol^', 'REPLACED_SYMBOL')
+end
+```
+
+Then
+```ruby
+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](https://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](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'i18n/transformers'
+
+require 'pry'
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/i18n-transformers.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'i18n/transformers/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'i18n-transformers'
+  spec.version       = I18n::Transformers::VERSION
+  spec.authors       = ['Tim Masliuchenko']
+  spec.email         = ['insside@gmail.com']
+
+  spec.summary       = 'Transformers for I18n ruby library'
+  spec.description   = 'Transformers for I18n ruby library'
+  spec.homepage      = 'https://github.com/timsly/i18n-transformers'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'i18n'
+  spec.add_dependency 'activesupport'
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'redcarpet'
+  spec.add_development_dependency 'kramdown'
+end

data/lib/i18n-transformers.rb

@@ -0,0 +1 @@
+require 'i18n/transformers'

data/lib/i18n/transformers.rb

@@ -0,0 +1,32 @@
+require 'i18n'
+require 'active_support/inflector'
+
+require 'i18n/transformers/version'
+
+require 'i18n/transformers/collection'
+require 'i18n/transformers/collection/base'
+require 'i18n/transformers/collection/generic'
+require 'i18n/transformers/collection/markdown'
+
+module I18n
+  module Transformers
+    def transformers
+      @transformers ||= Collection.new
+    end
+
+    def translate(*args)
+      result = super
+
+      # TODO: Handle missing translations.
+      # In theory we don't need to pass them to transformers, but there is no nice way to do that,
+      # only with force raising and handling it again
+
+      key = args.first
+      transformers.all.inject(result) do |transformed, transformer|
+        transformer.transform(key, transformed)
+      end
+    end
+  end
+
+  extend Transformers
+end

data/lib/i18n/transformers/collection.rb

@@ -0,0 +1,70 @@
+module I18n
+  module Transformers
+    class Collection
+      def initialize
+        @collection = []
+      end
+
+      def all
+        @collection
+      end
+
+      def find(name_or_obj, index: false)
+        name = name_or_obj.respond_to?(:name) ? name_or_obj.name : name_or_obj.to_s
+        method = index ? :index : :find
+
+        all.send(method) { |item| item.name == name }
+      end
+
+      def register(name = nil, options = {}, &block)
+        name, options = nil, name if name.is_a?(Hash)
+        position = options.extract! :before, :after, :at
+
+        transformer = if name.respond_to?(:transform)
+          name
+        else
+          klass = name.is_a?(Symbol) ? collection_class_for(name) : name
+          klass = I18n::Transformers::Collection::Generic if !klass || name.is_a?(String)
+          klass.new(options.merge(name: name), &block)
+        end
+
+        insert(transformer, position)
+      end
+
+      def insert(transformer, at: nil, before: nil, after: nil)
+        unless transformer.respond_to?(:transform)
+          raise ArgumentError, 'passed object need to response to transform method'
+        end
+
+        if [at, before, after].count(&:nil?) < 2
+          raise ArgumentError, 'before, after and at cannot be used at the same time'
+        end
+
+        index = at || find(before || after, index: true)
+
+        if index
+          raise ArgumentError, 'invalid index' if index < 0 || index > all.size
+          @collection.insert(after ? index + 1 : index, transformer)
+        else
+          @collection << transformer
+        end
+
+        transformer
+      end
+
+      def reset
+        @collection = []
+        self
+      end
+
+      private
+
+      def collection_class_for(shortcut)
+        klass = shortcut.to_s.classify
+        "I18n::Transformers::Collection::#{klass}".constantize
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/i18n/transformers/collection/base.rb

@@ -0,0 +1,20 @@
+module I18n
+  module Transformers
+    class Collection
+      class Base
+        def initialize(**options, &block)
+          @options = options
+          @block = block
+        end
+
+        def name
+          @name ||= self.class.to_s.demodulize.underscore
+        end
+
+        def transform(key, value)
+          raise NonImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/i18n/transformers/collection/generic.rb

@@ -0,0 +1,17 @@
+module I18n
+  module Transformers
+    class Collection
+      class Generic < Base
+        def initialize(name: nil, **options, &block)
+          super options, &block
+          @name = name ? name.to_s : to_s
+          raise ArgumentError, 'block is missing' unless @block
+        end
+
+        def transform(key, value)
+          @block.call(key, value)
+        end
+      end
+    end
+  end
+end

data/lib/i18n/transformers/collection/markdown.rb

@@ -0,0 +1,70 @@
+module I18n
+  module Transformers
+    class Collection
+      class Markdown < Base
+        def initialize(key_pattern: /(\b|_|\.)md$/, adapter: nil, **options, &block)
+          super options, &block
+          self.key_pattern = key_pattern
+          self.adapter = adapter
+        end
+
+        def key_pattern=(pattern)
+          @key_pattern = pattern.is_a?(Regexp) ? pattern : Regexp.quote(pattern.to_s)
+        end
+
+        def adapter=(adptr)
+          return unless adptr
+
+          require adptr
+          @adapter = adptr
+        end
+
+        def transform(key, value)
+          return value unless @key_pattern =~ key.to_s
+
+          res = @block ? @block.call(key, value) : markdown_to_html(value)
+          res.respond_to?(:html_safe) ? res.html_safe : res
+        end
+
+        def adapter
+          @adapter ||= begin
+            current_adapter = nil
+            available_adapters.each do |a|
+              begin
+                self.adapter = a
+                current_adapter = a
+                break
+              rescue LoadError
+                next
+              end
+            end
+            current_adapter
+          end
+        end
+
+        def available_adapters
+          @available_adapters ||= private_methods
+            .grep(/^transform_with_(.+)$/) { |m| $~[1].to_s }
+        end
+
+        private
+
+        def markdown_to_html(value)
+          method = "transform_with_#{adapter}"
+          raise "Unknown adapter: #{adapter}" unless respond_to?(method, true)
+
+          send method, value
+        end
+
+        def transform_with_redcarpet(value)
+          @redcarpet ||= Redcarpet::Markdown.new(Redcarpet::Render::HTML, @options)
+          @redcarpet.render(value)
+        end
+
+        def transform_with_kramdown(value)
+          Kramdown::Document.new(value).to_html
+        end
+      end
+    end
+  end
+end

data/lib/i18n/transformers/version.rb

@@ -0,0 +1,5 @@
+module I18n
+  module Transformers
+    VERSION = '0.1.0'
+  end
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: i18n-transformers
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim Masliuchenko
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-10-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Transformers for I18n ruby library
+email:
+- insside@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- i18n-transformers.gemspec
+- lib/i18n-transformers.rb
+- lib/i18n/transformers.rb
+- lib/i18n/transformers/collection.rb
+- lib/i18n/transformers/collection/base.rb
+- lib/i18n/transformers/collection/generic.rb
+- lib/i18n/transformers/collection/markdown.rb
+- lib/i18n/transformers/version.rb
+homepage: https://github.com/timsly/i18n-transformers
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Transformers for I18n ruby library
+test_files: []