translatomatic 0.1.1 → 0.1.2

data/lib/translatomatic/http_request.rb

@@ -2,24 +2,38 @@ require 'securerandom'
 require 'net/http'
 
 module Translatomatic
+  # HTTP request
+  # wrapper for Net::HTTP functionality
   class HTTPRequest
 
+    # @return [String] the text to use to denote multipart boundaries. By
+    #   default, a random hexadecimal string is used.
     attr_accessor :multipart_boundary
 
+    # @param url [String,URI] URL of the request
+    # @return [Translatomatic::HTTPRequest] Create a new request
     def initialize(url)
       @uri = url.respond_to?(:host) ? url : URI.parse(url)
       @multipart_boundary = SecureRandom.hex(16)
     end
 
+    # Start the HTTP request. Yields a http object.
+    # @param options [Hash<Symbol,Object>] Request options
+    # @return [Object] Result of the block
     def start(options = {})
       options = options.merge(use_ssl: @uri.scheme == "https")
+      result = nil
       Net::HTTP.start(@uri.host, @uri.port, options) do |http|
         @http = http
-        yield http
+        result = yield http
       end
       @http = nil
+      result
     end
 
+    # Send a HTTP GET request
+    # @param query [Hash<String,String>] Optional query parameters
+    # @return [Net::HTTP::Response]
     def get(query = nil)
       uri = @uri
       if query
@@ -31,6 +45,9 @@ module Translatomatic
       send_request(request)
     end
 
+    # Send an HTTP POST request
+    # @param body [String,Hash] Body of the request
+    # @return [Net::HTTP::Response]
     def post(body, options = {})
       request = Net::HTTP::Post.new(@uri)
       request['User-Agent'] = USER_AGENT
@@ -40,6 +57,7 @@ module Translatomatic
         content_type = "multipart/form-data; boundary=#{@multipart_boundary}"
         request.body = multipartify(body)
       elsif body.kind_of?(Hash)
+        # set_form_data does url encoding
         request.set_form_data(body)
       else
         request.body = body
@@ -49,10 +67,14 @@ module Translatomatic
       send_request(request)
     end
 
+    # Create a file parameter for a multipart POST request
+    # @return [FileParam] A new file parameter
     def file(*args)
       FileParam.new(*args)
     end
 
+    # Create a parameter for a multipart POST request
+    # @return [Param] A new parameter
     def param(*args)
       Param.new(*args)
     end
@@ -65,17 +87,19 @@ module Translatomatic
     class Param
       attr_accessor :key, :value
 
-      def initialize(key:, value:)
-        @key = key
-        @value = value
-      end
-
+      # @return [String] Representation of this parameter as it appears
+      #   within a multipart post request.
       def to_s
         return header(header_data) + "\r\n#{value}\r\n"
       end
 
       private
 
+      def initialize(key:, value:)
+        @key = key
+        @value = value
+      end
+
       def header_data
         name = CGI::escape(key.to_s)
         { "Content-Disposition": "form-data", name: %Q("#{name}") }
@@ -97,13 +121,7 @@ module Translatomatic
     class FileParam < Param
       attr_accessor :filename, :content, :mime_type
 
-      def initialize(key:, filename:, content:, mime_type:)
-        @key = key
-        @filename = filename
-        @content = content
-        @mime_type = mime_type
-      end
-
+      # (see Param#to_s)
       def to_s
         return header(header_data) +
           header("Content-Type": mime_type) + "\r\n#{content}\r\n"
@@ -111,6 +129,13 @@ module Translatomatic
 
       private
 
+      def initialize(key:, filename:, content:, mime_type:)
+        @key = key
+        @filename = filename
+        @content = content
+        @mime_type = mime_type
+      end
+
       def header_data
         super.merge({ filename: %Q("#{filename}") })
       end
@@ -124,7 +149,11 @@ module Translatomatic
     end
 
     def send_request(req)
-      response = @http.request(req)
+      if @http
+        response = @http.request(req)
+      else
+        response = start { |http| http.request(req) }
+      end
       raise response.body unless response.kind_of? Net::HTTPSuccess
       response
     end

data/lib/translatomatic/locale.rb

@@ -1,18 +1,37 @@
+# Represents a locale
+# @see https://en.wikipedia.org/wiki/Locale_(computer_software)
 class Translatomatic::Locale
 
