web_translate_it 1.4.4 → 1.4.5

data/README.md

@@ -1,17 +1,42 @@
 # Web Translate It
 
-[RDocs](http://yardoc.org/docs/AtelierConvivialite-webtranslateit) | [Metrics](http://getcaliper.com/caliper/project?repo=git%3A%2F%2Fgithub.com%2FAtelierConvivialite%2Fwebtranslateit.git) | [Tests](http://runcoderun.com/AtelierConvivialite/webtranslateit/builds/74a78c2b382cb1856fa0964ed4ad372b50872844/1/ruby_186) |
+[Homepage](https://webtranslateit.com) | 
+[RDocs](http://yardoc.org/docs/AtelierConvivialite-webtranslateit) | 
+[Metrics](http://getcaliper.com/caliper/project?repo=git%3A%2F%2Fgithub.com%2FAtelierConvivialite%2Fwebtranslateit.git) | 
+[Tests](http://runcoderun.com/AtelierConvivialite/webtranslateit/builds/74a78c2b382cb1856fa0964ed4ad372b50872844/1/ruby_186) | 
 [Example app](http://github.com/AtelierConvivialite/rails_example_app)
 
-This is a gem providing tools to integrate your app with [Web Translate It](https://webtranslateit.com).
+This is a gem providing tools to integrate your software to translate with [Web Translate It](https://webtranslateit.com), a web-based translation hub.
 
 This gem provides your app with:
 
-* a handful of rake task to fetch your translations.
+* an executable, `wti`, to upload and download language files from the command line (or in whatever else you want to execute it)
+* a handful of rake task to fetch and upload your translations.
 * a rack middleware to automatically fetch new translations from Web Translate It.
 
 ## Installation
 
+    gem install web_translate_it
+    
+That’s it! At this point you have the Web Translate It executable. Run `wti --help` to see the usage:
+
+    Web Translate It Help:
+    **********************
+    -f --fetch [locale]           Download all the files for your project.
+                                  If a locale is specified, only download
+                                  the file for that locale.
+    -u --upload [locale]          Upload your files for a locale.
+    -v --version                  Show version.
+    -h --help                     This page.
+
+### Assumptions
+
+We assume you have a `config/translation.yml` file in your project containing the configuration to sync with Web Translate It. [Read about the configuration file in the wiki](http://wiki.github.com/AtelierConvivialite/webtranslateit/).
+
+## Specific tools for Ruby on Rails
+
+This gem includes some rake tasks and a rack middleware to integrate Web Translate It with Ruby on Rails.
+
 * Add to your config/environments.rb:
 
     `config.gem 'web_translate_it'`
@@ -19,19 +44,19 @@ This gem provides your app with:
 * Then, run:
 
     `rake gems:install`
-    
+
 * Copy/paste your api key from Web Translate It and run:
 
     `script/generate webtranslateit --api-key your_key_here`
     
   The generator does two things:
   
-  * It adds a auto-configured `config/translation.yml` file using Web Translate It’s API.
-  * It adds `require 'web_translate_it/tasks' rescue LoadError` to your `Rakefile`
+  - It adds a auto-configured `config/translation.yml` file using Web Translate It’s API.
+  - It adds `require 'web_translate_it/tasks' rescue LoadError` to your `Rakefile`
   
-## Rake tasks provided
+### Rake tasks provided
 
-The gem provides 3 rake tasks.
+There are 3 rake tasks.
 
     rake trans:fetch:all
   
@@ -45,49 +70,8 @@ Fetch the latest translations for all the languages defined in Web Translate It
     
 Upload to Web Translate It your files in a specific locale defined in Web Translate It’s interface.
 
-## Optional: automatically fetch new language files for each page request
-
-This should not be used on production. This allows to translate text on Web Translate It, reload a page on your site and see the translations appear.
-
-### Rails 2.3 and newer
-
-Use the rack middleware!
-
-* Before starting up anything, you need to have a rack middleware setup to assign the value of the current locale to `I18n.locale`.
-  This is very much specific to your app, this is left as an exercise to the reader. You can inspire yourself from Ryan Tomakyo’s [locale.rb](http://github.com/rack/rack-contrib/blob/master/lib/rack/contrib/locale.rb).
-  You can also find an example of a very simple middleware using the `locale` parameter in [examples/locale.rb](http://github.com/AtelierConvivialite/webtranslateit/blob/master/examples/locale.rb).
-
-* The next step is to setup the `autofetch` middleware. Add in `config/environments/development.rb` and any other environments you want to autofetch this line:
-
-      config.middleware.use "WebTranslateIt::AutoFetch"
-    
-* Restart your application, load a page. You should see this in the logs:
-
-      Looking for fr_FR translations...
-      Done. Response code: 200
-    
-* That’s it!
-
-### Rails older than 2.3 (works also for 2.3 and newer)
-
-* Add the following lines in your `ApplicationController`:
-
-<pre>before_filter :update_locale
-
-def update_locale
-  begin
-    WebTranslateIt.fetch_translations
-  rescue Exception => e
-    puts "** Web Translate It raised an exception: " + e.message
-  end
-end</pre>
-
-* Restart your application for the changes to take effect. You should see something like this in the logs:
-
-      Looking for fr translations...
-      Done. Response code: 304
+Read more about "Rails integration in the wiki":http://wiki.github.com/AtelierConvivialite/webtranslateit/.
 
-* That’s it!
 
 ## Supported Rails Versions
 
@@ -100,7 +84,7 @@ Please open a discussion on [our support site](http://help.webtranslateit.com) i
 
 # What is Web Translate It anyway?
 
-Web Translate It is an easy to use web-based translation hub to collaboratively translate software.
+Web Translate It is a web-based translation hub to collaboratively translate software.
 
 To learn more about it, please visit our [tour page](https://webtranslateit.com/tour).
 

data/bin/wti

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'web_translate_it'
+# require 'lib/web_translate_it' # for testing
+WebTranslateIt::CommandLine.run

data/history.md

@@ -1,3 +1,8 @@
+## Edge
+
+* Improved documentation
+* Web Translate is now an executable: `wti`
+
 ## Version 1.4.4 / 2010-02-02
 
 * Add generator to automatically configure your project, given a Web Translate It API key.

data/lib/web_translate_it.rb

@@ -2,6 +2,7 @@ require File.join(File.dirname(__FILE__), 'web_translate_it', 'util')
 require File.join(File.dirname(__FILE__), 'web_translate_it', 'configuration')
 require File.join(File.dirname(__FILE__), 'web_translate_it', 'translation_file')
 require File.join(File.dirname(__FILE__), 'web_translate_it', 'auto_fetch')
+require File.join(File.dirname(__FILE__), 'web_translate_it', 'command_line')
 
 module WebTranslateIt
   def self.fetch_translations

data/lib/web_translate_it/auto_fetch.rb

@@ -1,11 +1,19 @@
 module WebTranslateIt
+  
+  # Class to automatically fetch the last translations from Web Translate It
+  # for every page requested.
+  # This can be used as a rack middleware.
+  # Implementation example:
+  #
+  #   # in config/environment.rb:
+  #   config.middleware.use "WebTranslateIt::AutoFetch"
+  #
   class AutoFetch
     def initialize(app)
       @app = app
     end
   
     def call(env)
-      # Update language files
       WebTranslateIt::fetch_translations
       status, headers, response = @app.call(env)
       [status, headers, response.body]

data/lib/web_translate_it/command_line.rb

@@ -0,0 +1,71 @@
+module WebTranslateIt
+  class CommandLine
+    
+    OPTIONS = <<-OPTION
+-f --fetch [locale]           Download all the files for your project.
+                              If a locale is specified, only download
+                              the file for that locale.
+-u --upload [locale]          Upload your files for a locale.
+-v --version                  Show version.
+-h --help                     This page.
+OPTION
+    
+    def self.run
+      case ARGV[0]
+      when '-f', '--fetch'
+        fetch
+      when '-u', '--upload'
+        upload
+      when '-v', '--version'
+        show_version
+      when '-h', '--help'
+        show_options
+      else
+        puts "Command not found"
+        show_options
+      end
+    end
+    
+    def self.fetch
+      #TODO: Ability to pass a path as an argument
+      configuration = WebTranslateIt::Configuration.new('.')
+      if ARGV.size == 2
+        locales = [ARGV[1]]
+      elsif ARGV.size == 1
+        locales = configuration.locales
+      end
+      configuration.files.each do |file|
+        locales.each do |locale|
+          file.fetch(locale)
+        end
+      end
+    end
+    
+    def self.upload
+      #TODO: Ability to pass a path as an argument
+      configuration = WebTranslateIt::Configuration.new('.')
+      if ARGV.size == 2
+        locales = [ARGV[1]]
+      elsif ARGV.size == 1
+        locales = configuration.locales
+      end
+      configuration.files.each do |file|
+        locales.each do |locale|
+          file.upload(locale)
+        end
+      end
+    end
+    
+    def self.show_options
+      puts ""
+      puts "Web Translate It Help:"
+      puts "**********************"
+      $stdout.puts OPTIONS
+    end
+    
+    def self.show_version
+      puts ""
+      puts "Web Translate It #{WebTranslateIt::Util.version}"
+    end
+  end
+end

data/lib/web_translate_it/configuration.rb

@@ -1,28 +1,43 @@
 module WebTranslateIt
+  
+  # Handles the configuration of your project, both via the the configuration file
+  # and via the API.
+  # Implementation example, assuming you have a valid config/translation.yml file:
+  #
+  #   configuration = WebTranslateIt::Configuration.new
+  #
   class Configuration
     require 'yaml'
     require 'fileutils'
-    attr_accessor :api_key, :files, :ignore_locales, :logger
+    attr_accessor :path, :api_key, :files, :ignore_locales, :logger
     
-    def initialize
-      file = File.join(RAILS_ROOT, 'config', 'translation.yml')
-      configuration       = YAML.load_file(file)
+    # Load the configuration file from the path.
+    def initialize(root_path=RAILS_ROOT, path_to_config="config/translation.yml")
+      self.path           = root_path
+      configuration       = YAML.load_file(File.join(root_path, path_to_config))
       self.logger         = logger
       self.api_key        = configuration['api_key']
       self.files          = []
       self.ignore_locales = configuration['ignore_locales'].to_a.map{ |locale| locale.to_s }
       configuration['files'].each do |file_id, file_path|
-        self.files.push(TranslationFile.new(file_id, file_path, api_key))
+        self.files.push(TranslationFile.new(file_id, root_path + '/' + file_path, api_key))
       end
     end
     
+    # Makes an API request to fetch the list of the different locales for a project.
+    # Implementation example:
+    #
+    #   configuration = WebTranslateIt::Configuration.new
+    #   locales = configuration.locales # returns an array of locales: ['en', 'fr', 'es', ...]
+    #
+    # TODO: Make this use the new endpoint serving YAML
     def locales
       WebTranslateIt::Util.http_connection do |http|
         request  = Net::HTTP::Get.new(api_url)
         response = http.request(request)
         if response.code.to_i >= 400 and response.code.to_i < 500
           puts "----------------------------------------------------------------------"
-          puts "You API key seems to be misconfigured. It is currently “self.api_key”."
+          puts "You API key seems to be misconfigured. It is currently #{self.api_key}."
           puts "Change it in RAILS_ROOT/configuration/translation.yml."
         else
           response.body.split
@@ -30,10 +45,12 @@ module WebTranslateIt
       end
     end
     
+    # Convenience method which returns the endpoint for fetching a list of locales for a project.
     def api_url
       "/api/projects/#{api_key}/locales"
     end
     
+    # Returns a logger. If RAILS_DEFAULT_LOGGER is defined, use it, else, define a new logger.
     def logger
       if defined?(Rails.logger)
         Rails.logger

data/lib/web_translate_it/tasks.rb

@@ -31,7 +31,7 @@ namespace :trans do
     end
   end
   
-  desc "Upload a translation file to Web Translate It"
+  desc "Upload the translation files for a locale to Web Translate It"
   task :upload, :locale do |task, args|
     welcome_message
     puts "Uploading file for locale #{args.locale}…"

data/lib/web_translate_it/translation_file.rb

@@ -1,4 +1,11 @@
 module WebTranslateIt
+  
+  # A TranslationFile is the representation of a master language file
+  # on Web Translate It.
+  #
+  # This class allows to manipulate TranslationFiles, more specifically upload and download them.
+  # If you pass a Locale to the master language file you will be able to
+  # manipulate a _target_ language file.
   class TranslationFile
     require 'net/https'
     require 'net/http/post/multipart'
@@ -12,16 +19,43 @@ module WebTranslateIt
       self.api_key   = api_key
     end
     
+    # Fetch a language file.
+    # By default it will make a conditional GET Request, using the `If-Modified-Since` tag.
+    # You can force the method to re-download your file by passing `true` as a second argument
+    #
+    # Example of implementation:
+    #
+    #   configuration = WebTranslateIt::Configuration.new
+    #   locale = configuration.locales.first
+    #   file = configuration.files.first
+    #   file.fetch(locale) # the first time, will return the content of the language file with a status 200 OK
+    #   file.fetch(locale) # returns nothing, with a status 304 Not Modified
+    #   file.fetch(locale, true) # force to re-download the file, will return the content of the file with a 200 OK
+    #
     def fetch(locale, force = false)
       WebTranslateIt::Util.http_connection do |http|
         request = Net::HTTP::Get.new(api_url(locale))
         request.add_field('If-Modified-Since', last_modification(file_path)) if File.exist?(file_path) and !force
         response = http.request(request)
-        File.open(file_path_for_locale(locale), 'w'){ |file| file << response.body } if response.code.to_i == 200 and !response.body == ''
+        File.open(file_path_for_locale(locale), 'w'){ |file| file << response.body } if response.code.to_i == 200 and response.body != ''
         response.code.to_i
       end
     end
     
+    # Update a language file to Web Translate It by performing a PUT Request.
+    # Note that it is currently not possible to POST a new language file at the moment.
+    #
+    # Example of implementation:
+    #
+    #   configuration = WebTranslateIt::Configuration.new
+    #   locale = configuration.locales.first
+    #   file = configuration.files.first
+    #   file.upload(locale) # should respond the HTTP code 202 Accepted
+    #
+    # The meaning of the HTTP 202 code is: the request has been accepted for processing, but the processing has not
+    # been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing
+    # actually takes place.
+    # This is due to the fact that language file imports are handled by background processing.
     def upload(locale)
       File.open(file_path_for_locale(locale)) do |file|
         WebTranslateIt::Util.http_connection do |http|
@@ -32,16 +66,19 @@ module WebTranslateIt
       end
     end
     
+    # Convenience method which returns the file path of a TranslationFile for a given locale.
     def file_path_for_locale(locale)
       self.file_path.gsub("[locale]", locale)
     end
         
     protected
       
+      # Convenience method which returns the date of last modification of a language file.
       def last_modification(file_path)
         File.mtime(File.new(file_path, 'r')).rfc2822
       end
-            
+      
+      # Convenience method which returns the URL of the API endpoint for a locale.
       def api_url(locale)
         "/api/projects/#{api_key}/files/#{self.id}/locales/#{locale}"
       end

data/lib/web_translate_it/util.rb

@@ -1,10 +1,24 @@
 module WebTranslateIt
-  class Util    
+  
+  # A few useful functions
+  class Util
+    
+    # Return a string representing the gem version
+    # For example "1.4.4"
     def self.version
       hash = YAML.load_file File.join(File.dirname(__FILE__), '..', '..' '/version.yml')
       [hash[:major], hash[:minor], hash[:patch]].join('.')
     end
     
+    # Yields a HTTP connection over SSL to Web Translate It.
+    # This is used for the connections to the API throughout the library.
+    # Use it like so:
+    # 
+    #   WebTranslateIt::Util.http_connection do |http|
+    #     request = Net::HTTP::Get.new(api_url)
+    #     response = http.request(request)
+    #   end
+    #
     def self.http_connection
       http = Net::HTTP.new('webtranslateit.com', 443)
       http.use_ssl      = true
@@ -12,6 +26,5 @@ module WebTranslateIt
       http.read_timeout = 10
       yield http
     end
-    
   end
 end

data/version.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 1
 :minor: 4
-:patch: 4
+:patch: 5

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: web_translate_it
 version: !ruby/object:Gem::Version 
-  version: 1.4.4
+  version: 1.4.5
 platform: ruby
 authors: 
 - "\xC3\x89douard Bri\xC3\xA8re"
@@ -9,8 +9,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-02 00:00:00 +01:00
-default_executable: 
+date: 2010-02-03 00:00:00 +01:00
+default_executable: wti
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: multipart-post
@@ -44,12 +44,13 @@ dependencies:
     version: 
 description: A rack middleware and a handful of rake tasks to sync your translations between webtranslateit.com and your rails applications.
 email: edouard@atelierconvivialite.com
-executables: []
-
+executables: 
+- wti
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- history.md
+- README.md
 files: 
 - history.md
 - MIT-LICENSE
@@ -58,6 +59,7 @@ files:
 - examples/locale.rb
 - examples/translation.yml
 - lib/web_translate_it/auto_fetch.rb
+- lib/web_translate_it/command_line.rb
 - lib/web_translate_it/configuration.rb
 - lib/web_translate_it/tasks.rb
 - lib/web_translate_it/translation_file.rb
@@ -66,13 +68,15 @@ files:
 - generators/webtranslateit/lib/insert_commands.rb
 - generators/webtranslateit/templates/translation.yml
 - generators/webtranslateit/webtranslateit_generator.rb
+- bin/wti
 has_rdoc: true
 homepage: https://webtranslateit.com
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --main
+- README.md
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement