simple_ar_localizer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 152ed9286c2d6f90a46dc350377dffca6cfc6bb1
+  data.tar.gz: 05e5020751b6edbfbe80b19a01c2feffb8c7053b
+SHA512:
+  metadata.gz: ffa8da686b8fbfe11da12add82f2453209ec1f8812ae19ab85ae140477d3b28997372a27ecbe92cde7ab602bd0e234b6bccc83eb6fa0343bc4f16b4807b7effc
+  data.tar.gz: e80d40c0c4fe167375f942691e79c77cd2d72966e165b1dde6de0404df171a7b8782bdac629ada89dc9054f1974fea55c2c077345412f91c72844c741d4e4afc

data/.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Defaults for all files
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true

data/.gitignore

@@ -0,0 +1,3 @@
+Gemfile.lock
+*.log
+*.gem

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in devise_account_expireable.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Jon Pearse
+
+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.textile

@@ -0,0 +1,85 @@
+h1. Simple AR Localizer
+
+SimpleARLocalizer is a gem that—hopefully—provides a slightly easier way of writing localisations for ActiveRecord models when splitting things out into per-model files.
+Out of the box, it provides hooks for a model’s human name, human attribute names, and both per-model and per-attribute error messaging.
+
+This means that instead of having:
+
+<pre># config/locales/foo/en.yml
+en:
+  activerecord:
+    models:
+      foo: model name
+
+    attributes:
+      foo:
+        attr_one: attribute name
+
+    errors:
+      models:
+        foo:
+          attributes:
+            attr_one:
+              blank: You need to fill this in
+</pre>
+
+You can instead use:
+
+<pre><code># config/locales/foo/en.rb
+SimpleARLocalizer::transform( Foo, :en, {
+  name: 'model name',
+  attributes: {
+    attr_one: {
+      name: 'attribute name',
+      errors: {
+        blank: 'You need to fill this in'
+      }
+    }
+  }
+})</code></pre>
+
+It’s still not exactly _pretty_, but it’s a little more descriptive and you’re less likely to put things in the wrong place/get your indents wrong.
+
+h2. Installation and using
+
+Add the following to your @Gemfile@ and run `bundle install`.
+
+<pre>gem 'simple_ar_localizer', '~> 1.0'</pre>
+
+Then, add the following in your @config/application.rb@:
+
+<pre># Also allow nested locale files
+config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]</pre>
+
+You should now be able to start using SimpleARLocalizer to generate your localisations, however it is important to note that this can only be used in Ruby files, rather than the YAML files to which you may be used.
+
+h3. Usage
+
+The main entry point is @SimpleARLocalizer::transform( model, language, l10n_data )@, which takes three arguments:
+
+- model _(String or Constant)_ := the model you’re localising, either as a string (eg: @'Foo'@) or as a constant
+- language _(Symbol)_ := ISO-639 language code of the language you’re providing a localisation for (eg: @:hu@)
+- l10n_data _(Hash)_ := the localisation data itself.
+
+The format of the localisation data is described "in its own file":doc/localisation_data.textile
+
+h3. Custom data formatting
+
+By design, this gem should cover ~90% of your localisation needs, but it also supports "custom data":doc/custom_data.textile if you need a little extra control.
+
+h2. A quick note about dialect/spelling
+
+Keen observers will note that I use US English (-ize) in the code, and British English (-ise) throughout comments and documentation: this is intentional.
+
+For better or worse, the world seems to have settled on US English as the de-facto standard for writing software and I have honoured (honored?) that in this gem. That said, however, it feels ‘wrong’ for me to use it when writing continuous prose, thus reverting to British English elsewhere. Sorry!
+
+h2. Version History
+
+*1.0.0 _(May 23rd, 2018)_*
+
+Extraction from the project whence it came and turning into a standalone gem.
+
+h2. @#include 'sales_pitch.h'@
+
+When I’m not hacking at random gems, I’m a freelance web developer specialising in all things front-end, based in the beautiful city of Cardiff, UK.
+I’m usually kept fairly busy with project work, but I’m always on the lookout for new people to do cool stuff with. "Drop me a line":mailto:hello@jonpearse.net – I’d love to hear from you!

