mova 0.1.0

data/lib/mova/translator.rb

@@ -0,0 +1,183 @@
+module Mova
+  # Wrapper around a storage that provides key management and fallbacks.
+  #
+  # Translator knows that keys by definition are dot-separated and each key should
+  # include a locale. It also flattens any given hash, because ordinary key-value
+  # storage can handle only flat data.
+  #
+  # Translator is in charge of returning non-empty data for given set of locales and keys,
+  # because it is likely that some translations are missing.
+  #
+  # @since 0.1.0
+  class Translator
+    include ReadStrategy::Lazy
+
+    # @!attribute [r] storage
+    # Key-value storage for translations.
+    # @return [#read, #read_multi, #write, #exist?, #clear]
+    attr_reader :storage
+
+    module Overridable
+      # @param opts [Hash]
+      # @option opts [see #storage] :storage default: {Storage::Memory} instance
+      def initialize(opts = {})
+        @storage = opts.fetch(:storage) do
+          require "mova/storage/memory"
+          Storage::Memory.new
+        end
+      end
+
+      # @return [Array<String, Symbol>] locales that should be tried until non-empty
+      #   translation would be found.
+      # @param current_locale [String, Symbol]
+      #
+      # @example Override locale fallbacks
+      #   translator = Mova::Translator.new.tap do |t|
+      #     def t.locales_to_try(locale)
+      #       [locale, :en]
+      #     end
+      #   end
+      #   translator.put(en: {hello: "world"})
+      #   translator.get(:hello, :de) #=> "world"; tried "de.hello", then "en.hello"
+      def locales_to_try(current_locale)
+        [current_locale]
+      end
+
+      # @return [Array<String, Symbol>] keys that should be tried until non-empty
+      #   translation would be found.
+      # @param key [String, Symbol]
+      #
+      # @example Override key fallbacks
+      #   translator = Mova::Translator.new.tap do |t|
+      #     def t.keys_to_try(key)
+      #       [key, "errors.#{key}"]
+      #     end
+      #   end
+      #   translator.put(en: {errors: {fail: "Fail"}})
+      #   translator.get(:fail, :en) #=> "Fail"; tried "en.fail", then "en.errors.fail"
+      def keys_to_try(key)
+        [key]
+      end
+
+      # @return [String] default value if no translation was found.
+      # @param locales [Array<String>] that were used to find a translation.
+      # @param keys [Array<String>] that were used to find a translation.
+      # @param get_options [Hash{Symbol => Object}] that were passed to {#get}
+      #
+      # @example Override default value handling
+      #   translator = Mova::Translator.new.tap do |t|
+      #     def t.default(locales, keys, get_options)
+      #       "translation is missing"
+      #     end
+      #   end
+      #   translator.get("hello", :de) #=> "translation is missing"
+      def default(locales, keys, get_options)
+        EMPTY_TRANSLATION
+      end
+    end
+    include Overridable
+
+    # Retrieves translation from the storage or return default value.
+    #
+    # @return [String] translation or default value if nothing found
+    #
+    # @example
+    #   translator.put(en: {hello: "world"})
+    #   translator.get("hello", :en) #=> "world"
+    #   translator.get("bye", :en) #=> ""
+    #
+    # @example Providing the default if nothing found
+    #   translator.get("hello", :de, default: "nothing") #=> "nothing"
+    #
+    # @overload get(key, locale, opts = {})
+    #   @param key [String, Symbol]
+    #   @param locale [String, Symbol]
+    #
+    # @overload get(keys, locale, opts = {})
+    #   @param keys [Array<String, Symbol>] use this to redefine an array returned
+    #     by {#keys_to_try}.
+    #   @param locale [String, Symbol]
+    #
+    #   @example
+    #     translator.put(en: {fail: "Fail"})
+    #     translator.get(["big.fail", "mine.fail"], :en) #=> ""; tried "en.big.fail", then "en.mine.fail"
+    #
+    # @overload get(key, locales, opts = {})
+    #   @param key [String, Symbol]
+    #   @param locales [Array<String, Symbol>] use this to redefine an array returned
+    #     by {#locales_to_try}.
+    #
+    #   @example
+    #     translator.put(en: {hello: "world"})
+    #     translator.get(:hello, :de) #=> ""; tried only "de.hello"
+    #     translator.get(:hello, [:de, :en]) #=> "world"; tried "de.hello", then "en.hello"
+    #
+    #   @example Disable locale fallbacks locally
+    #     translator.put(en: {hello: "world"}) # suppose this instance has fallback to :en locale
+    #     translator.get(:hello, :de) #=> "world"; tried "de.hello", then "en.hello"
+    #     translator.get(:hello, [:de]) #=> ""; tried only "de.hello"
+    #
+    # @overload get(keys, locales, opts = {})
+    #   @param keys [Array<String, Symbol>]
+    #   @param locales [Array<String, Symbol>]
+    #
+    #   @note Keys fallback has a higher priority than locales one, that is, Mova
+    #     tries to find a translation for any given key and only then it fallbacks
+    #     to another locale.
+    #
+    # @param opts [Hash]
+    # @option opts [String] :default use this to redefine default value returned
+    #   by {#default}.
+    #
+    # @see #locales_to_try
+    # @see #keys_to_try
+    # @see #default
+    #
+    def get(key, locale, opts = {})
+      keys = resolve_scopes(key)
+      locales = resolve_locales(locale)
+      read_first(locales, keys) || opts[:default] || default(locales, keys, opts)
+    end
+
+    # Writes translations to the storage.
+    #
+    # @return [void]
+    # @param translations [Hash{String, Symbol => String, Hash}] where
+    #   root key/keys must be a locale
+    #
+    # @example
+    #   translator.put(en: {world: "world"}, uk: {world: "світ"})
+    #   translator.get("world", :uk) #=> "світ"
+    def put(translations)
+      Scope.flatten(translations).each do |key, value|
+        storage.write(key, value) unless storage.exist?(key)
+      end
+    end
+
+    # @see #put
+    #
+    # @return [void]
+    #
+    # @note This method overwrites existing translations.
+    def put!(translations)
+      Scope.flatten(translations).each do |key, value|
+        storage.write(key, value)
+      end
+    end
+
+    # @private
+    def inspect
+      "<##{self.class.name} storage=#{storage.inspect}>"
+    end
+
+    private
+
+    def resolve_locales(locale)
+      (locale if locale.is_a? Array) || locales_to_try(locale)
+    end
+
+    def resolve_scopes(key)
+      (key if key.is_a? Array) || keys_to_try(key)
+    end
+  end
+end

