i18n_lazy_scope 0.0.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18f90e57b24abf6b4891a68967366415def5e64b
-  data.tar.gz: fd2fb05699dfdb18f12e28083348cbb398962138
+  metadata.gz: 1b293b5d8ce8b2d9b36e0e6aa0f0bc5089782123
+  data.tar.gz: cd63978ec85c128b6386140a40f09d37d2cbdccb
 SHA512:
-  metadata.gz: 55e7b010ad2a2a504c89cefa0e4c34c3b230bd5da39e6f91e10630b8389b8ab8f6350f922dd913ab6e2967d0187d9394c859dac5f3fc167045707b72c0c20b19
-  data.tar.gz: 450537099d921b4b3d050c6a60dcc44cfa24e7a2d9133c3cb3027bb0316bc4d2d3316dd27dae721227f3ff96565370b414f5955f9da0061ec60148980c2eddd5
+  metadata.gz: 016a2424f4540b1fdbc24d5822bdb46075b0f5dcf5e217b1a350d79c0024ba09acfc00e2c42f9f3ae3c7337b14f6c59f2d29cb41281c447b6202224241ef55b3
+  data.tar.gz: a9ebaad147eead7f833fbc4b2d3bdb1b4646b2e966481b492301d7952d0b84224cb01d9ba3709adc019c64d71e62887c0e0bbe0c010a8c5fb0f2c6eed32c8153

data/README.md

@@ -1,81 +1,57 @@
 # I18nLazyScope
 
-I18nLazyScope is a tiny library that lets you use lazy lookup and keep a better structure for your locale files when localising strings in your Ruby applications. This means quicker translations without sacrificing the structure of your locale files.
+I18nLazyScope is a tiny library that lets you use lazy lookup and custom scoping in your locale files when localising strings in your Ruby applications. This means quicker translations without sacrificing the structure of your locale files.
 
-```ruby
-# users_controller#create
-redirect_to @user, notice: scoped_t('welcome_message')
-```
+The library inserts a customisable namespace in the scope for you, just below the locale. The following table illustrates the difference between I18nLazyLookup and Rails when resolving lazy lookup keys.
 
-```yaml
-en:
-  controllers: # <- Oh, look, it's a controller scope with lazy lookup! Yay!
-    users:
-      create:
-        welcome_message: "You are such a star!"
-```
+|             | I18nLazyLookup                                       | Rails/I18n Lazy Lookup
+| ------------|------------------------------------------------------|------------------------------------------|
+| Controllers | `locale.controllers.controller_name.action_name.key` | `locale.controller_name.action_name.key` |
+| Mailers     | `locale.mailers.mailer_name.action_name.key`         | `locale.mailer_name.action_name.key`     |
+| Views       | `locale.views.template_or_partial_path.key`          | `locale.template_or_partial_path.key`    |
 
-I18nLazyScope provides a wrapper method around the `translate` and `t` methods in Rails and the Ruby [I18n][3] gem.
 
-## What Problem Does This Solve
+## What's Lazy Lookup?
 
-Imagine you are in the `users_controller#show` action, and you want to flash a localised welcome message.
+[Lazy lookup][1] is a feature that ships with Rails and the [I18n][3] gem. It allows you to translate strings without explicitly qualifying their entire scope. For example, consider the following code that lives in `show.html.erb` inside `app/views/users`, and that your application's locale is English.
 
-```ruby
-def create
-  if @user.save
-    redirect_to @user, notice: t('welcome_message')
-  end
-end
+```erb
+<%= t('.welcome_message') %>
 ```
 
-This scopes the translation to `locale.welcome_message`. If your current--or default--locale is English, the corresponding key in your locale file would be `en.welcome_message`.
-
-Oh dear! This is an awful way to structure translations. You want to scope them instead. You create a key in your locale file.
+Rails automatically converts `.welcome_message` to `en.users.show.welcome_message`. This saves you from having to type `users.show`, which is handy if you have lots of translations. But it forces you structure your locale files the way Rails prefers.
 
 ```yaml
 en:
-  controllers:
-    users:
-      create:
-        welcome_message: "You are such a star!"
+  users:
+    show:
+      welcome_message: "You are such a star!"
 ```
 
-And you add the key to your code.
+The above structure can get messy because `en.users` can refer to a view or a controller, and it feels wrong for `users` to be floating under the top level namespace. Most developers prefer to keep their translations under a scope.
 
-```ruby
-redirect_to @user, notice: t('controllers.users.create.welcome_message')
+```yaml
+en:
+  controllers:
+    users:
+      show:
+        success: "Yay!"
+  views:
+    users:
+      show:
+        welcome_message: "Yay!"
 ```
 
