trendi18n 0.9.1 → 0.9.2

data/README.rdoc

@@ -1,6 +1,14 @@
 = Introduction
 
-Trendi18n is database backend for Rails' i18n.  Trendi18n offers some administration functionality, which offers:
+Trendi18n is database backend for Rails' i18n.
+
+Default backend provided by Rails is a great and simple solution. It is however developer oriented: keeps translations in the files, require repository access for translators and their supervision.
+
+Trendi18n is targeted at projects where translation must be part of administration interface and where it should be possible to modify translations in live application.
+
+= Features
+
+Trendi18n offers some administration functionality, which offers:
 
 * paginated list of translations in database (with locale and translation status conditions)
 * autoassigned status for translations:
@@ -14,6 +22,79 @@ Trendi18n is database backend for Rails' i18n.  Trendi18n offers some administra
 
 Real-time updating store_translations
 
+= Install
+
+Trendi18n is hosted on gemcutter. Add gemcutter to your gems source and type:
+
+    gem install trendi18n
+
+= How to use
+
+If you want to use trendi18n in your app you should do three steps:
+
+* Add to apps config/environment.rb file:
+
+    config.gem "trendi18n", :lib => false
+
+* Run trendi18n generator. Type in your app main directory:
+
+    ruby script/generate trendi18n
+
+* Add to your ApplicationController:
+
+    include Trendi18n::Handler
+
+= Changelog
+
+=== 0.9.2
+
+* Backend reloading system (multi-threading supported)
+* Getting info of available locales system (multi-threading supported)
+* More documentation
+* Nicer structure of files and directories in lin directory
+
+= How it works
+
+Trendi18n is still supporting default source of translations - localizations files.
+This translations are loaded to standard I18n::Backend::Simple translation store
+system (called 'cache'). When I18n.translate is used:
+
+* First of all, trendi18n lookup translation in cache.
+* If translation is not found in cache then trendi18n lookup translation in db (using Translation model) and add it to cache
+* If translation is not found in db then create empty translation in db (and add it to cache)
+
+=== Translation model
+
+The soul of trendi18n is Translation model used for storing translations in db. If you have naver used rails i18n, you should first read guide: http://guides.rubyonrails.org/i18n.html
+This list of translation's fields (with short description) should be useful:
+
+* *key* - used to identification translation
+* *locale* - locale of translation
+* *scope* - used to identification translation. The same key can be located in various scopes, so there we be various translations. Simply, scope is something like prefix for key. Use dot to separate subscopes
+* *default* - return where there is no translation for this key
+* *translation* - standard translation for this key
+* *zero* - "plural" form of translation, when count is used and it equals 0
+* *one* - "plural" form of translation, when count is used and it equals 1
+* *many* - "plural" form of translation, when count is used and it's greater then 1
+* *few* - currently not used "plural" form of translation, when count is used and it's greater then 1 but smaller then "few + 1"
+* *state* - state of translation. Available values
+
+    * new - new translation
+    * unfinished - translation with some plural forms
+    * finished - finished translation
+
+* *timestamps*
+
+You should use Translation model to managing translations stored in database.
+
+=== Getting more
+
+You can get more information about trendi18n reading our documentation and source
+
+= Bugs, new features etc.
+
+If you find some bugs or you think trendi18n should do something differently or has new features please open new issue on github: http://github.com/bragi/trendi18n/issues
+
 = Copyright
 
 Copyright © 2009 Łukasz Piestrzeniewicz. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.9.1
+0.9.2

data/app/models/translation.rb

@@ -1,8 +1,6 @@
 class Translation < ActiveRecord::Base
   before_validation :set_state
   before_validation :set_defaults
-  after_save :reload_backend
-
 
   named_scope :untranslated, :conditions => {:state => %w(new unfinished)}
   named_scope :translated, :conditions => {:state => "finished"}
@@ -14,19 +12,50 @@ class Translation < ActiveRecord::Base
 
   @@locales = []
 
-   # return locales if their exists and translations are up-to-date. In other case assign are locales values from db to locales and return this value
+   # return locales which translations are stored in db
   def self.get_locales
     @@locales
   end
 
+  # read locales which translation are stored in db
   def self.set_locales
     @@locales = self.all(:select => "DISTINCT(locale)", :order => "locale ASC").map { |obj| obj.locale  }
   end
 
-  # This method is running after save translation into db and it is reloading I18n backend (trendi18n)
-  def reload_backend
-    I18n.backend.reload!
-    Translation.set_locales
+  # Set @read_time, date and time of first database read on current update.
+  # @read_time is used to get translations cache up-to-date status
+  def self.set_read_time
+    @read_time = Time.zone.now if @read_time.nil?
+  end
+
+  # Clear value of @read_time. It is used durnig backend reload!
+  def self.clear_read_time
+    @read_time = nil
+  end
+
+  # Return date and time of last translations update in database. It is used to get
+  # translations cache up-to-date status and we need to reload backend only after
+  # update existing translations (new translations will be cached when they will be used
+  # first time), so we are looking for the biggest update time in translations that
+  # updated_at is greater then created_at
+  def self.update_time
+    self.exists?(["updated_at > created_at"]) ? self.first(:conditions => "updated_at > created_at", :order => "updated_at DESC").updated_at : Time.zone.at(0)
+  end
+
+  def self.update_locales_time
+    self.exists? ? self.first(:order => "updated_at DESC").updated_at : Time.zone.at(0)
+  end
+
+  # Checking translations cache up-to-date status. We need to reload backend when
+  # cache is not up-to-date. It's going on when so existing translation was updated.
+  # We can't reload backend using after_update callback becouse there can be many
+  # proccesses running our apps and all of them must be reloaded, not only the updater.
+  def self.up_to_date?
+    @read_time.nil? ? true : self.update_time.to_i < @read_time.to_i
+  end
+
+  def self.locales_up_to_date?
+    @read_time.nil? ? true : self.update_locales_time.to_i < @read_time.to_i
   end
 
   # auto-magic finder using string normalized key to find translation. The first value in scope is the locale, the last is the key and all between are scopes
@@ -53,25 +82,6 @@ class Translation < ActiveRecord::Base
     self.translation = nil if self.translation.blank? # set nil to translation if it is blank (empty string)
   end
 
-  # time of the last db update
-  def self.base_updated_at
-    self.exists?(["updated_at > created_at"]) ? self.first(:order => "updated_at DESC", :conditions => "updated_at > created_at").updated_at : Time.at(0)
-  end
-
-   # time of the db read on current db update
-  def self.read_base
-    @base_read_at = Time.zone.now if @base_read_at.nil?
-  end
-
-  def self.clear_base_read_at
-    @base_read_at = nil
-  end
-
-   # db is up-to-date when it wasn't read or read time is larger then update time
-  def self.up_to_date?
-    @base_read_at.nil? || @base_read_at.to_i > self.base_updated_at.to_i
-  end
-
   # don't be nil if there is "{{count}}" in key
   def with_count?
     /\{\{count\}\}/.match(self.key)
@@ -102,7 +112,6 @@ class Translation < ActiveRecord::Base
 
   # look up for translation and return it, if exists, or create if not
   def self.lookup(locale, key, default = nil, scope = nil)
-    self.read_base
     scope = I18n.send(:normalize_translation_keys, locale, key, scope)
     locale = scope.delete_at(0).to_s
     key = scope.delete_at(scope.size - 1).to_s

data/lib/{trendi18n.rb → trendi18n/backend/trendi18n.rb}

@@ -3,17 +3,20 @@ module Trendi18n
   module Backend
 
     class Trendi18n < I18n::Backend::Simple
-      delegate :up_to_date?, :to => Translation # delgate up_to_date? method to Translation model
+
+      delegate :up_to_date?, :to => Translation
+      delegate :locales_up_to_date?, :to => Translation
 
       # return available locales, based on informaton form Translation model
       def available_locales
+        Translation.set_read_time
         Translation.get_locales
       end
 
       # translate key in locale using options
       def translate(locale, key, options = {})
         raise InvalidLocale.new(locale) if locale.nil?
-
+        Translation.set_read_time
         #if key is an array then as a result run yourself for all subkey in key
         return key.map { |subkey| translate(locale, subkey, options)} if key.is_a?(Array)
 
@@ -37,10 +40,13 @@ module Trendi18n
         entry = interpolate(locale, entry, values) # run interpolation for translation
       end
 
-
       def reload!
-        super # run standard I18n::Backend::Simple reload! method
-        Translation.clear_base_read_at # and clear information about time of last translation's base read
+        super
+        Translation.clear_read_time
+      end
+
+      def locales_reload!
+        Translation.set_locales
       end
 
       protected

data/lib/trendi18n/handler.rb

