Add Translate service

Add implementation, developer tests, and acceptance tests.
This is a big commit due to the churn in getting authentication correct.
The API discovery doc makes it seem that an OAuth token can be used,
but after several trials and errors this does not seem to be the case.
Authentication must be performed with an API Key, as it is done in
other language implementations such as gcloud-node.

acceptance/logging/logging_test.rb

@@ -14,7 +14,7 @@
 
 require "logging_helper"
 
-# This test is a ruby version of gcloud-node"s logging test.
+# This test is a ruby version of gcloud-node's logging test.
 
 describe Gcloud::Logging, :logging do
   describe "Sinks" do

acceptance/translate/translate_test.rb

@@ -0,0 +1,49 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "translate_helper"
+
+# This test is a ruby version of gcloud-node's translate test.
+
+describe Gcloud::Translate, :translate do
+  it "detects a langauge" do
+    translate.detect("Hello").results.first.language.must_equal "en"
+    translate.detect("Hola").results.first.language.must_equal "es"
+
+    detections = translate.detect "Hello", "Hola"
+    detections.count.must_equal 2
+    detections.first.results.first.language.must_equal "en"
+    detections.last.results.first.language.must_equal "es"
+  end
+
+  it "translates input" do
+    translate.translate("Hello", to: "es").text.must_equal "Hola"
+    translate.translate("How are you today?", to: "es").text.must_equal "Como estas hoy?"
+
+    translations = translate.translate "Hello", "How are you today?", to: "es"
+    translations.count.must_equal 2
+    translations.first.text.must_equal "Hola"
+    translations.last.text.must_equal "Como estas hoy?"
+  end
+
+  it "lists supported languages" do
+    languages = translate.languages
+    languages.count.must_be :>, 0
+    languages.first.name.must_be :nil?
+
+    languages = translate.languages "en"
+    languages.count.must_be :>, 0
+    languages.first.name.wont_be :nil?
+  end
+end

acceptance/translate_helper.rb

@@ -0,0 +1,71 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "helper"
+require "gcloud/translate"
+
+Gcloud::Backoff.retries = 10
+
+if ENV["GCLOUD_TEST_TRANSLATE_KEY"]
+  # Create shared translate object so we don't create new for each test
+  $translate = Gcloud.translate ENV["GCLOUD_TEST_TRANSLATE_KEY"]
+else
+  puts "No API Key found for the Translate acceptance tests."
+end
+
+module Acceptance
+  ##
+  # Test class for running against a Translate instance.
+  # Ensures that there is an active connection for the tests to use.
+  #
+  # This class can be used with the spec DSL.
+  # To do so, add :translate to describe:
+  #
+  #   describe "My Translate Test", :translate do
+  #     it "does a thing" do
+  #       your.code.must_be :thing?
+  #     end
+  #   end
+  class TranslateTest < Minitest::Test
+    attr_accessor :translate
+
+    ##
+    # Setup project based on available ENV variables
+    def setup
+      @translate = $translate
+
+      refute_nil @translate, "You do not have an active translate to run the tests."
+
+      super
+    end
+
+    # Add spec DSL
+    extend Minitest::Spec::DSL
+
+    # Register this spec type for when :translate is used.
+    register_spec_type(self) do |desc, *addl|
+      addl.include? :translate
+    end
+  end
+
+  def self.run_one_method klass, method_name, reporter
+    result = nil
+    (1..3).each do |try|
+      result = Minitest.run_one_method(klass, method_name)
+      break if (result.passed? || result.skipped?)
+      puts "Retrying #{klass}##{method_name} (#{try})"
+    end
+    reporter.record result
+  end
+end

lib/gcloud.rb

@@ -374,4 +374,25 @@ def logging scope: nil
     require "gcloud/logging"
     Gcloud.logging @project, @keyfile, scope: scope
   end
+
+  ##
+  # Creates a new object for connecting to the Translate service.
+  # Each call creates a new connection.
+  #
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
+  #
+  # @return [Gcloud::Translate::Api]
+  #
+  # @example
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   translate = gcloud.translate
+  #   # ...
+  #
+  def translate key = nil
+    require "gcloud/translate"
+    Gcloud.translate key
+  end
 end

lib/gcloud/translate.rb