data/doc/custom_data.textile

@@ -0,0 +1,80 @@
+h1. Custom localisation mapping
+
+Whilst the "defaults":./localisation_data.textile for SimpleARLocalizer are probably enough to cover the majority of things you’ll want to do with it, it also provides the ability to provide custom mappings from the localisation data hash to Rails I18n framework should you wish to extend its abilities.
+This includes overriding default rules, should they be a little limited.
+
+_(side note: this is how this gem came about—I needed a way of simply and easily localising a CMS which made heavy use of Rails’ inbuilt ‘human’ naming functionality, as well as labelling and messaging that could be localised on a per-model basis)_
+
+h2. Configuring custom rules
+
+In a Rails app, custom rules are added through the Rails configuration system:
+
+<pre><code>Rails.application.config.ar_localization_rules = {
+  …
+}</code></pre>
+
+This consists of a hash, where the keys are the pseudo-path within the localisation data hash (more on that in a moment), and the value is the Rails I18n key to which it should be mapped.
+
+Thus, the default @:name@ rule would be specified as:
+
+<pre><code>Rails.application.config.ar_localization_rules = {
+  'name': 'activerecord.models.%{model}'
+}</code></pre>
+
+h2. Specifying keys
+
+The mapping key is the nested keys from the incoming localisation data, separated by the forward slash (à lá XPath), thus given the localisation data:
+
+<pre>{
+  foo: {
+    bar: {
+      baz: 'value'
+    }
+  }
+}</pre>
+
+The key would be: @foo/bar/baz@
+
+h3. Interpolations
+
+The mapping parser understands interpolations, which work in a similar way to parameters in routes, for example the default rule for attribute names is specified as:
+
+<pre><code>  …
+  'attributes/:attr': 'activerecord.attributes.%{model}.%{attr}'
+  …</code></pre>
+
+The values of the interpolations (and indeed, the name of the model) can be used in the mapping, as shown above.
+
+h3. More complex mapping
+
+Sometimes you might want to do something more complex than simply taking a string from the localisation data and dropping it into a particular I18n key.
+SimpleARLocalizer allows multiple behaviours beyond a simple input–output mapping:
+
+A mapping value can be specified as an @Array@, which allows the mapping of a single item of localisation data to multiple I18n keys.
+
+<pre><code>  …
+  'foo/bar': [
+    'foo.bar.baz',
+    'qux.quux.quuz'
+  ]
+  …</code></pre>
+
+A mapping value can also be specified as a @Hash@, with members @key@ and @proc@:
+
+<pre><code>  …
+  'foo/bar': { key: 'foo.bar.baz', proc: ->(v){ v.uppercase }}
+  …</code></pre>
+
+This takes whatever is specified by @l10n_data[:foo][:bar]@, converts it to uppercase, and stores it in the I18n key @foo.bar.baz@.
+
+These can also be combined, for example, as a workaround for @Model.model_name.human@ not pluralising anything unless you explicitly tell it how to do so (which is irritating).
+
+<pre><code>  …
+  'name': [
+    'activerecord.models.%{model}.one',
+    { key: 'activerecord.models.%{model}.other', proc: ->(s){ s.pluralize }}
+  ]
+  …
+</code></pre>
+
+Will take the inbound name and stores it in the I18n key @activerecord.models.%{model}.one@, but also stores its plural form in @activerecord.models.%{model}.other@, and saves you having to do this manually.

data/doc/localisation_data.textile