+  # @return [String] ISO 639-1 language
   attr_reader :language
+
+  # @return [String] ISO 15924 script
   attr_reader :script
+
+  # @return [String] ISO 3166-1 alpha-2 country code
   attr_reader :region
 
+  # Parse the given tag
+  # @param tag [String] A string representing a locale
+  # @param validate [boolean] If true, return nil if the locale is invalid
+  # @return [Locale] A locale object
   def self.parse(tag, validate = true)
-    locale = tag.kind_of?(Translatomatic::Locale) ? tag : new(tag)
+    return nil if tag.nil?
+
+    locale = tag
+    unless tag.kind_of?(Translatomatic::Locale)
+      tag = tag.to_s.gsub(/_/, '-')
+      locale = new(tag)
+    end
     validate && !locale.valid? ? nil : locale
   end
 
+  # @return [Locale] the default locale
   def self.default
-    DEFAULT_LOCALE
+    parse(Translatomatic::Config.instance.default_locale)
   end
 
+  # @return [Locale] create a new locale object
   def initialize(tag)
     data = I18n::Locale::Tag::Rfc4646.tag(tag)
     if data
@@ -22,23 +41,29 @@ class Translatomatic::Locale
     end
   end
 
+  # @return true if language is a valid ISO 639-1 language
   def valid?
-    # test if lang is a valid ISO 639-1 language
     VALID_LANGUAGES.include?(language)
   end
 
+  # @return [String] Locale as a string
   def to_s
     [language, script, region].compact.join("-")
   end
 
+  # @param other [Object] Another object
+  # @return [boolean] true if the other object is a {Translatomatic::Locale}
+  #   object and has equal language, script and region.
   def eql?(other)
     other.kind_of?(Translatomatic::Locale) && other.hash == hash
   end
 
+  # (see #eql?)
   def ==(other)
     eql?(other)
   end
 
+  # @!visibility private
   def hash
     [language, script, region].hash
   end
@@ -47,6 +72,5 @@ class Translatomatic::Locale
 
   # list of 2 letter country codes
   VALID_LANGUAGES = ::I18nData.languages.keys.collect { |i| i.downcase }.sort
-  DEFAULT_LOCALE = parse(I18n.default_locale)
 
 end

data/lib/translatomatic/logger.rb

@@ -1,6 +1,10 @@
-class Translatomatic::Logger
+# Logging
+class Translatomatic::Logger
+
+  # @return [ProgressBar] A progress bar
   attr_accessor :progressbar
-
+
+  # @return [Translatomatic::Logger] create a new logger instance
   def initialize
     @logger = Logger.new(STDOUT)
     @logger.level = ENV['DEBUG'] ? Logger::DEBUG : Logger::INFO
@@ -9,20 +13,24 @@ class Translatomatic::Logger
     end
   end
 
-  def method_missing(name, *args)
-    handle_logger_method(name, args) if @logger.respond_to?(name)
-  end
-
-  def finish
-    @progressbar.finish if @progressbar
+  # Called at the end of translatomatic to clear the progress bar.
+  def finish
+    @finished ||= begin
+      @progressbar.finish if @progressbar
+      true
+    end
   end
 
-  private
+  private
 
-  def handle_logger_method(name, args)
-    @progressbar.clear if @progressbar
-    @logger.send(name, *args)
-    @progressbar.refresh(force: true) if @progressbar && !@progressbar.stopped?
+  def method_missing(name, *args)
+    handle_logger_method(name, args) if @logger.respond_to?(name)
   end
 
+  def handle_logger_method(name, args)
+    @progressbar.clear if @progressbar
+    @logger.send(name, *args)
+    @progressbar.refresh(force: true) if @progressbar && !@progressbar.stopped?
+  end
+
 end

data/lib/translatomatic/model/locale.rb

@@ -1,11 +1,14 @@
 module Translatomatic
   module Model
+    # Locale database record.
+    # Used to store translations in the database.
     class Locale < ActiveRecord::Base
       has_many :texts, class_name: "Translatomatic::Model::Text"
       validates_presence_of :language
       validates_uniqueness_of :language, scope: [:script, :region]
 