@@ -0,0 +1,57 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "gcloud"
+require "gcloud/translate/api"
+
+module Gcloud
+  ##
+  # Creates a new `Api` instance connected to the Translate service.
+  # Each call creates a new connection.
+  #
+  # TODO: Add info for creatign an API Key here...
+  #
+  # @param [String] key API Key
+  #
+  # @return [Gcloud::Translate::Api]
+  #
+  # @example
+  #   require "gcloud"
+  #
+  #   translate = Gcloud.translate "api-key-abc123XYZ789"
+  #
+  #   zone = translate.zone "example-com"
+  #
+  # @example Using API Key from the environment variable.
+  #   require "gcloud"
+  #
+  #   ENV["TRANSLATE_KEY"] = "api-key-abc123XYZ789"
+  #
+  #   translate = Gcloud.translate
+  #
+  #   zone = translate.zone "example-com"
+  #
+  def self.translate key = nil
+    Gcloud::Translate::Api.new key
+  end
+
+  ##
+  # # Google Cloud Translate
+  #
+  # TODO
+  #
+  module Translate
+  end
+end

lib/gcloud/translate/api.rb

@@ -0,0 +1,81 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "gcloud/translate/connection"
+require "gcloud/translate/translation"
+require "gcloud/translate/detection"
+require "gcloud/translate/language"
+require "gcloud/translate/errors"
+
+module Gcloud
+  module Translate
+    ##
+    # TODO
+    class Api
+      ##
+      # @private The Connection object.
+      attr_accessor :connection
+
+      ##
+      # @private Creates a new Translate Api instance.
+      #
+      # See {Gcloud.translate}
+      def initialize key
+        key ||= ENV["TRANSLATE_KEY"]
+        if key.nil?
+          key_mising_msg = "An API key is required to use the Translate API."
+          fail ArgumentError, key_mising_msg
+        end
+        @connection = Connection.new key
+      end
+
+      ##
+      # TODO
+      def translate *text, to: nil, from: nil, format: nil, cid: nil,
+                    quota_user: nil, user_ip: nil
+        return nil if text.empty?
+        fail ArgumentError, "to is required" if to.nil?
+        to = to.to_s
+        from = from.to_s if from
+        format = format.to_s if format
+        resp = connection.translate(*text, to: to, from: from,
+                                           format: format, cid: cid,
+                                           quota_user: quota_user,
+                                           user_ip: user_ip)
+        fail ApiError.from_response(resp) unless resp.success?
+        Translation.from_response resp, text, to, from
+      end
+
+      ##
+      # TODO
+      def detect *text, quota_user: nil, user_ip: nil
+        return nil if text.empty?
+        resp = connection.detect(*text, quota_user: quota_user,
+                                        user_ip: user_ip)
+        fail ApiError.from_response(resp) unless resp.success?
+        Detection.from_response resp, text
+      end
+
+      ##
+      # TODO
+      def languages language = nil, quota_user: nil, user_ip: nil
+        resp = connection.languages language, quota_user: quota_user,
+                                              user_ip: user_ip
+        fail ApiError.from_response(resp) unless resp.success?
+        Array(resp.data["languages"]).map { |gapi| Language.from_gapi gapi }
+      end
+    end
+  end
+end

lib/gcloud/translate/connection.rb

@@ -0,0 +1,85 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "gcloud/version"
+require "google/api_client"
+
+module Gcloud
+  module Translate
+    ##
+    # @private Represents the connection to Translate, as well as expose the API
+    # calls
+    class Connection
+      API_VERSION = "v2"
+
+      attr_accessor :client
+
+      ##
+      # Creates a new Connection instance.
+      def initialize key
+        @client = Google::APIClient.new application_name:    "gcloud-ruby",
+                                        application_version: Gcloud::VERSION,
+                                        authorization: nil
+        @translate = @client.discovered_api "translate", API_VERSION
+        @client.key = key # set key after discovery, helps with tests
+      end
+
+      def translate *text, to: nil, from: nil, format: nil, cid: nil,
+                    quota_user: nil, user_ip: nil
+        params = { q:         text,
+                   target:    to,
+                   source:    from,
+                   format:    format,
+                   cid:       cid,
+                   quotaUser: quota_user,
+                   userIp:    user_ip
+                 }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @translate.translations.list,
+          parameters: params
+        )
+      end
+
+      def detect *text, quota_user: nil, user_ip: nil
+        params = { q:         text,
+                   quotaUser: quota_user,
+                   userIp:    user_ip
+                 }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @translate.detections.list,
+          parameters: params
+        )
+      end
+
+      def languages language = nil, quota_user: nil, user_ip: nil
+        params = { target:    language,
+                   quotaUser: quota_user,
+                   userIp:    user_ip
+                 }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @translate.languages.list,
+          parameters: params
+        )
+      end
+
+      def inspect
+        "#{self.class}(#{@project})"
+      end
+    end
+  end
+end