mygengo 1.0

data/README.md

@@ -0,0 +1,52 @@
+myGengo Ruby Library (for the [myGengo API](http://mygengo.com/))
+========================================================================================================
+Translating your tools and products helps people all over the world access them; this is, of course, a
+somewhat tricky problem to solve. **[myGengo](http://mygengo.com/)** is a service that offers human-translation
+(which is often a higher quality than machine translation), and an API to manage sending in work and watching
+jobs. This is a ruby interface to make using the API simpler (some would say incredibly easy). 
+
+
+Installation & Requirements
+-------------------------------------------------------------------------------------------------------
+Installing myGengo is fairly simple:
+
+    gem install mygengo
+
+
+Tests - Running Them, etc
+------------------------------------------------------------------------------------------------------
+myGengo has a full suite of tests, however they're not currently automated. Each script in the _examples_
+directory tests a different myGengo API endpoint; run against those if you wish to test for now.
+
+Question, Comments, Complaints, Praise?
+------------------------------------------------------------------------------------------------------
+If you have questions or comments and would like to reach us directly, please feel free to do
+so at the following outlets. We love hearing from developers!
+
+Email: ryan [at] mygengo dot com  
+Twitter: **[@mygengo_dev](http://twitter.com/mygengo_dev)**  
+
+If you come across any issues, please file them on the **[Github project issue tracker](https://github.com/myGengo/mygengo-ruby/issues)**. Thanks!
+
+
+Documentation
+------------------------------------------------------------------------------------------------------
+The usage of the API is very simple - the most important part is getting authenticated. To do this is just
+a few lines of code:
+
+``` ruby
+require 'mygengo'
+
+mygengo = MyGengo::API.new({
+	:public_key => 'your_public_key',
+	:private_key => 'your_private_key',
+	:sandbox => true, # Or false, depending on your work
+})
+
+# Get some information
+puts mygengo.getAccountBalance()
+```
+
+With that, you can call any number of methods supported by this library. The entire library is rdoc supported,
+so you can look at more method information there - there's also a full suite of test code/examples, located in the 'examples'
+directory. Good luck!

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestRake.new do |t|
+	t.libs << "test"
+	t.test_files = FileList['test/*test.rb']
+	t.verbose = true
+end

data/lib/mygengo-ruby/api_handler.rb

@@ -0,0 +1,286 @@
+# Encoding: UTF-8
+
+require 'rubygems'
+require 'net/http'
+require 'uri'
+require 'cgi'
+require 'json'
+require 'hmac-sha1'
+require 'time'
+
+module MyGengo
+	
+	# The only real class that ever needs to be instantiated.
+	class API
+		attr_accessor :api_host
+		attr_accessor :debug
+		attr_accessor :client_info
+
+		# Creates a new API handler to shuttle calls/jobs/etc over to the myGengo translation API.
+		#
+		# Options:
+		# <tt>opts</tt> - A hash containing the api key, the api secret key, the API version (defaults to 1), whether to use
+		# the sandbox API, and an optional custom user agent to send.
+		def initialize(opts)
+			# Consider this an example of the object you need to pass.
+			@opts = {
+				:public_key => '',
+				:private_key => '',
+				:api_version => '1.1',
+				:sandbox => false,
+				:user_agent => "myGengo Ruby Library v#{MyGengo::Config::VERSION}",
+				:debug => false,
+			}.merge(opts)
+
+			# Let's go ahead and separate these out, for clarity...
+			@debug = @opts[:debug]
+			@api_host = (@opts[:sandbox] == true ? MyGengo::Config::SANDBOX_API_HOST : MyGengo::Config::API_HOST)
+
+			# More of a public "check this" kind of object.
+			@client_info = {"VERSION" => MyGengo::Config::VERSION}
+		end
+
+		# This is... hilariously awkward, but Ruby escapes things very differently from PHP/etc. This causes
+		# issues with de-escaping things on the backend over at myGengo; in the future this will become obsolete,
+		# but for now we'll just leave this here...
+		def urlencode(string)
+			string.gsub(/([^ a-zA-Z0-9_.-]+)/n) do
+				'%' + $1.unpack('H2' * $1.size).join('%').upcase
+			end.tr(' ', '+')
+		end
+
+		# Creates an HMAC::SHA1 signature, signing the timestamp with the private key.
+		def signature_of(pk, ts)
+			HMAC::SHA1.hexdigest @opts[:private_key], ts
+		end
+
+		# The "GET" method; handles requesting basic data sets from myGengo and converting
+		# the response to a Ruby hash/object.
+		#
+		# Options:
+		# <tt>endpoint</tt> - String/URL to request data from.
+		# <tt>params</tt> - Data necessary for request (keys, etc). Generally taken care of by the requesting instance.
+		def get_from_mygengo(endpoint, params = {})
+			# The first part of the object we're going to encode and use in our request to myGengo. The signing process
+			# is a little annoying at the moment, so bear with us...
+			query = {
+				:api_key => @opts[:public_key],
+				:ts => Time.now.gmtime.to_i.to_s
+			}
+			
+			endpoint << "?api_sig=" + signature_of(query[:api_key], query[:ts])
+			endpoint << '&' + query.map { |k, v| "#{k}=#{urlencode(v)}" }.join('&')	
+
+			resp = Net::HTTP.start(@api_host, 80) do |http|
+				http.request(Net::HTTP::Get.new("/v#{@opts[:api_version]}/" + endpoint, {
+					'Accept' => 'application/json', 
+					'User-Agent' => @opts[:user_agent]
+				}))
+			end
+
+			json = JSON.parse(resp.body)
+
+			if json['opstat'] != 'ok'
+				raise MyGengo::Exception.new(json['opstat'], json['err']['code'].to_i, json['err']['msg'])
+			end
+
+			# Return it if there are no problems, nice...
+			json
+		end
+
+		# The "POST" method; handles shuttling up encoded job data to myGengo
+		# for translation and such. Somewhat similar to the above methods, but depending on the scenario
+		# can get some strange exceptions, so we're gonna keep them fairly separate for the time being. Consider
+		# for a merger down the road...
+		#
+		# Options:
+		# <tt>endpoint</tt> - String/URL to post data to.
+		# <tt>params</tt> - Data necessary for request (keys, etc). Generally taken care of by the requesting instance.
+		def send_to_mygengo(endpoint, params = {})
+			query = {
+				:api_key => @opts[:public_key],
+				:data => params.to_json.gsub('"', '\"'),
+				:ts => Time.now.gmtime.to_i.to_s
+			}
+
+			url = URI.parse("http://#{@api_host}/v#{@opts[:api_version]}/#{endpoint}")
+			http = Net::HTTP.new(url.host, url.port)
+			request = Net::HTTP::Post.new(url.path)
+	
+			request.add_field('Accept', 'application/json')
+			request.add_field('User-Agent', @opts[:user_agent])
+
+			request.content_type = 'application/x-www-form-urlencoded'
+			request.body = {
+				"api_sig" => signature_of(query[:api_key], query[:ts]),
+				"api_key" => urlencode(@opts[:public_key]),
+				"data" => urlencode(params.to_json.gsub('\\', '\\\\')),
+				"ts" => Time.now.gmtime.to_i.to_s
+			}.map { |k, v| "#{k}=#{v}" }.flatten.join('&')
+			
+			if @debug
+				http.set_debug_output($stdout)
+			end
+
+			resp = http.request(request)
+
+			case resp
+				when Net::HTTPSuccess, Net::HTTPRedirection
+					json = JSON.parse(resp.body)
+
+					if json['opstat'] != 'ok'
+						raise MyGengo::Exception.new(json['opstat'], json['err']['code'].to_i, json['err']['msg'])
+					end
+
+					# Return it if there are no problems, nice...
+					json
+				else
+					resp.error!
+			end
+		end
+
+		# Returns a Ruby-hash of the stats for the current account. No arguments required!
+		#
+		# Options:
+		# <tt>None</tt> - N/A
+		def getAccountStats(params = {})
+			self.get_from_mygengo('account/stats', params)
+		end
+
+		# Returns a Ruby-hash of the balance for the authenticated account. No args required!
+		#
+		# Options:
+		# <tt>None</tt> - N/A
+		def getAccountBalance(params = {})
+			self.get_from_mygengo('account/balance', params)
+		end
+
+		# Posts a translation job over to myGengo, returns a response indicating whether the submission was
+		# successful or not. Param list is quite expansive here, pay attention...
+		#
+		# Options:
+		# <tt>job</tt> - A job is a hash of data describing what you want translated. See the examples included for
+		# more information on what this should be. (type/slug/body_src/lc_src/lc_tgt/tier/auto_approve/comment/callback_url/custom_data)
+		def postTranslationJob(params = {})
+			self.send_to_mygengo('translate/job', params)
+		end
+
+		# Much like the above, but takes a hash titled "jobs" that is multiple jobs, each with their own unique key.
+		#
+		# Options:
+		# <tt>jobs</tt> - "Jobs" is a hash containing further hashes; each further hash is a job. This is best seen in the example code.
+		def postTranslationJobs(params = {})
+			self.send_to_mygengo('translate/jobs', params)
+		end
+
+		# Updates an already submitted job.
+		#
+		# Options:
+		# <tt>id</tt> - The ID of a job to update.
+		# <tt>action</tt> - A hash describing the update to this job. See the examples for further documentation.
+		def updateTranslationJob(params = {})
+			self.send_to_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Given an ID, pulls down information concerning that job from myGengo.
+		#
+		# <tt>id</tt> - The ID of a job to check.
+		# <tt>pre_mt</tt> - Optional, get a machine translation if the human translation is not done.
+		def getTranslationJob(params = {})
+			self.get_from_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Pulls down a list of recently submitted jobs, allows some filters.
+		#
+		# <tt>status</tt> - Optional. "unpaid", "available", "pending", "reviewable", "approved", "rejected", or "canceled".
+		# <tt>timestamp_after</tt> - Optional. Epoch timestamp from which to filter submitted jobs.
+		# <tt>count</tt> - Optional. Defaults to 10.
+		def getTranslationJobs(params = {})
+			self.get_from_mygengo('translate/jobs', params)
+		end
+
+		# Pulls a group of jobs that were previously submitted together.
+		#
+		# <tt>id</tt> - Required, the ID of a job that you want the batch/group of.
+		def getTranslationJobBatch(params = {})
+			self.get_from_mygengo('translate/jobs/:id'.gsub(':id', params.delete(:id)), params)
+		end
+	
+		# Mirrors the bulk Translation call, but just returns an estimated cost.
+		def determineTranslationCost(params = {})
+			self.send_to_mygengo('translate/service/quote', params)
+		end
+
+		# Post a comment for a translator or myGengo on a job.
+		#
+		# Options:
+		# <tt>id</tt> - The ID of the job you're commenting on.
+		# <tt>comment</tt> - The comment to put on the job.
+		def postTranslationJobComment(params = {})
+			self.send_to_mygengo('translate/job/:id/comment'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Get all comments (the history) from a given job.
+		#
+		# Options:
+		# <tt>id</tt> - The ID of the job to get comments for.
+		def getTranslationJobComments(params = {})
+			self.get_from_mygengo('translate/job/:id/comments'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Returns the feedback you've submitted for a given job.
+		#
+		# Options:
+		# <tt>id</tt> - The ID of the translation job you're retrieving comments from.
+		def getTranslationJobFeedback(params = {})
+			self.get_from_mygengo('translate/job/:id/feedback'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Gets a list of the revision resources for a job. Revisions are created each time a translator updates the text.
+		#
+		# Options:
+		# <tt>id</tt> - The ID of the translation job you're getting revisions from.
+		def getTranslationJobRevisions(params = {})
+			self.get_from_mygengo('translate/job/:id/revisions'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Get a specific revision to a job.
+		# 
+		# Options:
+		# <tt>id</tt> - The ID of the translation job you're getting revisions from.
+		# <tt>rev_id</tt> - The ID of the revision you're looking up.
+		def getTranslationJobRevision(params = {})
+			self.get_from_mygengo('translate/job/:id/revisions/:revision_id'.gsub(':id', params.delete(:id)).gsub(':rev_id', params.delete(:rev_id)), params)
+		end
+
+		# Returns a preview image for a job.
+		#
+		# Options:
+		# <tt>id</tt> - The ID of the job you want a preview image of.
+		def getTranslationJobPreviewImage(params = {})
+			self.get_from_mygengo('translate/job/:id/preview'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Deletes a job.
+		#
+		# Options:
+		# <tt>id</tt> - The ID of the job you want to delete.
+		def deleteTranslationJob(params = {})
+			self.send_to_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params)
+		end
+
+		# Gets information about currently supported language pairs.
+		#
+		# Options:
+		# <tt>lc_src</tt> - Optional language code to filter on.
+		def getServiceLanguagePairs(params = {})
+			self.get_from_mygengo('translate/service/language_pairs', params)
+		end
+
+		# Pulls down currently supported languages.
+		def getServiceLanguages(params = {})
+			self.get_from_mygengo('translate/service/languages', params)
+		end
+	end
+
+end

data/lib/mygengo-ruby/mygengo_exception.rb

@@ -0,0 +1,15 @@
+module MyGengo
+	# Base Exception class and such.
+	class MyGengo::Exception < ::StandardError
+		attr_accessor :opstat, :code, :msg
+
+		# Pretty self explanatory stuff here...
+		def initialize(opstat, code, msg)
+			@opstat = opstat
+			@code = code
+			@msg = msg
+
+			puts msg
+		end
+	end
+end

data/lib/mygengo.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'mygengo-ruby/api_handler'
+require 'mygengo-ruby/mygengo_exception'
+
+module MyGengo
+	# Store global config objects here - e.g, urls, etc.
+	module Config
+		# API url endpoints; replace the version at function call time to
+		# allow for function-by-function differences in versioning.
+		API_HOST = 'api.mygengo.com'
+		SANDBOX_API_HOST = 'api.sandbox.mygengo.com'
+
+		# Pretty self explanatory.
+		VERSION = '1.1'
+	end
+end

data/licenses/LICENSE.txt

@@ -0,0 +1,18 @@
+All code provided from the http://mygengo.com site, such as API example code and libraries, is provided under the New BSD license unless otherwise noted. Details are below.
+ 
+New BSD License
+Copyright (c) 2009-2011, myGengo, Inc.
+All rights reserved.
+ 
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+ 
+Redistributions of source code must retain the above copyright notice, 
+this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, 
+this list of conditions and the following disclaimer in the documentation 
+and/or other materials provided with the distribution.
+Neither the name of myGengo, Inc. nor the names of its contributors may 
+be used to endorse or promote products derived from this software 
+without specific prior written permission.
+ 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: mygengo
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: "1.0"
+platform: ruby
+authors: 
+- Ryan McGrath <ryan@mygengo.com>
+- Matthew Romaine
+- Kim Alhstrom
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-17 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: myGengo is a service that offers various translation APIs, both machine and high quality human-sourced. The mygengo gem lets you interface with the myGengo REST API (http://mygengo.com/services/api/dev-docs/).
+email: ryan@mygengo.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/mygengo-ruby/api_handler.rb
+- lib/mygengo-ruby/mygengo_exception.rb
+- lib/mygengo.rb
+- licenses/LICENSE.txt
+- Rakefile
+- README.md
+has_rdoc: true
+homepage: http://mygengo.com/services/api/dev-docs/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: A library for interfacing with the myGengo Translation API.
+test_files: []
+