data/mova.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |spec|
+  spec.name          = "mova"
+  spec.version       = "0.1.0"
+  spec.authors       = ["Andrii Malyshko"]
+  spec.email         = ["mail@nashbridges.me"]
+  spec.summary       = "Translation and localization library"
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/mova-rb/mova"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/test/acceptance_test.rb

@@ -0,0 +1,22 @@
+require "test_helper"
+
+module Mova
+  class AcceptanceTest < Minitest::Test
+    def test_get
+      translator = Translator.new.tap do |t|
+        def t.locales_to_try(current_locale)
+          [current_locale, :en]
+        end
+      end
+
+      translator.put(en: {global: {hello: "world"}}, de: {hi: "Hallo"})
+
+      assert_equal "Hallo", translator.get(:hi, :de)
+      assert_equal "world", translator.get("global.hello", :de)
+      assert_equal "", translator.get("global.hello", [:de])
+      assert_equal "world", translator.get(["hello", "global.hello"], :en)
+      assert_equal "", translator.get(:nothing, :en)
+      assert_equal "nothing", translator.get(:nothing, :en, default: "nothing")
+    end
+  end
+end

data/test/interpolation/sprintf_test.rb

@@ -0,0 +1,60 @@
+require "test_helper"
+require "mova/interpolation/sprintf"
+
+module Mova
+  class SprintfTest < Minitest::Test
+    def interpolator
+      @interpolator ||= Interpolation::Sprintf.new
+    end
+
+    def test_no_placeholders_and_no_values
+      assert_equal "hi there!", interpolator.call("hi there!", {})
+    end
+
+    def test_no_placeholders_and_values
+      assert_equal "hi there!", interpolator.call("hi there!", subject: "people")
+    end
+
+    def test_replaced_placeholders
+      values = {subject: "people", type: "smart"}
+      assert_equal "hi there, smart people!", interpolator.call("hi there, %{type} %{subject}!", values)
+    end
+
+    def test_placeholder_and_extra_value
+      assert_equal "hi there, people!", interpolator.call("hi there, %{subject}!", subject: "people", type: "smart")
+    end
+
+    def test_placeholder_and_missing_value
+      values = {type: "smart"}
+      expect(interpolator).to receive(:missing_placeholder).with(:subject, values, "hi there, %{subject}!").and_return("<missing value>")
+      assert_equal "hi there, <missing value>!", interpolator.call("hi there, %{subject}!", values)
+    end
+
+    def test_escaped_placeholder
+      assert_equal "hi there, %{subject}!", interpolator.call("hi there, %%{subject}!", subject: "people")
+    end
+
+    def test_activesupport_safebuffer_like_strings
+      substring_class = Class.new(String) do
+        def gsub(*args, &blk)
+          to_str.gsub(*args, &blk)
+        end
+      end
+
+      string = substring_class.new("hi there, %{subject}!")
+      assert_equal "hi there, people!", interpolator.call(string, subject: "people")
+    end
+
+    def test_ruby_sprintf
+      assert_equal "1", interpolator.call("%<num>d", num: 1)
+      assert_equal "0b1", interpolator.call("%<num>#b", num: 1)
+      assert_equal "foo", interpolator.call("%<msg>s", msg: "foo")
+      assert_equal "1.000000", interpolator.call("%<num>f", num: 1.0)
+      assert_equal "  1", interpolator.call("%<num>3.0f", num: 1.0)
+      assert_equal "100.00", interpolator.call("%<num>2.2f", num: 100.0)
+      assert_equal "0x64", interpolator.call("%<num>#x", num: 100.0)
+      assert_raises(ArgumentError) { interpolator.call("%<num>,d", num: 100) }
+      assert_raises(ArgumentError) { interpolator.call("%<num>/d", num: 100) }
+    end
+  end
+end