@@ -0,0 +1,103 @@
+h1. Localisation data
+
+Localisation data is passed to SimpleARLocalizer as a nested hash, thus:
+
+<pre><code>SimpleARLocalizer::transform( Foo, :en, {
+  name: 'model name',
+  attributes: {
+    attr_one: {
+      name: 'attribute name',
+      errors: {
+        blank: 'You need to fill this in'
+      }
+    }
+  }
+})</code></pre>
+
+This file quickly documents how this works, and the options that are configured by default.
+
+Note that, by default, none of the hash members are required. Additionally, unconfigured members are simply ignored.
+
+h2. Model name: @name@
+
+_Mapped to @activerecord.models.%{model}@_
+
+This is used to specify the ‘human’ name for the model being localised (accessed via @Model.model_name.human@ ), and can be specified either as a string or a hash.
+Using a hash ties into "Rails’ default behaviour":http://guides.rubyonrails.org/i18n.html#translations-for-active-record-models with regard pluralisation, thus:
+
+<pre><code>SimpleARLocalizer::transform( Foo, :en, {
+  name: {
+    one: 'foo',
+    two: 'foos'
+  }
+})
+
+Foo.model_name.human( count: 1 ) # ‘foo’
+Foo.model_name.human( count: 2 ) # 'foos'
+</code></pre>
+
+SimpleARLocalizer also provides two aliases at this level: @:singular@ and @:plural@ which are mapped to @:one@ and @:other@ respectively. This is simply to make things a little clearer when defining localisations, especially who might not be quite as familiar with Rails’ I18n framework.
+
+As such, the two statements below are equal.
+
+<pre><code>SimpleARLocalizer::transform( Foo, :en, {
+  name: {
+    one: 'foo',
+    other: 'foos'
+  }
+})
+
+SimpleARLocalizer::transform( Foo, :en, {
+  name: {
+    singular: 'foo',
+    plural:   'foos'
+  }
+})</code></pre>
+
+h3. Side note on pluralisation
+
+If you intend to use @Model.model_name.human( count: x )@ in your code, Rails requires that you specify at least @:one@ and @:other@ for it to work properly. That is, if you just specify a single value, it’ll not pluralise it for you.
+There is a simple workaround for this in the "custom data"./custom_data.textile documentation.
+
+h2. Generic error messages: @errors@
+
+_Mapped to @activerecord.errors.models.%{model}@_
+
+This takes a @hash@, and is used to specify "validation error messages":http://guides.rubyonrails.org/active_record_validations.html on a per-model basis. A list of possible keys is available in "the appropriate Rails guide":http://guides.rubyonrails.org/i18n.html#error-message-interpolation
+
+<pre><code>SimpleARLocalizer::transform( Foo, :en, {
+  errors: {
+    blank: 'This is required',
+    invalid: 'That doesn’t look right to me…',
+    less_than: 'Must be less than %{count}'
+  }
+})
+</code></pre>
+
+h2. Model attributes: @attributes@
+
+*_Mapped to @activerecord.attributes.%{model}@ … kinda_*
+
+This is a hash, where each member relates to a particular attribute of your model. In its simplest form, each value is a simple string:
+
+<pre><code>SimpleARLocalizer::transform( Foo, :en, {
+  attributes: {
+    title: 'Title',
+    body:  'Body'
+  }
+})</code></pre>
+
+This provides localisation for the ‘human’ attribute name, accessed via @Model.human_attribute_name( attr )@
+
+However, SimpleARLocalizer also supports per-attribute error messages, in which case the value of each hash member should itself be a Hash.
+
+<pre><code>SimpleARLocalizer::transform( Foo, :en, {
+  attributes: {
+    title: {
+      name: 'Title',
+      errors: {
+        blank: 'You really need a title…'
+      }
+    }
+  }
+})</code></pre>

data/lib/simple_ar_localizer.rb

@@ -0,0 +1,14 @@
+require 'simple_ar_localizer/version'
+require 'simple_ar_localizer/map'
+require 'simple_ar_localizer/localizer'
+
+module SimpleARLocalizer
+
+  # Convenience accessort to SimpleARLocalizer::Localizer::transform()
+  def self.transform( model_name, language, l10n_data )
+
+    Localizer.transform( model_name, language, l10n_data )
+
+  end
+
+end

data/lib/simple_ar_localizer/localizer.rb