-      # create a locale record from an I18n::Locale::Tag object or string
+      # Create a locale record from an I18n::Locale::Tag object or string
+      # @return [Translatomatic::Model::Locale] Locale record
       def self.from_tag(tag)
         tag = Translatomatic::Locale.parse(tag)
         find_or_create_by!({
@@ -13,6 +16,7 @@ module Translatomatic
         })
       end
 
+      # @return [String] Locale as string
       def to_s
         [language, script, region].compact.join("-")
       end

data/lib/translatomatic/model/text.rb

@@ -1,5 +1,7 @@
 module Translatomatic
   module Model
+    # Text database record.
+    # Used to store translations in the database.
     class Text < ActiveRecord::Base
       belongs_to :locale, class_name: "Translatomatic::Model::Locale"
       belongs_to :from_text, class_name: "Translatomatic::Model::Text"

data/lib/translatomatic/model.rb

@@ -1,3 +1,4 @@
+# Contains classes that interface to records in the translatomatic database
 module Translatomatic::Model; end
 
 require 'translatomatic/model/locale'

data/lib/translatomatic/option.rb

@@ -1,24 +1,89 @@
 module Translatomatic
-  class Option
-    attr_reader :name, :required, :use_env, :description
-
+  # Stores details about command line and object constructor options
+  class Option
+    # @return [String] Name of the option
+    attr_reader :name
+
+    # @return [boolean] True if this option is required
+    attr_reader :required
+
+    # @return [boolean] If true, the option can be set via an environment
+    #   variable corresponding to the uppercased version of {name}.
+    attr_reader :use_env
+
+    # @return [String] Description of the option
+    attr_reader :description
+
+    # @return [boolean] If true, the option does not appear on the command line
+    #   but it can be used in configuration settings
+    attr_reader :hidden
+
+    # @return [Symbol] Type of option, one of:
+    #   :string, :hash, :array, :numeric, or :boolean
+    attr_reader :type
+
+    # @return [Object] The default value for this option
+    attr_reader :default
+
+    # Create a new option
+    # @param data [Hash<Symbol,Object>] Attributes as above
+    # @return [Translatomatic::Option] A new option instance
     def initialize(data = {})
       @name = data[:name]
       @required = data[:required]
       @use_env = data[:use_env]
-      @description = data[:desc]
+      @description = data[:desc]
+      @hidden = data[:hidden]
+      @default = data[:default]
+      @type = data[:type] || :string
       @data = data
     end
-
-    def to_hash
-      @data
+
+    # @return [Hash] Option data as a hash
+    def to_hash
+      @data
+    end
+
+    # Retrieve all options from an object or list of objects.
+    # @param object [#options,Array<#options>] Options source
+    # @return [Array<Translatomatic::Option>] options
+    def self.options_from_object(object)
+      options = []
+      if object.respond_to?(:options)
+        options += options_from_object(object.options)
+      elsif object.kind_of?(Array)
+        object.each do |item|
+          if item.kind_of?(Translatomatic::Option)
+            options << item
+          elsif item.respond_to?(:options)
+            options += options_from_object(item.options)
+          end
+        end
+      end
+      options
     end
   end
+
+  private
 
+  # @!visibility private
   module DefineOptions
-    private
-    def define_options(*options)
-      @options = options.collect { |i| Translatomatic::Option.new(i) }
+
+    # @!visibility private
+    module ClassMethods
+      attr_reader :options
+
+      private
+
+      def define_options(*options)
+        @options = options.collect { |i| Translatomatic::Option.new(i) }
+      end
+    end
+
+    private
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
     end
   end
 end

data/lib/translatomatic/progress_updater.rb

@@ -1,15 +1,19 @@
 # implements Converter listener
 class Translatomatic::ProgressUpdater
+  # Create a new progress updater
+  # @param progressbar [Progressbar] A ruby-progressbar object
   def initialize(progressbar)
     @progressbar = progressbar
   end
 
+  # @return [Number] the number of translated strings
   def translated_texts(texts)
-    @progressbar.progress += texts.length
+    @progressbar.progress += texts.length
   end
-
+
+  # @return [Number] the number of untranslated strings
   def untranslated_texts(texts)
-    @progressbar.total -= texts.length
+    @progressbar.total -= texts.length
   end
 
 end