data/test/mova_test.rb

@@ -0,0 +1,21 @@
+require "test_helper"
+
+module Mova
+  class MovaTest < Minitest::Test
+    def test_presence_nil
+      assert_nil Mova.presence(nil)
+    end
+
+    def test_presence_empty
+      assert_nil Mova.presence("")
+    end
+
+    def test_presence_non_empty
+      assert_equal "hello", Mova.presence("hello")
+    end
+
+    def test_presence_spaces_only
+      assert_equal "  ", Mova.presence("  ")
+    end
+  end
+end

data/test/read_strategy/eager_test.rb

@@ -0,0 +1,47 @@
+require "test_helper"
+require "mova/read_strategy/eager"
+
+module Mova
+  class EagerReadStrategyTest < Minitest::Test
+    include Test::Doubles
+
+    def translator_class
+      Struct.new(:storage) do
+        include ReadStrategy::Eager
+      end
+    end
+
+    def translator
+      @translator ||= translator_class.new(storage)
+    end
+
+    def test_read_first
+      expect(storage).to receive(:read_multi).with("de.hello").and_return("de.hello" => "Hallo")
+      assert_equal "Hallo", translator.read_first([:de], ["hello"])
+    end
+
+    def test_read_first_returns_nil_when_nothing_found
+      expect(storage).to receive(:read_multi).with("de.hello").and_return({})
+      assert_nil translator.read_first([:de], ["hello"])
+    end
+
+    def test_read_first_fallbacks_to_next_scope
+      expect(storage).to receive(:read_multi).with("de.hello", "de.hi").and_return("de.hi" => "Hallo")
+      assert_equal "Hallo", translator.read_first([:de], ["hello", "hi"])
+    end
+
+    def test_read_first_fallbacks_when_empty_result_in_storage
+      expect(storage).to receive(:read_multi).with("de.hello", "de.hi").and_return(
+        "de.hello" => "", "de.hi" => "Hallo"
+      )
+      assert_equal "Hallo", translator.read_first([:de], ["hello", "hi"])
+    end
+
+    def test_read_first_fallbacks_to_next_locale
+      expect(storage).to receive(:read_multi).with("de.hello", "de.hi", "en.hello", "en.hi").and_return(
+        "en.hello" => "Hello", "en.hi" => "hi"
+      )
+      assert_equal "Hello", translator.read_first([:de, :en], ["hello", "hi"])
+    end
+  end
+end