@@ -0,0 +1,171 @@
+require 'singleton'
+
+module SimpleARLocalizer
+
+  # Localizer provides a slightly easier way of hooking into the depths of Rails’ Internationalization functionality.
+  #
+  # By default, it allows you to specify the human name (with plurality), human attribute names, and any custom error messages
+  # on both a per-model and per-attribute level via a simple hash… rather than having to worry about exactly where things
+  # get nested in .YAML files.
+  #
+  # It takes a bit of explaining to start with, but should be way nicer in the long-run =)
+  class Localizer
+    include Singleton
+
+    # Constructor logic. This should not be called directly.
+    def initialize
+
+      @custom_rules = {}
+
+      # if we have a custom startup hook
+      if defined?( Rails ) and Rails.application.config.respond_to?( :ar_localization_rules )
+
+        @custom_rules = Rails.application.config.ar_localization_rules
+
+      end
+
+    end
+
+    # Does the actual translation from the nicely-formatted hash, to a more Rails i18n-friendly one.
+    #
+    # === Parameters
+    #
+    # [model_name]  the model we’re specifying localisations for
+    # [language]    the ISO-639 language code of the language we’re providing a localisation for
+    # [L10n_data]   a hash containing localisation data for the model/language combination
+    def self.transform( model_name, language, l10n_data )
+
+      self.instance.send( :perform_translation, model_name, language, l10n_data )
+
+    end
+
+    protected
+
+      # Callback from self.transform that actually does the work.
+      #
+      # === Parameters
+      #
+      # [model_name]  the model we’re specifying localisations for
+      # [language]    the ISO-639 language code of the language we’re providing a localisation for
+      # [L10n_data]   a hash containing localisation data for the model/language combination
+      def perform_translation( model_name, language, l10n_data )
+
+        # normalise the model name
+        model_name = model_name.name.underscore.to_sym if model_name.is_a?( Class )
+
+        # normalise the language, while we’re at it
+        language = language.to_sym unless language.is_a?( Symbol )
+
+        # compile our rules into a tree for easier matching
+        @rules = SimpleARLocalizer::DEFAULT_MAP.merge( @custom_rules ).deep_stringify_keys
+
+        # parse everything
+        parsed = deep_parse( l10n_data.deep_stringify_keys, { model: model_name })
+
+        # squish it out to a hash
+        hsh = {}
+        parsed.each{ |k,v| deep_assign( hsh, k, v ) }
+
+        # drop in the language and return
+        retval = {}
+        retval[language] = hsh
+        retval
+
+      end
+
+      # Performs the grunt work of recursing through the inbound array and turning it into a hash where keys are the
+      # dotted internationalization keys, and the values are the translated value for that key.
+      #
+      # === Parameters
+      #
+      # [data_in] the current level of the hash to parse
+      # [replacements] a hash containing values of tokens that should be replaced when generating internationalization keys
+      # [curr_path] the current path within the hash for use when looking up mapping values
+      def deep_parse( data_in, replacements, curr_path = '' )
+
+        # start a return value
+        retval = {}
+
+        # find some rules that match at this level
+        local_paths = @rules.keys
+        local_paths.select!{ |p| p.starts_with?( curr_path ) } unless curr_path.blank?
+
+        # finally, strip off any trailing stuff so we only have the current stub, then sort them so wildcards go at the end
+        local_paths = local_paths.map{ |p| p.gsub(curr_path, '').gsub(/\/(.*)/, '') }.uniq.sort.reverse
+
+        # now, stash some replacements somewhere
+        local_replacements = replacements.dup
+
+        # start iterating through keys at this level
+        data_in.each do |key, value|
+
+          # search for candidates
+          candidates = local_paths.select{ |p| ((p === key) or p.starts_with?( ':' )) }
+          next if candidates.empty?
+          matched_path = candidates.first
+
+          # if we’ve matched a symbol
+          local_replacements[matched_path[1..-1].to_sym] = key if matched_path.starts_with?( ':' )
+
+          # if it’s a hash, recurse
+          if value.is_a?( Hash )
+
+            retval.merge!( deep_parse( value, local_replacements, "#{curr_path}#{matched_path}/" ))
+
+          else
+
+            # do some substitution + cast to an array (so we can do multiple at once)
+            full_rule  = @rules["#{curr_path}#{matched_path}"]
+            full_rule  = [ full_rule ] unless full_rule.is_a?( Array )
+
+            # and then…
+            full_rule.each do |r|
+
+              # allow passing in more complex rules as hashes
+              if r.is_a?( Hash )
+
+                value = r['proc'].call( value )
+                r = r['key']
+
+              end
+
+              # write it to the array
+              retval[ r.gsub( /%\{(\w+)\}/ ){ |m| local_replacements[ $1.to_sym ] }] = value
+
+            end
+
+          end
+
+        end
+
+        # return the result
+        retval
+
+      end
+
+      def deep_assign( hsh, key, data )
+
+        # prepare for some recursion fun
+        target = hsh
+        path   = key.to_s.split( '.' ).map( &:to_sym )
+        final  = path.pop
+
+        # unravel stuff a bit
+        path.each do |k|
+
+          target[k] = {} unless target.key?( k )
+          target = target[k]
+
+        end
+
+        # push the final data…
+        target[final] = data
+
+        # … + return
+        hsh
+
+      end
+
+  end
+
+end