-Holy Semantics, Batman! `controllers.users.create` is a lot to type before each key name. And after some time you tire of typing it repeatedly. You read the documentation and discover [lazy lookup][1]--brilliant. You decide to use it, and diligently place a dot before your key name.
+So applications with lots of translations will find it hard to take advantage of lazy lookup. Wouldn't it be great if you could use lazy lookup and a custom namespace? Well, now you can.
 
-```ruby
-redirect_to @user, notice: t('.welcome_message')
+```erb
+<%= t_scoped('welcome_message') %>
 ```
 
-Soon after, when testing, you discover that you have a `translation missing` error in your template. This is because lazy lookup will scope the translation to `en.users.create.welcome_message`. The neat `controller` namespace we created is missing.
-
-You have two choices:
-
-1. Change the structure of your locale file to match how lazy lookup works.
-2. Use verbose, fully qualified scopes.
+The `scoped_t` method will automatically convert `welcome_message` to `en.views.show.welcome_message`. And you can customise the `views` part of the scope to anything you like. Your locale file would contain the `views` namespace to keep view translations organised as demonstrated above.
 
-Option one might cause your locale file to become a mess, or worse, cause namespace collisions because views and controllers share part of the namespace: `en.users`. And option two is annoying to type all the time.
+I18nLazyScope provides a wrapper method around the `translate` and `t` methods in Rails and the Ruby I18n gem.
 
-**I18nLazyScope** lets you use lazy lookup and keep a better structure for your locale files.
-
-```erb
-redirect_to @user, notice: scoped_t('welcome_message')
-
-```
-
-```yaml
-en:
-  controllers: # or mailers, views, or, whatever you want
-    users:
-      create:
-        welcome_message: "You are such a star!"
-```
 
 ## Installation
 
@@ -95,7 +71,7 @@ Or install it yourself as:
 
 ## Usage
 
-Call the `t_scoped` method instead of `t`, or `translate`, and make sure you have the corresponding keys in your locale file. Say you are in `app/views/users/show.html.erb`.
+Call the `t_scoped` method instead of `t`, or `translate`, and make sure you have the corresponding keys in your locale files. Say you are in `app/views/users/show.html.erb`.
 
 ```erb
 <%= t_scoped 'greeting' %>
@@ -109,12 +85,27 @@ en:
        greeting: "Hello!"
 ```
 
-The library inserts a top level name in the scope for you. You will be able to customise this in future releases, but for now, the scopes default to:
+The library inserts a top level name in the scope for you. Here are the defaults:
 
 1. Conrollers: `locale.controllers.controller_name.action_name.key`
 2. Mailers: `locale.mailers.mailer_name.action_name.key`
 3. Views: `locale.views.template_or_partial_path.key`
 
+### Customising the Namespace
+
+I18nLazyScope accepts a configuration block. This is an example that you might put into a Rails initializer at `config/initializers/i18n_lazy_scope.rb`:
+
+```ruby
+I18nLazyScope.configure do |config|
+  # Resolves lazy lookup to `locale.my.custom.scope.controller_name.action_name.key`
+  config.action_controller_scope = [:my, :custom, :scope]
+  # Resolves lazy lookup to `locale.my.custom.scope.mailer_name.action_name.key`
+  config.action_mailer_scope     = [:my, :custom, :scope]
+  # Resolves lazy lookup to `locale.my.custom.scope.template_or_partial_path.key`
+  config.action_view_scope       = [:my, :custom, :scope]
+end
+```
+
 ### Interpolation
 
 It works exactly as it would if you call `t` or `translate`.
@@ -131,12 +122,10 @@ en:
        greeting: "Hello, %{name}!"
 ```
 
-### Scoping
+### A Note on Scoping
 
 If you have to customise the scope on individual basis, then you should use `t` and `translate` that ship with Rails or the [I18n][3] gem. Scoping on individual basis defeates the point of this gem. This gem isn't meant to replace the I18n; it's a tiny wrapper that depends on it.
 
