google-cloud-translate-v2 0.1.0

data/lib/google/cloud/translate/v2/detection.rb

@@ -0,0 +1,132 @@
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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.
+
+
+module Google
+  module Cloud
+    module Translate
+      module V2
+        ##
+        # # Detection
+        #
+        # Represents a detect language query result. Returned by {Google::Cloud::Translate::V2::Api#detect}.
+        #
+        # @see https://cloud.google.com/translation/docs/detecting-language Detecting Language
+        #
+        # @example
+        #   require "google/cloud/translate/v2"
+        #
+        #   translate = Google::Cloud::Translate::V2.new
+        #
+        #   detections = translate.detect "chien", "chat"
+        #
+        #   detections.size #=> 2
+        #   detections[0].text #=> "chien"
+        #   detections[0].language #=> "fr"
+        #   detections[0].confidence #=> 0.7109375
+        #   detections[1].text #=> "chat"
+        #   detections[1].language #=> "en"
+        #   detections[1].confidence #=> 0.59922177
+        #
+        class Detection
+          ##
+          # The text upon which the language detection was performed.
+          #
+          # @return [String]
+          attr_reader :text
+
+          ##
+          # The list of detection results for the given text. The most likely language is listed first, and its
+          # attributes can be accessed through {#language} and {#confidence}.
+          #
+          # @return [Array<Detection::Result>]
+          attr_reader :results
+
+          ##
+          # @private Create a new object.
+          def initialize text, results
+            @text = text
+            @results = results
+          end
+
+          ##
+          # The confidence that the language detection result is correct. The closer this value is to 1, the higher the
+          # confidence in language detection.
+          #
+          # @return [Float] a value between 0 and 1
+          def confidence
+            return nil if results.empty?
+            results.first.confidence
+          end
+
+          ##
+          # The most likely language that was detected. This is an [ISO
+          # 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code.
+          #
+          # @return [String] the language code
+          def language
+            return nil if results.empty?
+            results.first.language
+          end
+
+          ##
+          # @private New Detection from a ListDetectionsResponse object as defined by the Google API Client object.
+          def self.from_gapi gapi, text
+            res = text.zip(Array(gapi["detections"])).map do |txt, detections|
+              results = detections.map { |g| Result.from_gapi g }
+              new txt, results
+            end
+            return res.first if res.size == 1
+            res
+          end
+
+          ##
+          # # Result
+          #
+          # Represents an individual result in a {Google::Cloud::Translate::V2::Detection} result.
+          #
+          class Result
+            ##
+            # The confidence that the language detection result is correct. The closer this value is to 1, the higher
+            # the confidence in language detection.
+            #
+            # @return [Float] a value between 0 and 1
+            attr_reader :confidence
+
+            ##
+            # The language detected. This is an [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
+            # language code.
+            #
+            # @return [String] the language code
+            attr_reader :language
+
+            ##
+            # @private Create a new object.
+            def initialize confidence, language
+              @confidence = confidence
+              @language = language
+            end
+
+            ##
+            # @private New Detection::Result from a DetectionsResource object as defined by the Google API Client
+            # object.
+            def self.from_gapi gapi
+              new gapi["confidence"], gapi["language"]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/translate/v2/language.rb