data/lib/simple_ar_localizer/map.rb

@@ -0,0 +1,21 @@
+module SimpleARLocalizer
+
+  # Default mapping from inbound localisation data to I18n keys. These can be supplemented/overridden via the
+  # <tt>Rails.application.config.ar_localization_rules</tt> configuration variable.
+  DEFAULT_MAP = {
+
+    # per-model stuff
+    'name':          'activerecord.models.%{model}',
+    'name/singular': 'activerecord.models.%{model}.one',
+    'name/plural':   'activerecord.models.%{model}.other',
+    'name/:key':     'activerecord.models.%{model}.%{key}',
+    'errors/:error': 'activerecord.errors.models.%{model}.%{error}',
+
+    # per-attribute stuff
+    'attributes/:attr':      'activerecord.attributes.%{model}.%{attr}', # only specifying a name
+    'attributes/:attr/name': 'activerecord.attributes.%{model}.%{attr}', # verbose specification
+    'attributes/:attr/errors/:error': 'activerecord.errors.models.%{model}.attributes.%{attr}.%{error}'
+
+  }
+
+end

data/lib/simple_ar_localizer/version.rb

@@ -0,0 +1,5 @@
+module SimpleARLocalizer
+
+  VERSION = '1.0.0'
+
+end

data/simple_ar_localizer.gemspec

@@ -0,0 +1,21 @@
+# encoding: UTF-8
+require File.expand_path('../lib/simple_ar_localizer/version', __FILE__)
+
+Gem::Specification.new do |gem|
+
+  gem.name          = 'simple_ar_localizer'
+  gem.summary       = 'Easier localisation for ActiveRecord models.'
+  gem.description   = 'Provides a (hopefully) simpler way of localising the human name, attribute names, and error message for ActiveRecord models.'
+  gem.version       = SimpleARLocalizer::VERSION
+
+  gem.files         = `git ls-files`.split($\)
+  gem.require_paths = [ 'lib' ]
+
+  gem.authors       = 'Jon Pearse'
+  gem.email         = 'hello@jonpearse.net'
+  gem.license       = 'MIT'
+  gem.homepage      = 'https://github.com/jonpearse/simple_ar_localizer'
+
+  gem.add_dependency( 'activerecord', '~> 5.1' )
+
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: simple_ar_localizer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jon Pearse
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-05-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+description: Provides a (hopefully) simpler way of localising the human name, attribute
+  names, and error message for ActiveRecord models.
+email: hello@jonpearse.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.textile
+- doc/custom_data.textile
+- doc/localisation_data.textile
+- lib/simple_ar_localizer.rb
+- lib/simple_ar_localizer/localizer.rb
+- lib/simple_ar_localizer/map.rb
+- lib/simple_ar_localizer/version.rb
+- simple_ar_localizer.gemspec
+homepage: https://github.com/jonpearse/simple_ar_localizer
+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.6.14
+signing_key: 
+specification_version: 4
+summary: Easier localisation for ActiveRecord models.
+test_files: []