data/test/read_strategy/lazy_test.rb

@@ -0,0 +1,46 @@
+require "test_helper"
+
+module Mova
+  class LazyReadStrategyTest < Minitest::Test
+    include Test::Doubles
+
+    def translator_class
+      Struct.new(:storage) do
+        include ReadStrategy::Lazy
+      end
+    end
+
+    def translator
+      @translator ||= translator_class.new(storage)
+    end
+
+    def test_read_first
+      expect(storage).to receive(:read).with("de.hello") { "Hallo" }
+      assert_equal "Hallo", translator.read_first([:de], ["hello"])
+    end
+
+    def test_read_first_returns_nil_when_nothing_found
+      expect(storage).to receive(:read).with("de.hello") { nil }
+      assert_nil translator.read_first([:de], ["hello"])
+    end
+
+    def test_read_first_fallbacks_to_next_scope
+      expect(storage).to receive(:read).ordered.with("de.hello") { nil }
+      expect(storage).to receive(:read).ordered.with("de.hi") { "Hallo" }
+      assert_equal "Hallo", translator.read_first([:de], ["hello", "hi"])
+    end
+
+    def test_read_first_fallbacks_when_empty_result_in_storage
+      expect(storage).to receive(:read).ordered.with("de.hello") { "" }
+      expect(storage).to receive(:read).ordered.with("de.hi") { "Hallo" }
+      assert_equal "Hallo", translator.read_first([:de], ["hello", "hi"])
+    end
+
+    def test_read_first_fallbacks_to_next_locale
+      expect(storage).to receive(:read).ordered.with("de.hello") { nil }
+      expect(storage).to receive(:read).ordered.with("de.hi") { nil }
+      expect(storage).to receive(:read).ordered.with("en.hello") { "Hello" }
+      assert_equal "Hello", translator.read_first([:de, :en], ["hello", "hi"])
+    end
+  end
+end

data/test/scope_test.rb

@@ -0,0 +1,41 @@
+require "test_helper"
+
+module Mova
+  class ScopeTest < Minitest::Test
+    def test_join
+      assert_equal "hello.world", Scope.join("hello", "world")
+    end
+
+    def test_join_symbols
+      assert_equal "hello.world", Scope.join(:hello, :world)
+    end
+
+    def test_join_array
+      assert_equal "hello.world", Scope.join(["hello", "world"])
+    end
+
+    def test_split
+      assert_equal ["hello", "world"], Scope.split("hello.world")
+    end
+
+    def test_flatten_simple
+      expected = {"hello" => "world"}
+      assert_equal expected, Scope.flatten(hello: "world")
+    end
+
+    def test_flatten_with_one_root
+      expected = {"en.foo" => "bar", "en.inner.foo" => "bar"}
+      assert_equal expected, Scope.flatten(en: {foo: "bar", inner: {foo: "bar"}})
+    end
+
+    def test_flatten_with_multiple_roots
+      expected = {"en.foo" => "bar", "ru.foo" => "bar"}
+      assert_equal expected, Scope.flatten(en: {foo: "bar"}, ru: {foo: "bar"})
+    end
+
+    def test_cross_join
+      expected = ["de.hello", "de.hi", "en.hello", "en.hi"]
+      assert_equal expected, Scope.cross_join([:de, :en], ["hello", "hi"])
+    end
+  end
+end