data/lib/translatomatic/resource_file/base.rb

@@ -1,3 +1,4 @@
+# Base class for resource file implementations
 # @abstract Subclasses implement different types of resource files
 class Translatomatic::ResourceFile::Base
 
@@ -15,13 +16,13 @@ class Translatomatic::ResourceFile::Base
   # Create a new resource file.
   # If locale is unspecified, attempts to determine the locale of the file
   # automatically, and if that fails, uses the default locale.
-  # @param [String] path Path to the file
-  # @param [String] locale Locale of the file contents
+  # @param path [String] Path to the file
+  # @param locale [String] Locale of the file contents
   # @return [Translatomatic::ResourceFile::Base] the resource file.
   def initialize(path, locale = nil)
     @path = path.kind_of?(Pathname) ? path : Pathname.new(path)
-    @locale = locale || detect_locale || Translatomatic::Locale.default
-    raise "unable to determine locale" unless @locale && @locale.language
+    @locale = Translatomatic::Locale.parse(locale || detect_locale || Translatomatic::Locale.default)
+    raise t("resource.unknown_locale") unless @locale && @locale.language
     @valid = false
     @properties = {}
   end
@@ -32,7 +33,7 @@ class Translatomatic::ResourceFile::Base
   end
 
   # Create a path for the current resource file with a given locale
-  # @param [String] locale for the path
+  # @param locale [String] The target locale
   # @return [Pathname] The path of this resource file modified for the given locale
   def locale_path(locale)
     basename = path.sub_ext('').basename.to_s
@@ -54,7 +55,7 @@ class Translatomatic::ResourceFile::Base
   end
 
   # Set all properties
-  # @param [Hash<String,String>] properties New properties
+  # @param properties [Hash<String,String>] New properties
   def properties=(properties)
     # use set rather that set @properties directly as subclasses override set()
     properties.each do |key, value|
@@ -63,18 +64,18 @@ class Translatomatic::ResourceFile::Base
   end
 
   # Get the value of a property
-  # @param [String] name The name of the property
+  # @param key [String] The name of the property
   # @return [String] The value of the property
-  def get(name)
-    @properties[name]
+  def get(key)
+    @properties[key]
   end
 
   # Set a property
-  # @param [String] key The name of the property
-  # @param [String] value The new value of the property
+  # @param key [String] The name of the property
+  # @param value [String] The new value of the property
   # @return [String] The new value of the property
-  def set(name, value)
-    @properties[name] = value
+  def set(key, value)
+    @properties[key] = value
   end
 
   # Test if the current resource file is valid
@@ -84,8 +85,8 @@ class Translatomatic::ResourceFile::Base
   end
 
   # Save the resource file.
-  # @param [Pathname] target The destination path
-  # @param [Hash<Symbol, Object>] options Output format options
+  # @param target [Pathname] The destination path
+  # @param options [Hash<Symbol, Object>] Output format options
   # @return [void]
   def save(target = path, options = {})
     raise "save(path) must be implemented by subclass"
@@ -93,9 +94,10 @@ class Translatomatic::ResourceFile::Base
 
   # @return [String] String representation of this file
   def to_s
-    "#{path.basename.to_s} (#{locale})"
+    path.basename.to_s
   end
 
+  # @return [Array<String>] All property values split into sentences
   def sentences
     sentences = []
     properties.values.each do |value|
@@ -105,13 +107,34 @@ class Translatomatic::ResourceFile::Base
     sentences
   end
 
+  # @return [boolean] true if this resource file supports variable interpolation
+  def supports_variable_interpolation?
+    false
+  end
+
+  # Create an interpolated variable string.
+  # @return [String] A string representing the interpolated variable, or
+  #   nil if this resource file doesn't support variable interpolation.
+  def create_variable(name)
+    return nil unless supports_variable_interpolation?
+    raise "create_variable(name) must be implemented by subclass"
+  end
+
+  # @return [Regexp] A regexp used to match interpolated variables
+  def variable_regex
+    return nil unless supports_variable_interpolation?
+    raise "variable_regex must be implemented by subclass"
+  end
+
   private
 
   include Translatomatic::Util
 
   def created_by
