web_translate_it 1.10.2 → 2.0.0.rc2

data/history.md

@@ -1,3 +1,16 @@
+## Edge
+
+* Backport of compatibility fix for ruby 1.8.7 from 1.x serie.
+* Fix issue with new version system, which broke the gem. #86
+
+## Version 2.0.0.rc1 / 2012-04-16 (yanked)
+
+**Important**: This release candidate introduce breaking changes in the String, Translation, Term and TermTranslation APIs. See [Extras](https://github.com/AtelierConvivialite/webtranslateit/wiki/Extras) if you use the String, Translation, Term and TermTranslation APIs to programmatically manage strings, translations and terms. 
+
+* Remove undeclared dependency on ActiveSupport. ActiveSupport was required to use the `WebTranslateIt::String`, `Translation`, `Term` and `TermTranslation` classes. #84
+* Refactor `WebTranslateIt::String` and `WebTranslateIt::Translation` classes and add specs. #85
+* Refactor `WebTranslateIt::Term` and `WebTranslateIt::TermTranslation` classes and add specs.
+
 ## Version 1.10.2 / 2012-04-17
 
 * Compatibility fix for ruby 1.8.7.

data/lib/web_translate_it.rb

@@ -8,6 +8,8 @@ require 'web_translate_it/configuration'
 require 'web_translate_it/translation_file'
 require 'web_translate_it/string'
 require 'web_translate_it/translation'
+require 'web_translate_it/term'
+require 'web_translate_it/term_translation'
 require 'web_translate_it/auto_fetch'
 require 'web_translate_it/command_line'
 require 'web_translate_it/project'

data/lib/web_translate_it/string.rb

@@ -2,26 +2,76 @@
 module WebTranslateIt
   class String
     require 'net/https'
+    require 'json'
     
-    attr_accessor :id, :api_key
+    attr_accessor :api_key, :id, :key, :plural, :type, :dev_comment, :word_count, :status, :category, :label, :file,
+                  :created_at, :updated_at, :translations, :new_record
     
-    def initialize(id, api_key)
-      self.id         = id
-      self.api_key    = api_key
+    # Initialize a new WebTranslateIt::String
+    # The only mandatory parameter is `api_key`
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::String.new('secret_api_token', { "key" => "product_name_123" })
+    #
+    # to instantiate a new String without any text.
+    #
+    #   translation_en = WebTranslateIt::Translation.new({ "locale" => "en", "text" => "Hello" })
+    #   translation_fr = WebTranslateIt::Translation.new({ "locale" => "fr", "text" => "Bonjour" })
+    #   WebTranslateIt::String.new('secret_api_token', { "key" => "product_name_123", "translations" => [translation_en, translation_fr]})
+    #
+    # to instantiate a new String with a source and target translation.
+    
+    def initialize(api_key, params = {})
+      self.api_key      = api_key
+      self.id           = params["id"] || nil
+      self.key          = params["key"] || nil
+      self.plural       = params["plural"] || nil
+      self.type         = params["type"] || nil
+      self.dev_comment  = params["dev_comment"] || nil
+      self.word_count   = params["word_count"] || nil
+      self.status       = params["status"] || nil
+      self.category     = params["category"] || nil
+      self.label        = params["label"] || nil
+      self.file         = params["file"] || nil
+      self.created_at   = params["created_at"] || nil
+      self.updated_at   = params["updated_at"] || nil
+      self.translations = params["translations"] || []
+      self.new_record   = true
     end
     
-    def self.list(http_connection, api_key, params = {}, options = {})
-      options.reverse_merge!(:format => 'yaml')
-
-      url = "/api/projects/#{api_key}/strings.#{options[:format]}"
-      url += '?' + HashUtil.to_param(params) unless params.blank?
+    # Find a String based on filters
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     strings = WebTranslateIt::String.find_all(connection, 'secret_api_token', { "key" => "product_name_123" })
+    #   end
+    #
+    #   puts strings.inspect #=> An array of WebTranslateIt::String objects
+    #
+    # to find and instantiate an array of String which key is like `product_name_123`.
+    #
+    # TODO: Implement pagination
+    
+    def self.find_all(http_connection, api_key, params = {})
+      url = "/api/projects/#{api_key}/strings.yaml"
+      url += '?' + HashUtil.to_params("filters" => params) unless params.empty?
 
       request = Net::HTTP::Get.new(url)
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
 
       begin
-        Util.handle_response(http_connection.request(request), true)
+        response = Util.handle_response(http_connection.request(request), true)
+        strings = []
+        YAML.load(response).each do |string_response|
+          string = WebTranslateIt::String.new(api_key, string_response)
+          string.new_record = false
+          strings.push(string)
+        end
+        return strings
       rescue Timeout::Error
         puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
         sleep(5)
@@ -29,31 +79,73 @@ module WebTranslateIt
       end
     end
     
-    def show(http_connection, options = {})
-      options.reverse_merge!(:format => 'yaml')
-
-      request = Net::HTTP::Get.new("/api/projects/#{self.api_key}/strings/#{self.id}.#{options[:format]}")
+    # Find a String based on its ID
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     string = WebTranslateIt::String.find(connection, 'secret_api_token', 1234)
+    #   end
+    #
+    #   puts string.inspect #=> A WebTranslateIt::String object
+    #
+    # to find and instantiate the String which ID is `1234`.
+    #
+    
+    def self.find(http_connection, api_key, id)
+      request = Net::HTTP::Get.new("/api/projects/#{api_key}/strings/#{id}.yaml")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
 
       begin
-        Util.handle_response(http_connection.request(request), true)
+        response = http_connection.request(request)
+        return nil if response.code.to_i == 404
+        string = WebTranslateIt::String.new(api_key, YAML.load(response.body))
+        string.new_record = false
+        return string
       rescue Timeout::Error
         puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
         sleep(5)
         retry
       end
     end
-
-    def update(http_connection, params = {}, options = {})
-      options.reverse_merge!(:format => 'yaml')
-
-      request = Net::HTTP::Put.new("/api/projects/#{self.api_key}/strings/#{self.id}.#{options[:format]}")
+    
+    # Update or create a String to WebTranslateIt.com
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     string = WebTranslateIt::String.find(connection, 'secret_api_token', 1234)
+    #     string.status = "status_obsolete"
+    #     string.save(http_connection)
+    #   end
+    #
+    
+    def save(http_connection)
+      if self.new_record
+        self.create(http_connection)
+      else
+        self.update(http_connection)
+      end
+    end
+    
+    # Delete a String on WebTranslateIt.com
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     string = WebTranslateIt::String.find(connection, 'secret_api_token', 1234)
+    #     string.delete(http_connection)
+    #   end
+    #
+    
+    def delete(http_connection)
+      request = Net::HTTP::Delete.new("/api/projects/#{self.api_key}/strings/#{self.id}")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
-      request.add_field("Content-Type", "application/json")
-          
-      request.body = params.to_json
 
       begin
         Util.handle_response(http_connection.request(request), true)
@@ -64,14 +156,55 @@ module WebTranslateIt
       end
     end
     
-    def self.create(http_connection, api_key, params = {})
-      request = Net::HTTP::Post.new("/api/projects/#{api_key}/strings")
+    # Gets a Translation for a String
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     string = WebTranslateIt::String.find(connection, 'secret_api_token', 1234)
+    #     puts string.translation_for(connection, "fr") #=> A Translation object
+    #   end
+    #
+    
+    def translation_for(http_connection, locale)
+      return self.translations unless self.translations == []
+      request = Net::HTTP::Get.new("/api/projects/#{self.api_key}/strings/#{self.id}/locales/#{locale}/translations.yaml")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
-      request.add_field("Content-Type", "application/json")
-        
-      request.body = params.to_json
 
+      begin
+        response = Util.handle_response(http_connection.request(request), true)
+        hash = YAML.load(response)
+        return nil if hash.empty?
+        translation = WebTranslateIt::Translation.new(api_key, hash)
+        return translation
+        
+      rescue Timeout::Error
+        puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
+        sleep(5)
+        retry
+      end      
+    end
+    
+    protected
+    
+    # Save the changes made to a String to WebTranslateIt.com
+    # Needs a HTTPS Connection
+    #
+    
+    def update(http_connection)
+      request = Net::HTTP::Put.new("/api/projects/#{self.api_key}/strings/#{self.id}.yaml")
+      request.add_field("X-Client-Name", "web_translate_it")
+      request.add_field("X-Client-Version", WebTranslateIt::Util.version)
+      request.add_field("Content-Type", "application/json")
+      request.body = self.to_json
+      
+      self.translations.each do |translation|
+        translation.string_id = self.id
+        translation.save(http_connection)
+      end
+      
       begin
         Util.handle_response(http_connection.request(request), true)
       rescue Timeout::Error
@@ -80,20 +213,51 @@ module WebTranslateIt
         retry
       end
     end
-
-    def delete(http_connection)
-      request = Net::HTTP::Delete.new("/api/projects/#{self.api_key}/strings/#{self.id}")
+    
+    # Create a new String to WebTranslateIt.com
+    # Needs a HTTPS Connection
+    #
+    
+    def create(http_connection)
+      request = Net::HTTP::Post.new("/api/projects/#{self.api_key}/strings")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
+      request.add_field("Content-Type", "application/json")
+      request.body = self.to_json(true)
 
       begin
-        Util.handle_response(http_connection.request(request), true)
+        response = YAML.load(Util.handle_response(http_connection.request(request), true))
+        self.id = response["id"]
+        self.new_record = false
+        return true
       rescue Timeout::Error
         puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
         sleep(5)
         retry
       end
     end
-
+    
+    def to_json(with_translations = false)
+      hash = {
+        "id" => id,
+        "key" => key,
+        "plural" => plural,
+        "type" => type,
+        "dev_comment" => dev_comment,
+        "status" => status,
+        "label" => label,
+        "category" => category,
+        "file" => {
+          "id" => file
+        }
+      }
+      if self.translations.any? && with_translations
+        hash.update({ "translations" => [] })
+        translations.each do |translation|
+          hash["translations"].push(translation.to_hash)
+        end
+      end
+      hash.to_json
+    end
   end
 end

data/lib/web_translate_it/term.rb

@@ -2,26 +2,67 @@
 module WebTranslateIt
   class Term
     require 'net/https'
+    require 'json'
     
-    attr_accessor :id, :api_key
+    attr_accessor :api_key, :id, :text, :description, :created_at, :updated_at, :translations, :new_record
     
-    def initialize(id, api_key)
-      self.id         = id
-      self.api_key    = api_key
+    # Initialize a new WebTranslateIt::Term
+    # The only mandatory parameter is `api_key`
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Term.new('secret_api_token', { "text" => "Term Name" })
+    #
+    # to instantiate a new Term.
+    #
+    #   translation_es = WebTranslateIt::TermTranslation.new({ "locale" => "es", "text" => "Hola" })
+    #   translation_fr = WebTranslateIt::TermTranslation.new({ "locale" => "fr", "text" => "Bonjour" })
+    #   WebTranslateIt::Term.new('secret_api_token', { "text" => "Hello", "translations" => [translation_es, translation_fr]})
+    #
+    # to instantiate a new Term with a Term Translations in Spanish and French.
+    
+    def initialize(api_key, params = {})
+      self.api_key      = api_key
+      self.id           = params["id"] || nil
+      self.text         = params["text"] || nil
+      self.description  = params["description"] || nil
+      self.created_at   = params["created_at"] || nil
+      self.updated_at   = params["updated_at"] || nil
+      self.translations = params["translations"] || []
+      self.new_record   = true
     end
     
-    def self.list(http_connection, api_key, params = {}, options = {})
-      options.reverse_merge!(:format => 'yaml')
-
-      url = "/api/projects/#{api_key}/terms.#{options[:format]}"
-      url += '?' + HashUtil.to_param(params) unless params.blank?
+    # Fetch all terms
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     terms = WebTranslateIt::Term.find_all(connection, 'secret_api_token')
+    #   end
+    #
+    #  puts terms.inspect #=> An array of WebTranslateIt::Term objects
+    #
+    # TODO: Implement pagination
+    
+    def self.find_all(http_connection, api_key, params = {})
+      url = "/api/projects/#{api_key}/terms.yaml"
+      url += '?' + HashUtil.to_params(params) unless params.empty?
 
       request = Net::HTTP::Get.new(url)
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
 
       begin
-        Util.handle_response(http_connection.request(request), true)
+        response = Util.handle_response(http_connection.request(request), true)
+        terms = []
+        YAML.load(response).each do |term_response|
+          term = WebTranslateIt::Term.new(api_key, term_response)
+          term.new_record = false
+          terms.push(term)
+        end
+        return terms
+        
       rescue Timeout::Error
         puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
         sleep(5)
@@ -29,15 +70,31 @@ module WebTranslateIt
       end
     end
     
-    def show(http_connection, options = {})
-      options.reverse_merge!(:format => 'yaml')
-
-      request = Net::HTTP::Get.new("/api/projects/#{self.api_key}/terms/#{self.id}.#{options[:format]}")
+    # Find a Term based on its ID
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     term = WebTranslateIt::Term.find(connection, 'secret_api_token', 1234)
+    #   end
+    #
+    #   puts term.inspect #=> A Term object
+    #
+    # to find and instantiate the Term which ID is `1234`.
+    #
+    
+    def self.find(http_connection, api_key, term_id)
+      request = Net::HTTP::Get.new("/api/projects/#{api_key}/terms/#{term_id}.yaml")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
 
       begin
-        Util.handle_response(http_connection.request(request), true)
+        response = http_connection.request(request)
+        return nil if response.code.to_i == 404
+        term = WebTranslateIt::Term.new(api_key, YAML.load(response.body))
+        term.new_record = false
+        return term
       rescue Timeout::Error
         puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
         sleep(5)
@@ -45,15 +102,41 @@ module WebTranslateIt
       end
     end
 
-    def update(http_connection, params = {}, options = {})
-      options.reverse_merge!(:format => 'yaml')
+    # Update or create a Term to WebTranslateIt.com
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     term = WebTranslateIt::Term.find(connection, 'secret_api_token', 1234)
+    #     term.text = "Hello"
+    #     term.save(http_connection)
+    #   end
+    #
 
-      request = Net::HTTP::Put.new("/api/projects/#{self.api_key}/terms/#{self.id}.#{options[:format]}")
+    def save(http_connection)
+      if self.new_record
+        self.create(http_connection)
+      else
+        self.update(http_connection)
+      end
+    end
+    
+    # Delete a Term on WebTranslateIt.com
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     term = WebTranslateIt::Term.find(connection, 'secret_api_token', 1234)
+    #     term.delete(http_connection)
+    #   end
+    #
+    
+    def delete(http_connection)
+      request = Net::HTTP::Delete.new("/api/projects/#{self.api_key}/terms/#{self.id}")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
-      request.add_field("Content-Type", "application/json")
-          
-      request.body = params.to_json
 
       begin
         Util.handle_response(http_connection.request(request), true)
@@ -64,16 +147,34 @@ module WebTranslateIt
       end
     end
     
-    def self.create(http_connection, api_key, params = {})
-      request = Net::HTTP::Post.new("/api/projects/#{api_key}/terms")
+    # Gets a Translation for a Term
+    # Needs a HTTPS Connection
+    #
+    # Implementation Example:
+    #
+    #   WebTranslateIt::Util.http_connection do |connection|
+    #     term = WebTranslateIt::Term.find(connection, 'secret_api_token', 1234)
+    #     puts term.translation_for(connection, "fr") #=> A TermTranslation object
+    #   end
+    #
+    
+    def translation_for(http_connection, locale)
+      return self.translations unless self.translations == []
+      request = Net::HTTP::Get.new("/api/projects/#{self.api_key}/terms/#{self.id}/locales/#{locale}/translations.yaml")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
-      request.add_field("Content-Type", "application/json")
-        
-      request.body = params.to_json
 
       begin
-        Util.handle_response(http_connection.request(request), true)
+        response = Util.handle_response(http_connection.request(request), true)
+        array = YAML.load(response)
+        return nil if array.empty?
+        translations = []
+        array.each do |translation|
+          term_translation = WebTranslateIt::TermTranslation.new(api_key, translation)
+          translations.push(term_translation)
+        end
+        return translations
+        
       rescue Timeout::Error
         puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
         sleep(5)
@@ -81,10 +182,20 @@ module WebTranslateIt
       end
     end
 
-    def delete(http_connection)
-      request = Net::HTTP::Delete.new("/api/projects/#{self.api_key}/terms/#{self.id}")
+    protected
+
+    def update(http_connection)
+      request = Net::HTTP::Put.new("/api/projects/#{self.api_key}/terms/#{self.id}.yaml")
       request.add_field("X-Client-Name", "web_translate_it")
       request.add_field("X-Client-Version", WebTranslateIt::Util.version)
+      request.add_field("Content-Type", "application/json")
+          
+      request.body = self.to_json
+
+      self.translations.each do |translation|
+        translation.term_id = self.id
+        translation.save(http_connection)
+      end
 
       begin
         Util.handle_response(http_connection.request(request), true)
@@ -94,6 +205,41 @@ module WebTranslateIt
         retry
       end
     end
+    
+    def create(http_connection)
+      request = Net::HTTP::Post.new("/api/projects/#{api_key}/terms")
+      request.add_field("X-Client-Name", "web_translate_it")
+      request.add_field("X-Client-Version", WebTranslateIt::Util.version)
+      request.add_field("Content-Type", "application/json")
+        
+      request.body = self.to_json(true)
 
+      begin
+        response = YAML.load(Util.handle_response(http_connection.request(request), true))
+        self.id = response["id"]
+        self.new_record = false
+        return true
+        
+      rescue Timeout::Error
+        puts "The request timed out. The service may be overloaded. We will retry in 5 seconds."
+        sleep(5)
+        retry
+      end
+    end
+    
+    def to_json(with_translations = false)
+      hash = {
+        "id" => id,
+        "text" => text,
+        "description" => description
+      }
+      if self.translations.any? && with_translations
+        hash.update({ "translations" => [] })
+        translations.each do |translation|
+          hash["translations"].push(translation.to_hash)
+        end
+      end
+      hash.to_json
+    end
   end
 end