@@ -0,0 +1,17 @@
+module Trendi18n
+  module Handler
+
+    def self.included(subclass)
+      subclass.class_eval do
+        before_filter :translations_cache_updater
+
+        # check translations cache up-to-date status and reload backend or/and locales when needed
+        def translations_cache_updater
+          I18n.backend.reload! unless I18n.backend.up_to_date?
+          I18n.backend.locales_reload! unless I18n.backend.locales_up_to_date?
+        end
+      end
+    end
+
+  end
+end

data/rails/init.rb

@@ -1,5 +1,9 @@
-require 'trendi18n'
-require "commands"
+require 'trendi18n/backend/trendi18n'
+require 'trendi18n/generator/commands'
+require 'trendi18n/handler'
 require 'file'
 
-I18n.backend = Trendi18n::Backend::Trendi18n.new
+I18n.backend = Trendi18n::Backend::Trendi18n.new
+
+
+

data/spec/test_application/app/controllers/application_controller.rb

@@ -5,6 +5,8 @@ class ApplicationController < ActionController::Base
   helper :all # include all helpers, all the time
   protect_from_forgery # See ActionController::RequestForgeryProtection for details
 
+  include Trendi18n::Handler
+
   # Scrub sensitive parameters from your log
   # filter_parameter_logging :password
 end

data/spec/test_application/app/controllers/translations_controller.rb

@@ -5,6 +5,10 @@ class TranslationsController < ApplicationController
     @translations = Translation.localization(params[:localization]).send(params[:condition].downcase.to_sym) if ["untranslated", "translated", "all"].include?(params[:condition].downcase)
   end
 
+  def locales_list
+    @locales = I18n.backend.available_locales
+  end
+
   def new
     @translation = Translation.new
   end

data/spec/test_application/app/views/translations/edit.html.erb

@@ -1,6 +1,6 @@
 <%= error_messages_for 'translation' %>
 
-<% form_for @translation, :url => {:action => "update"} do  %>
+<% form_for @translation do  %>
     <%= render :partial => "form" %>
     <%= submit_tag("Save") %>
 <% end %>

data/spec/test_application/app/views/translations/locales_list.html.erb

@@ -0,0 +1,5 @@
+<ul>
+  <% for locale in @locales %>
+    <li /><%= h locale %>
+  <% end %>
+</ul>

data/spec/test_application/config/routes.rb

@@ -39,7 +39,7 @@ ActionController::Routing::Routes.draw do |map|
   # Note: These default routes make all actions in every controller accessible via GET requests. You should
   # consider removing or commenting them out if you're using named routes and resources.
 
-  map.resources :translations
+  map.resources :translations, :collection => {:locales_list => :get}
 
 #  map.connect ':controller/:action/:id'
 #  map.connect ':controller/:action/:id.:format'

data/spec/test_application/features/managing_translations.feature

@@ -59,4 +59,23 @@ Scenario: Editing translations
     And I should see "Key1NewTranslation"
     And I should see "Key1Many"
 
+Scenario: List of available locales
+    Given I have translated "Key1" to "Key1PL" in "pl" locale
+    And I have translated "Key1" to "Key1EN" in "en" locale
+    When I am on the list of available locales
+    Then I should see "en"
+    And I should see "pl"
+    Given I have translated "Key1" to "Key1NL" in "nl" locale
+    When I go to the list of available locales
+    Then I should see "en"
+    And I should see "pl"
+    And I should see "nl"
+    Given I have relocalized "Key1" from "nl" to "es"
+    When I go to the list of available locales
+    Then I should see "en"
+    And I should see "pl"
+    And I should see "es"
+    And I should not see "nl"
+
+
 

data/spec/test_application/features/static_translation.feature

@@ -3,7 +3,7 @@ Feature: Static translation
   As a language idiot
   I want to be given static page elements in a selected language
 
-#Scenario: Simple translations test
+Scenario: Simple translations test
     Given I have translated "Key1" to "Key1Translation" in "en" locale
     And I have tranlated "Key2" to "Key2Translation" with scope "scope1.subscope1" in "en" locale
     And I have translated "Key3" to "Klucz3Tłumaczenie" in "pl" locale

data/spec/test_application/features/step_definitions/translations_steps.rb

@@ -6,6 +6,16 @@ Given /^I have tranlated "([^\"]*)" to "([^\"]*)" with scope "([^\"]*)" in "([^\
   Translation.create!(:key => key, :translation => translation, :locale => locale, :scope => scope)
 end
 
+Given /^I have relocalized "([^\"]*)" from "([^\"]*)" to "([^\"]*)"$/ do |key, old_locale, new_locale|
+  Translation.first(:conditions => {:key => key, :locale => old_locale}).update_attribute('locale', new_locale)
+end
+
+When /^I reloading locales$/ do
+  Translation.set_locales
+end
+
+
+
 
 
 

data/spec/test_application/features/support/paths.rb

@@ -25,6 +25,8 @@ module NavigationHelpers
       edit_translation_path
     when /the translations test page/
       translation_path :id => 1
+    when /the list of available locales/
+      locales_list_translations_url
     
     # Add more mappings here.
     # Here is a more fancy example:

data/spec/test_application/spec/backend_spec.rb

@@ -1,9 +1,5 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
-I18n.backend = Trendi18n::Backend::Trendi18n.new
-
-
-
 describe Trendi18n::Backend::Trendi18n do
 
   before do
@@ -43,7 +39,6 @@ describe Trendi18n::Backend::Trendi18n do
       I18n.reload!
       I18n.t("test_key")
     end
-
     describe "up-to-date status" do
 
       it "should be up-to-date when there is no translations" do
@@ -73,16 +68,17 @@ describe Trendi18n::Backend::Trendi18n do
         I18n.backend.up_to_date?.should == true
       end
 
-      it "should still be up-to-date when we was looking for new translation" do
+      it "should be up-to-date when we was looking for new translation" do
         I18n.t("non_existing_key")
-        I18n.backend.up_to_date? == true
+        I18n.backend.up_to_date?.should == true
       end
 
-      it "should be up-to-date even translation is updated after use" do
+      it "should not be up-to-date if translation is updated after use" do
         I18n.t("test_key")
         @translation.update_attribute("created_at", 2.minutes.ago)
-        I18n.backend.up_to_date?.should == true
+        I18n.backend.up_to_date?.should == false
       end
+      
     end
   end
 
@@ -151,8 +147,5 @@ describe Trendi18n::Backend::Trendi18n do
       it "should translate to hash of translations"
 
     end
-
-
   end
-
 end

data/spec/test_application/spec/models/translation_spec.rb

@@ -16,6 +16,7 @@ describe Translation do
   end
 
 
+
   describe "state assigment" do
 
     before do
@@ -91,12 +92,16 @@ describe Translation do
     Translation.find_by_string_normalized_key(translation.key).should == translation
   end
 
-  it "should return array of all locale values form db" do
-    Translation.read_base
-    Translation.create!(:key => "key", :locale => "pl")
-    Translation.create!(:key => "key", :locale => "en")
-    Translation.create!(:key => "key", :locale => "nl")
-    Translation.get_locales.should == ["en", "nl", "pl"]
+  describe "locales tools" do
+
+    it "should return array of all locale values form db" do
+       Translation.create!(:key => "key", :locale => "pl")
+       Translation.create!(:key => "key", :locale => "en")
+       Translation.create!(:key => "key", :locale => "nl")
+       Translation.set_locales
+       Translation.get_locales.should == ["en", "nl", "pl"]
+    end
+
   end
 
   it "should return correct plural form (using count argument)" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: trendi18n
 version: !ruby/object:Gem::Version 
-  version: 0.9.1
+  version: 0.9.2
 platform: ruby
 authors: 
 - Piotr Misiurek
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-15 00:00:00 +01:00
+date: 2009-12-30 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,9 +42,10 @@ files:
 - app/models/translation.rb
 - generators/trendi18n/templates/migrations/create_translations.rb
 - generators/trendi18n/trendi18n_generator.rb
-- lib/commands.rb
 - lib/file.rb
-- lib/trendi18n.rb
+- lib/trendi18n/backend/trendi18n.rb
+- lib/trendi18n/generator/commands.rb
+- lib/trendi18n/handler.rb
 - rails/init.rb
 - spec/test_application/README
 - spec/test_application/Rakefile
@@ -54,6 +55,7 @@ files:
 - spec/test_application/app/views/translations/_form.html.erb
 - spec/test_application/app/views/translations/edit.html.erb
 - spec/test_application/app/views/translations/index.html.erb
+- spec/test_application/app/views/translations/locales_list.html.erb
 - spec/test_application/app/views/translations/new.html.erb
 - spec/test_application/app/views/translations/show.html.erb
 - spec/test_application/config/boot.rb