-    date = DateTime.now.strftime("%Y-%m-%d %H:%M")
-    "Created by Translatomatic #{Translatomatic::VERSION} #{date}"
+    t("resource.created_by", app: "Translatomatic",
+      version: Translatomatic::VERSION, date: I18n.l(DateTime.now),
+      locale: locale.language
+    )
   end
 
   # detect locale from filename

data/lib/translatomatic/resource_file/html.rb

@@ -1,4 +1,5 @@
 module Translatomatic::ResourceFile
+  # HTML resource file
   class HTML < XML
 
     # (see Translatomatic::ResourceFile::Base.extensions)
@@ -17,30 +18,26 @@ module Translatomatic::ResourceFile
         return strip_extensions.sub_ext("." + new_extension)
       else
         # add locale extension
-        ext = path.extname
+        ext = path.extname
         # TODO: need configurable order for locale & ext here?
-        #path.sub_ext("#{ext}." + locale.to_s)
+        #path.sub_ext("#{ext}." + locale.to_s)
         path.sub_ext("." + locale.to_s + ext)
       end
     end
 
     # (see Translatomatic::ResourceFile::Base#save)
-    def save(target = path, options = {})
-      if @doc
-        add_created_by unless options[:no_created_by]
-        target.write(@doc.to_html)
+    def save(target = path, options = {})
+      if @doc
+        add_created_by unless options[:no_created_by]
+        target.write(@doc.to_html)
       end
     end
 
     private
-
-    def text_nodes_xpath
-      '//*[not(self::code)]/text()'
-    end
-
-    def add_created_by
-      @created_by ||= @doc.root.add_previous_sibling(comment(created_by))
-    end
+
+    def text_nodes_xpath
+      '//*[not(self::code)]/text()'
+    end
 
     def read_doc(path)
       Nokogiri::HTML(path.open) do |config|

data/lib/translatomatic/resource_file/markdown.rb

@@ -2,6 +2,7 @@ require 'kramdown'
 require 'reverse_markdown'
 
 module Translatomatic::ResourceFile
+  # Markdown resource file
   class Markdown < HTML
 
     # (see Translatomatic::ResourceFile::Base.extensions)
@@ -10,17 +11,17 @@ module Translatomatic::ResourceFile
     end
 
     # (see Translatomatic::ResourceFile::Base#save)
-    def save(target = path, options = {})
-      if @doc
-        begin
-          add_created_by unless options[:no_created_by]
-          html = @doc.to_html
-          # convert html back to markdown
-          markdown = ReverseMarkdown.convert(html, unknown_tags: :bypass)
-          target.write(markdown.chomp)
-        rescue Exception => e
-          puts "error: #{e.message}"
-        end
+    def save(target = path, options = {})
+      if @doc
+        begin
+          add_created_by unless options[:no_created_by]
+          html = @doc.to_html
+          # convert html back to markdown
+          markdown = ReverseMarkdown.convert(html, unknown_tags: :bypass)
+          target.write(markdown.chomp)
+        rescue Exception => e
+          log.error t("resource.error", message: e.message)
+        end
       end
     end
 
@@ -44,7 +45,7 @@ module Translatomatic::ResourceFile
         end
         init_nodemap(@doc)
       rescue Exception => e
-        log.error(e.message)
+        log.error t("resource.error", message: e.message)
         @valid = false
         {}
       end

data/lib/translatomatic/resource_file/plist.rb

@@ -1,25 +1,14 @@
 module Translatomatic::ResourceFile
+  # Property list resource file
+  # @see https://en.wikipedia.org/wiki/Property_list
   class Plist < XML
+    include Translatomatic::ResourceFile::XCodeStringsLocalePath
 
     # (see Translatomatic::ResourceFile::Base.extensions)
     def self.extensions
       %w{plist}
     end
 
-    # (see Translatomatic::ResourceFile::Base#locale_path)
-    # @note localization files in XCode use the following file name
-    #   convention: Project/locale.lproj/filename
-    # @todo refactor this and xcode_strings.rb to use the same code
-    def locale_path(locale)
-      if path.to_s.match(/\/([-\w]+).lproj\/.+.plist$/)
-        # xcode style
-        filename = path.basename
-        path.parent.parent + (locale.to_s + ".lproj") + filename
-      else
-        super(locale)
-      end
-    end
-
     private
 
     def text_nodes_xpath