mova 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dce5a55e194f08af6811f43235c1d05fd61a8fd6
+  data.tar.gz: 0bd231589ce57b0bd8c834efc7fd3f8249104214
+SHA512:
+  metadata.gz: c1295e5cc33f92fce796ef8e96c513a3ce1574c6047d30a9bcd945b7ecb8be77f86bdef3bfb6861c663874f08791e61b051a5229d1fa77cb09f1d05c71e97633
+  data.tar.gz: 99de35a299fc4877a76ce12d937efac57119819a11d38019abfe7a18c893ad89e1ea6156e0feb493fcefdb8aa80c738df7b128be4354014346cf096ce656b80c

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+## Adding a feature
+
+1. Open an issue and explain what you're planning to do. It is better to discuss new idea first,
+   rather when diving into code.
+2. Add some tests.
+3. Write the code.
+4. Make sure all tests pass.
+5. Commit with detailed explanation what you've done in a message.
+6. Open pull request.
+
+## Breaking/removing a feature
+
+1. Add deprecation warning and fallback to old behaivour if possible.
+2. Explain how to migrate to the new code in CHANGELOG.
+3. Update/remove tests.
+4. Update the code.
+5. Make sure all tests pass.
+6. Commit with detailed explanation what you've done in a message.
+7. Open pull request.
+
+## Fixing a bug
+
+1. Add failing test.
+2. Fix the bug.
+3. Make sure all tests pass.
+4. Commit with detailed explanation what you've done in a message.
+5. Open pull request.
+
+## Fixing a typo
+
+1. Commit with a message that include "[ci skip]" remark.
+2. Open pull request.
+
+## Running the tests
+
+```
+rake test
+```
+
+## Working with documentation
+
+```
+yard server -dr
+open http://localhost:8808
+```

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem "minitest", "~> 5.4"
+gem "rspec-mocks", "~> 3.0"
+gem "yard", "~> 0.8"
+gem "pry"
+
+group :benchmark do
+  gem "benchmark-ips"
+  gem "i18n"
+  gem "r18n-core"
+  gem "activesupport"
+  gem "dalli", ">= 2.6.4"
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Andrii Malyshko
+
+MIT License
+
+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,102 @@
+# Mova
+
+**Mova** is a translation and localization library that aims to be simple and fast.
+
+## Name origin
+
+"Мова" [['mɔwɑ][mova-pronounce]] in Ukrainian and Belarusian means "language".
+
+## Why
+
+Because [I18n][i18n] code is hard to reason about.
+
+## Status
+
+Not tested in production. Localization part is yet to be implemented.
+
+## Installation
+
+Add this line to your application's Gemfile and run `bundle`:
+
+```ruby
+gem 'mova'
+```
+
+## Usage
+
+```ruby
+require "mova"
+
+# instantiate a translator with in-memory storage
+translator = Mova::Translator.new
+
+# store translations
+translator.put(en: {hello: "world!"})
+
+# retreive translations
+translator.get("hello", :en) #=> "world!"
+
+# wrap existing storage
+require "redis-activesupport"
+redis = ActiveSupport::Cache::RedisStore.new("localhost:6379/0")
+translator = Mova::Translator.new(storage: redis)
+translator.get(:hi_from_redis, :en) #=> "Hi!"
+```
+
+## Documentation
+
+*link to rubydoc*
+
+## Design principles
+
+1.  **Translation and localization data should be decoupled.**
+
+    Localization info describes how dates, numbers, currencies etc. should be rendered,
+and what pluralization rules and writing direction should be used. This data is rarely if ever
+changed during project lifetime.
+
+    On the other hand translation data is always subject to change, because you may need to
+adjust text length to fit it into new design, update your product title to be more SEO friendly
+and so on.
+
+    It is more performant to keep localization data in a static Ruby class, rather then
+fetch it from a translation storage each time when we want to localize a date. This still
+allows to modify locales on per project level.
+
+    Ruby class is also a natural place for methods and collection data types, while procs and hashes
+being put into a translation storage feels awkward.
+
+2.  **Translations should be kept in a simple key-value storage.**
+
+    Simple storage means that given a string key it should return only a string or
+nil if nothing found. No object serialization. No hashes as a return value.
+
+    Such limitation allows to use almost anything as a storage: Ruby hash, file storage that maps
+to a hash, any RDMBS, any key-value store, or any combination of them.
+
+    This also forces decoupling of translation retrieval and translation management (finding
+untranslated strings, providing hints to translators etc.) since not much data can be put in a key.
+
+3.  **Translation framework should not be aware of any file format.**
+
+    If we need to import translations from a file, hash should be used as input format. No matter
+which file format is used to store data on a disk, whether it be YAML or JSON, or TOML, any option
+should work transparently.
+
+4.  **Exception should be used as a last resort when controlling flow.**
+
+    Raising and catching an exception in Ruby is a very expensive operation and should be avoided
+whenever possible.
+
+5.  **Instance is better than singleton.**
+
+    You can have separate versions of translator for models and templates. You can have different
+storages. You can use different interpolation rules.
+
+## Related projects
+
+* [mova-i18n][mova-i18n] - integrating with/replacing I18n.
+
+[mova-pronounce]: http://upload.wikimedia.org/wikipedia/commons/f/ff/Uk-%D0%BC%D0%BE%D0%B2%D0%B0.ogg
+[mova-i18n]: https://github.com/mova-rb/mova-i18n
+[i18n]: https://github.com/svenfuchs/i18n

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+task :default => :test
+task :test do
+  $LOAD_PATH.unshift("test")
+  Dir.glob("./test/**/*_test.rb").each { |file| require file}
+end

data/benchmarks/compare/locale_fallbacks.rb

@@ -0,0 +1,42 @@
+require "bundler/setup"
+require "benchmark/ips"
+require "securerandom"
+
+require "mova"
+require "i18n"
+require "r18n-core"
+
+mova = Mova::Translator.new.tap do |t|
+  def t.locales_to_try(locale)
+    [locale, :ru, :en]
+  end
+end
+mova.put(en: {hello: "Hello"}, uk: {hi: "Привіт"})
+
+I18n.enforce_available_locales = true
+I18n::Backend::Simple.include(I18n::Backend::Fallbacks)
+I18n.fallbacks[:uk] = [:uk, :ru, :en]
+I18n.backend.store_translations(:en, {hello: "Hello"})
+I18n.backend.store_translations(:uk, {hi: "Привіт"})
+I18n.locale = :uk
+
+module R18nHashLoader
+  def self.available; [R18n.locale("uk"), R18n.locale("ru"), R18n.locale("en")] end
+  def self.load(locale)
+    case locale.code
+    when "en" then {"hello" => "Hello"}
+    when "uk" then {"hi" => "Привіт"}
+    when "ru" then {}
+    end
+  end
+end
+R18n.default_places = R18nHashLoader
+R18n.set("uk")
+
+Benchmark.ips do |x|
+  x.report("mova") { mova.get(:hello, :uk) }
+  x.report("i18n") { I18n.t(:hello) }
+  x.report("r18n") { R18n.t.hello }
+
+  x.compare!
+end

data/benchmarks/compare/long_scope.rb

@@ -0,0 +1,48 @@
+require "bundler/setup"
+require "benchmark/ips"
+require "securerandom"
+
+require "mova"
+require "i18n"
+require "r18n-core"
+
+KEYS = Array.new(1000).map { SecureRandom.hex(8) }
+DATA = {
+  "this" => {
+    "is" => {
+      "really" => {
+        "deep" => {
+          "nested" => {
+            "key" => KEYS.each_with_object({}) { |key, memo| memo[key] = SecureRandom.hex(30) }
+          }
+        }
+      }
+    }
+  }
+}
+
+def random_key
+  KEYS.sample
+end
+
+mova = Mova::Translator.new
+mova.put(en: DATA)
+
+I18n.enforce_available_locales = true
+I18n.backend.store_translations(:en, DATA)
+I18n.locale = :en
+
+module R18nHashLoader
+  def self.available; [R18n.locale("en")] end
+  def self.load(locale); DATA end
+end
+R18n.default_places = R18nHashLoader
+R18n.set("en")
+
+Benchmark.ips do |x|
+  x.report("mova") { mova.get("this.is.really.deep.nested.key.#{random_key}", :en) }
+  x.report("i18n") { I18n.t("this.is.really.deep.nested.key.#{random_key}") }
+  x.report("r18n") { R18n.t.this.is.really.deep.nested.key.send(random_key) }
+
+  x.compare!
+end

data/benchmarks/each_vs_or.rb

@@ -0,0 +1,42 @@
+require "bundler/setup"
+require "benchmark/ips"
+
+storage1 = Object.new.tap do |s|
+  def s.get
+    nil
+  end
+end
+
+storage2 = Object.new.tap do |s|
+  def s.get
+    "result"
+  end
+end
+
+class Chain
+  attr_reader :storages
+
+  def initialize(*storages)
+    @storages = storages
+  end
+
+  def with_each
+    storages.each do |s|
+      result = s.get
+      return result if result
+    end
+  end
+
+  def with_or
+    storages[0].get || storages[1].get
+  end
+end
+
+chain = Chain.new(storage1, storage2)
+
+Benchmark.ips do |x|
+  x.report("each") { chain.with_each }
+  x.report("or") { chain.with_or }
+
+  x.compare!
+end

data/benchmarks/fallbacks_with_local_storage.rb

@@ -0,0 +1,21 @@
+require "bundler/setup"
+require "benchmark/ips"
+
+require "mova"
+require "mova/storage/memory"
+require "mova/read_strategy/eager"
+
+memory = Mova::Storage::Memory.new
+memory.write("en.mova_test", "Mova test")
+
+lazy = Mova::Translator.new(storage: memory)
+eager = Mova::Translator.new(storage: memory).tap do |t|
+  t.extend Mova::ReadStrategy::Eager
+end
+
+Benchmark.ips do |x|
+  x.report("lazy") { lazy.get(:mova_test, [:uk, :ru, :en]) }
+  x.report("eager") { eager.get(:mova_test, [:uk, :ru, :en]) }
+
+  x.compare!
+end

data/benchmarks/fallbacks_with_remote_storage.rb

@@ -0,0 +1,24 @@
+require "bundler/setup"
+require "benchmark/ips"
+require "active_support/notifications"
+require "active_support/cache"
+require "active_support/cache/strategy/local_cache"
+require "active_support/cache/dalli_store"
+
+require "mova"
+require "mova/read_strategy/eager"
+
+dalli = ActiveSupport::Cache::DalliStore.new("localhost:11211")
+dalli.write("en.mova_test", "Mova test")
+
+lazy = Mova::Translator.new(storage: dalli)
+eager = Mova::Translator.new(storage: dalli).tap do |t|
+  t.extend Mova::ReadStrategy::Eager
+end
+
+Benchmark.ips do |x|
+  x.report("lazy") { lazy.get(:mova_test, [:uk, :ru, :en]) }
+  x.report("eager") { eager.get(:mova_test, [:uk, :ru, :en]) }
+
+  x.compare!
+end

data/lib/mova.rb

@@ -0,0 +1,36 @@
+require "mova/scope"
+require "mova/read_strategy/lazy"
+require "mova/translator"
+
+module Mova
+  EMPTY_TRANSLATION = "".freeze
+
+  # @return [String] if translation is non-empty string
+  # @return [nil] if translation is nil or an empty string
+  #
+  # @example
+  #   Mova.presence("hello") #=> "hello"
+  #   Mova.presence(nil) #=> nil
+  #   Mova.presence("") #=> nil
+  #
+  # @note Unlike ActiveSupport's Object#presence this method doesn't
+  #   treat a string made of spaces as blank
+  #     "  ".presence #=> nil
+  #     Mova.presence("  ") #=> "  "
+  #
+  # @since 0.1.0
+  def self.presence(translation)
+    return nil if translation == EMPTY_TRANSLATION
+    translation
+  end
+
+  # Classes under this namespace must conform with
+  # {http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html ActiveSupport::Cache::Store} API.
+  #
+  # Instances must respond to at least #read, #read_multi, #write, #exist?, #clear. It is allowed #clear
+  # to be implemented as no-op.
+  module Storage; end
+
+  # Classes under this namespace must implement #call(String, Hash) and #missing_placeholder(Symbol, Hash).
+  module Interpolation; end
+end