@@ -0,0 +1,68 @@
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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.
+
+
+module Google
+  module Cloud
+    module Translate
+      module V2
+        ##
+        # # Language
+        #
+        # Represents a supported languages query result. Returned by {Google::Cloud::Translate::V2::Api#languages}.
+        #
+        # @see https://cloud.google.com/translation/docs/discovering-supported-languages Discovering Supported Languages
+        #
+        # @example
+        #   require "google/cloud/translate/v2"
+        #
+        #   translate = Google::Cloud::Translate::V2.new
+        #
+        #   languages = translate.languages "en"
+        #
+        #   languages.size #=> 104
+        #   languages[0].code #=> "af"
+        #   languages[0].name #=> "Afrikaans"
+        #
+        class Language
+          ##
+          # The language code. This is an [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language
+          # code.
+          #
+          # @return [String]
+          attr_reader :code
+
+          ##
+          # The localized name of the language, if available.
+          #
+          # @return [String]
+          attr_reader :name
+
+          ##
+          # @private Create a new object.
+          def initialize code, name
+            @code = code
+            @name = name
+          end
+
+          ##
+          # @private New Language from a LanguagesResource object as defined by the Google API Client object.
+          def self.from_gapi gapi
+            new gapi["language"], gapi["name"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/translate/v2/service.rb

@@ -0,0 +1,210 @@
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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 "google/cloud/errors"
+require "google/cloud/translate/v2/credentials"
+require "google/cloud/translate/v2/version"
+require "faraday"
+require "uri"
+
+module Google
+  module Cloud
+    module Translate
+      module V2
+        ##
+        # @private
+        # Represents the Translation API REST service, exposing the API calls.
+        class Service #:nodoc:
+          API_VERSION = "v2".freeze
+          API_URL = "https://translation.googleapis.com".freeze
+
+          # @private
+          attr_accessor :project_id, :credentials, :retries, :timeout, :key
+
+          ##
+          # Creates a new Service instance.
+          def initialize project_id, credentials, retries: nil, timeout: nil, key: nil, host: nil
+            @project_id = project_id
+            @credentials = credentials
+            @retries = retries
+            @timeout = timeout
+            @key = key
+            @host = host || API_URL
+          end
+
+          ##
+          # Returns Hash of ListTranslationsResponse JSON
+          def translate text, to: nil, from: nil, format: nil, model: nil, cid: nil
+            body = {
+              q: Array(text), target: to, source: from, format: format,
+              model: model, cid: cid
+            }.delete_if { |_k, v| v.nil? }.to_json
+
+            post "/language/translate/v2", body
+          end
+
+          ##
+          # Returns API::ListDetectionsResponse
+          def detect text
+            body = { q: Array(text) }.to_json
+
+            post "language/translate/v2/detect", body
+          end
+
+          ##
+          # Returns API::ListLanguagesResponse
+          def languages language = nil
+            body = { target: language }.to_json
+
+            post "language/translate/v2/languages", body
+          end
+
+          def inspect
+            self.class.to_s
+          end
+
+          protected
+
+          def post path, body = nil
+            response = execute do
+              http.post path do |req|
+                req.headers.merge! default_http_headers
+                req.body = body unless body.nil?
+
+                if @key
+                  req.params = { key: @key }
+                else
+                  sign_http_request! req
+                end
+              end
+            end
+
+            return JSON.parse(response.body)["data"] if response.success?
+
+            raise Google::Cloud::Error.gapi_error_class_for(response.status)
+          rescue Faraday::ConnectionFailed
+            raise Google::Cloud::ResourceExhaustedError
+          end
+
+          ##
+          # The HTTP object that makes calls to API.
+          # This must be a Faraday object.
+          def http
+            @http ||= Faraday.new url: @host, request: {
+              open_timeout: @timeout, timeout: @timeout
+            }.delete_if { |_k, v| v.nil? }
+          end
+
+          ##
+          # The default HTTP headers to be sent on all API calls.
+          def default_http_headers
+            @default_http_headers ||= begin
+              lib_version = Google::Cloud::Translate::V2::VERSION
+              headers = {
+                "User-Agent"                   => "gcloud-ruby/#{lib_version}",
+                "google-cloud-resource-prefix" => "projects/#{@project}",
+                "Content-Type"                 => "application/json",
+                "x-goog-api-client"            => "gl-ruby/#{RUBY_VERSION} gccl/#{lib_version}"
+              }
+              headers["x-goog-user-project"] = credentials.quota_project_id if credentials.respond_to? :quota_project_id
+              headers
+            end
+          end
+
+          ##
+          # Make a request and apply incremental backoff
+          def execute
+            backoff = Backoff.new retries: retries
+            backoff.execute do
+              yield
+            end
+          rescue Faraday::ConnectionFailed
+            raise Google::Cloud::ResourceExhaustedError
+          end
+
+          ##
+          # Sign Oauth2 API calls.
+          def sign_http_request! request
+            client = credentials.client
+            return if client.nil?
+
+            client.fetch_access_token! if client.expires_within? 30
+            client.generate_authenticated_request request: request
+            request
+          end
+
+          ##
+          # @private Backoff
+          class Backoff
+            class << self
+              attr_accessor :retries
+              attr_accessor :http_codes
+              attr_accessor :reasons
+              attr_accessor :backoff # :nodoc:
+            end
+
+            # Set the default values
+            self.retries = 3
+            self.http_codes = [500, 503]
+            self.reasons = ["rateLimitExceeded", "userRateLimitExceeded"]
+            self.backoff = ->(retries) { sleep retries.to_i }
+
+            def initialize options = {} #:nodoc:
+              @max_retries  = (options[:retries]    || Backoff.retries).to_i
+              @http_codes   = (options[:http_codes] || Backoff.http_codes).to_a
+              @reasons      = (options[:reasons]    || Backoff.reasons).to_a
+              @backoff      =  options[:backoff]    || Backoff.backoff
+            end
+
+            def execute #:nodoc:
+              current_retries = 0
+              loop do
+                response = yield # Expecting Faraday::Response
+                return response if response.success?
+                break response unless retry? response, current_retries
+                current_retries += 1
+                @backoff.call current_retries
+              end
+            end
+
+            protected
+
+            def retry? result, current_retries #:nodoc:
+              if current_retries < @max_retries
+                return true if retry_http_code? result
+                return true if retry_error_reason? result
+              end
+              false
+            end
+
+            def retry_http_code? response #:nodoc:
+              @http_codes.include? response.status
+            end
+
+            def retry_error_reason? response #:nodoc:
+              result = JSON.parse response.body
+              if result && result["error"] && result["error"]["errors"]
+                Array(result["error"]["errors"]).each do |error|
+                  return true if error["reason"] && @reasons.include?(error["reason"])
+                end
+              end
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/translate/v2/translation.rb

@@ -0,0 +1,120 @@
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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.
+
+
+module Google
+  module Cloud
+    module Translate
+      module V2
+        ##
+        # # Translation
+        #
+        # Represents a translation query result. Returned by {Google::Cloud::Translate::V2::Api#translate}.
+        #
+        # @see https://cloud.google.com/translation/docs/translating-text#Translate Translating Text
+        #
+        # @example
+        #   require "google/cloud/translate/v2"
+        #
+        #   translate = Google::Cloud::Translate::V2.new
+        #
+        #   translation = translate.translate "Hello world!", to: "la"
+        #
+        #   translation.to_s #=> "Salve mundi!"
+        #
+        #   translation.from #=> "en"
+        #   translation.origin #=> "Hello world!"
+        #   translation.to #=> "la"
+        #   translation.text #=> "Salve mundi!"
+        #
+        class Translation
+          ##
+          # The translated result.
+          #
+          # @return [String]
+          attr_reader :text
+          alias to_s text
+          alias to_str text
+
+          ##
+          # The original query text that was translated.
+          #
+          # @return [String]
+          attr_reader :origin
+
+          ##
+          # The target language into which the text was translated.
+          #
+          # @return [String]
+          attr_reader :to
+          alias language to
+          alias target to
+
+          ##
+          # The source language from which the text was translated.
+          #
+          # @return [String]
+          attr_reader :from
+          alias source from
+
+          ##
+          # The translation model. Can be either `base` for the Phrase-Based Machine Translation (PBMT) model, or `nmt`
+          # for the Neural Machine Translation (NMT) model. If you did not include a model parameter with your request,
+          # then this field is not included in the response.
+          #
+          # @return [String]
+          attr_reader :model
+
+          ##
+          # @private Create a new object.
+          def initialize text, to, origin, from, model, detected
+            @text = text
+            @to = to
+            @origin = origin
+            @from = from
+            @model = model
+            @detected = detected
+          end
+
+          ##
+          # Determines if the source language was detected by the Google Cloud Cloud Translation API.
+          #
+          # @return [Boolean] `true` if the source language was detected by the Cloud Translation API, `false` if the
+          #   source language was provided in the request
+          def detected?
+            @detected
+          end
+
+          ##
+          # @private New Translation from a TranslationsListResponse object as defined by the Google API Client object.
+          def self.from_gapi_list gapi, text, to, from
+            res = text.zip(Array(gapi["translations"])).map do |origin, g|
+              from_gapi g, to, origin, from
+            end
+            return res.first if res.size == 1
+            res
+          end
+
+          ##
+          # @private New Translation from a TranslationsResource object as defined by the Google API Client object.
+          def self.from_gapi gapi, to, origin, from
+            from ||= gapi["detectedSourceLanguage"]
+            detected = !gapi["detectedSourceLanguage"].nil?
+            new gapi["translatedText"], to, origin, from, gapi["model"], detected
+          end
+        end
+      end
+    end
+  end
+end