-In future releases you will be able to customise top level namespaces, such as `views`, `controllers`, `mailers`, etc.
-
 ## API
 
 ```ruby
@@ -147,6 +136,10 @@ t_scoped(key, **args)
 
 I18nLazyScope requires Ruby 2.0 because it uses the [double splat `**` operator][2] to capture all keyword arguments.
 
+## Version
+
+I18nLazyScope uses semantic versioning.
+
 ## Contributing
 
 1. Fork it ( https://github.com/abitdodgy/i18n_lazy_scope/fork )

data/lib/i18n_lazy_scope.rb

@@ -1,4 +1,6 @@
 require "i18n_lazy_scope/version"
+require "i18n_lazy_scope/configuration"
+
 require "i18n_lazy_scope/railtie" if defined?(Rails)
 
 begin
@@ -7,4 +9,15 @@ rescue LoadError
 end
 
 module I18nLazyScope
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
 end

data/lib/i18n_lazy_scope/action_controller/helper.rb

@@ -1,7 +1,7 @@
 module I18nLazyScope::ActionController
   module Helper
     def lazy_scope
-      [:controllers, controller_name, action_name]
+      [*I18nLazyScope.configuration.action_controller_scope, controller_name, action_name]
     end
   end
 end

data/lib/i18n_lazy_scope/action_mailer/helper.rb

@@ -1,7 +1,7 @@
 module I18nLazyScope::ActionMailer
   module Helper
     def lazy_scope
-      [:mailers, mailer_name, action_name]
+      [*I18nLazyScope.configuration.action_mailer_scope, mailer_name, action_name]
     end
   end
 end

data/lib/i18n_lazy_scope/action_view/helper.rb

@@ -1,7 +1,7 @@
 module I18nLazyScope::ActionView
   module Helper
     def lazy_scope
-      [:views, view_path]
+      [*I18nLazyScope.configuration.action_view_scope, view_path]
     end
 
   private

data/lib/i18n_lazy_scope/configuration.rb

@@ -0,0 +1,11 @@
+module I18nLazyScope
+  class Configuration
+    attr_accessor :action_controller_scope, :action_mailer_scope, :action_view_scope
+
+    def initialize
+      @action_controller_scope = [:controllers]
+      @action_mailer_scope = [:mailers]
+      @action_view_scope = [:views]
+    end
+  end
+end

data/lib/i18n_lazy_scope/version.rb

@@ -1,3 +1,3 @@
 module I18nLazyScope
-  VERSION = "0.0.3"
+  VERSION = "1.0.0"
 end

data/spec/i18n_lazy_scope/action_controller/helper_spec.rb

@@ -1,17 +1,5 @@
 require "spec_helper"
 
-class FakeController
-  include I18nLazyScope::ActionController::Helper
-  include I18nLazyScope::Helper
-
-  def t(*args)
-    I18n.t(*args)
-  end
-
-  def controller_name; :users; end
-  def action_name;     :show;  end
-end
-
 describe FakeController do
   before :each do
     @controller = FakeController.new

data/spec/i18n_lazy_scope/action_mailer/helper_spec.rb

@@ -1,17 +1,5 @@
 require "spec_helper"
 
-class FakeMailer
-  include I18nLazyScope::ActionMailer::Helper
-  include I18nLazyScope::Helper
-
-  def t(*args)
-    I18n.t(*args)
-  end
-
-  def mailer_name; :user_mailer;   end
-  def action_name; :welcome_email; end
-end
-
 describe FakeMailer do
   before :each do
     @mailer = FakeMailer.new

data/spec/i18n_lazy_scope/action_view/helper_spec.rb

@@ -1,21 +1,5 @@
 require "spec_helper"
 
-class FakeView
-  include I18nLazyScope::ActionView::Helper
-  include I18nLazyScope::Helper
-
-  def initialize
-    @virtual_path = 'users.show.user_profile'
-  end
-
-  def t(*args)
-    I18n.t(*args)
-  end
-
-  def controller_name; :users; end
-  def action_name;     :show;  end
-end
-
 describe FakeView do
   before :each do
     @view = FakeView.new

data/spec/i18n_lazy_scope/configuration_spec.rb

@@ -0,0 +1,53 @@
+require "spec_helper"
+
+module I18nLazyScope
+  describe Configuration do
+    describe "#action_controller_scope" do
+      it "defaults to [:controllers]" do
+        scope = Configuration.new.action_controller_scope
+        expect(scope).to eq([:controllers])
+      end
+    end
+
+    describe "#action_controller_scope=" do
+      it "sets a value" do
+        config = Configuration.new
+        config.action_controller_scope = [:my, :controller, :scope]
+        scope = config.action_controller_scope
+        expect(scope).to eq([:my, :controller, :scope])
+      end
+    end
+
+    describe "#action_mailer_scope" do
+      it "defaults to [:mailers]" do
+        scope = Configuration.new.action_mailer_scope
+        expect(scope).to eq([:mailers])
+      end
+    end
+
+    describe "#action_mailer_scope=" do
+      it "sets a value" do
+        config = Configuration.new
+        config.action_mailer_scope = [:my, :mailer, :scope]
+        scope = config.action_mailer_scope
+        expect(scope).to eq([:my, :mailer, :scope])
+      end
+    end
+
+    describe "#action_view_scope" do
+      it "defaults to [:views]" do
+        scope = Configuration.new.action_view_scope
+        expect(scope).to eq([:views])
+      end
+    end
+
+    describe "#action_view_scope=" do
+      it "sets a value" do
+        config = Configuration.new
+        config.action_view_scope = [:my, :view, :scope]
+        scope = config.action_view_scope
+        expect(scope).to eq([:my, :view, :scope])
+      end
+    end
+  end
+end

data/spec/i18n_lazy_scope/i18n_lazy_scope_spec.rb

@@ -0,0 +1,30 @@
+require "spec_helper"
+
+module I18nLazyScope
+  describe I18nLazyScope do
+    describe "#configure" do
+      before do
+        I18nLazyScope.configure do |config|
+          config.action_controller_scope = %i(my scope)
+          config.action_mailer_scope = %i(my scope)
+          config.action_view_scope = %i(my scope)
+        end
+      end
+
+      it "sets custom controller scope" do
+        controller = FakeController.new
+        expect(controller.lazy_scope).to eq [:my, :scope, :users, :show]
+      end
+
+      it "sets custom mailer scope" do
+        mailer = FakeMailer.new
+        expect(mailer.lazy_scope).to eq [:my, :scope, :user_mailer, :welcome_email]
+      end
+
+      it "sets custom view scope" do
+        view = FakeView.new
+        expect(view.lazy_scope).to eq [:my, :scope, "users.show.user_profile"]
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,8 +1,15 @@
+require "i18n_lazy_scope"
+
 require "i18n_lazy_scope/action_controller/helper"
 require "i18n_lazy_scope/action_mailer/helper"
 require "i18n_lazy_scope/action_view/helper"
 
 require "i18n_lazy_scope/helper"
+require "i18n_lazy_scope/configuration"
+
+require "support/fake_controller"
+require "support/fake_mailer"
+require "support/fake_view"
 
 require "i18n"
 

data/spec/support/fake_controller.rb

@@ -0,0 +1,16 @@
+class FakeController
+  include I18nLazyScope::ActionController::Helper
+  include I18nLazyScope::Helper
+
+  def t(*args)
+    I18n.t(*args)
+  end
+
+  def controller_name
+    :users
+  end
+
+  def action_name
+    :show
+  end
+end

data/spec/support/fake_mailer.rb

@@ -0,0 +1,16 @@
+class FakeMailer
+  include I18nLazyScope::ActionMailer::Helper
+  include I18nLazyScope::Helper
+
+  def t(*args)
+    I18n.t(*args)
+  end
+
+  def mailer_name
+    :user_mailer
+  end
+
+  def action_name
+    :welcome_email
+  end
+end

data/spec/support/fake_view.rb

@@ -0,0 +1,20 @@
+class FakeView
+  include I18nLazyScope::ActionView::Helper
+  include I18nLazyScope::Helper
+
+  def initialize
+    @virtual_path = 'users.show.user_profile'
+  end
+
+  def t(*args)
+    I18n.t(*args)
+  end
+
+  def controller_name
+    :users
+  end
+
+  def action_name
+    :show
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: i18n_lazy_scope
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Mohamad El-Husseini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-24 00:00:00.000000000 Z
+date: 2015-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -100,14 +100,20 @@ files:
 - lib/i18n_lazy_scope/action_controller/helper.rb
 - lib/i18n_lazy_scope/action_mailer/helper.rb
 - lib/i18n_lazy_scope/action_view/helper.rb
+- lib/i18n_lazy_scope/configuration.rb
 - lib/i18n_lazy_scope/helper.rb
 - lib/i18n_lazy_scope/railtie.rb
 - lib/i18n_lazy_scope/version.rb
 - spec/i18n_lazy_scope/action_controller/helper_spec.rb
 - spec/i18n_lazy_scope/action_mailer/helper_spec.rb
 - spec/i18n_lazy_scope/action_view/helper_spec.rb
+- spec/i18n_lazy_scope/configuration_spec.rb
+- spec/i18n_lazy_scope/i18n_lazy_scope_spec.rb
 - spec/spec_helper.rb
 - spec/support/en.yml
+- spec/support/fake_controller.rb
+- spec/support/fake_mailer.rb
+- spec/support/fake_view.rb
 homepage: ''
 licenses:
 - MIT
@@ -136,5 +142,10 @@ test_files:
 - spec/i18n_lazy_scope/action_controller/helper_spec.rb
 - spec/i18n_lazy_scope/action_mailer/helper_spec.rb
 - spec/i18n_lazy_scope/action_view/helper_spec.rb
+- spec/i18n_lazy_scope/configuration_spec.rb
+- spec/i18n_lazy_scope/i18n_lazy_scope_spec.rb
 - spec/spec_helper.rb
 - spec/support/en.yml
+- spec/support/fake_controller.rb
+- spec/support/fake_mailer.rb
+- spec/support/fake_view.rb