google-cloud-translate 1.4.0 → 2.0.0

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

@@ -0,0 +1,205 @@
+# Copyright 2016 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/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 ||= {
+              "User-Agent"                   => "gcloud-ruby/#{Google::Cloud::Translate::VERSION}",
+              "google-cloud-resource-prefix" => "projects/#{@project}",
+              "Content-Type"                 => "application/json",
+              "x-goog-api-client"            => "gl-ruby/#{RUBY_VERSION} gccl/#{Google::Cloud::Translate::VERSION}"
+            }
+          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 2016 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"
+        #
+        #   translate = Google::Cloud::Translate.new version: :v2
+        #
+        #   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

data/lib/google/cloud/translate/v3.rb

@@ -0,0 +1,144 @@
+# Copyright 2019 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/translate/v3/translation_service_client"
+
+module Google
+  module Cloud
+    module Translate
+      # rubocop:disable LineLength
+
+      ##
+      # # Ruby Client for Cloud Translation API ([Alpha](https://github.com/googleapis/google-cloud-ruby#versioning))
+      #
+      # [Cloud Translation API][Product Documentation]:
+      # Integrates text translation into your website or application.
+      # - [Product Documentation][]
+      #
+      # ## Quick Start
+      # In order to use this library, you first need to go through the following
+      # steps:
+      #
+      # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+      # 2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+      # 3. [Enable the Cloud Translation API.](https://console.cloud.google.com/apis/library/translate.googleapis.com)
+      # 4. [Setup Authentication.](https://googleapis.dev/ruby/google-cloud-translate/latest/file.AUTHENTICATION.html)
+      #
+      # ### Installation
+      # ```
+      # $ gem install google-cloud-translate
+      # ```
+      #
+      # ### Next Steps
+      # - Read the [Cloud Translation API Product documentation][Product Documentation]
+      #   to learn more about the product and see How-to Guides.
+      # - View this [repository's main README](https://github.com/googleapis/google-cloud-ruby/blob/master/README.md)
+      #   to see the full list of Cloud APIs that we cover.
+      #
+      # [Product Documentation]: https://cloud.google.com/translate
+      #
+      # ## Enabling Logging
+      #
+      # To enable logging for this library, set the logger for the underlying [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library.
+      # The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as shown below,
+      # or a [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
+      # that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+      # and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
+      #
+      # Configuring a Ruby stdlib logger:
+      #
+      # ```ruby
+      # require "logger"
+      #
+      # module MyLogger
+      #   LOGGER = Logger.new $stderr, level: Logger::WARN
+      #   def logger
+      #     LOGGER
+      #   end
+      # end
+      #
+      # # Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+      # module GRPC
+      #   extend MyLogger
+      # end
+      # ```
+      #
+      module V3
+        # rubocop:enable LineLength
+
+        ##
+        # Provides natural language translation operations.
+        #
+        # @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]
+        #   Provides the means for authenticating requests made by the client. This parameter can
+        #   be many types.
+        #   A `Google::Auth::Credentials` uses a the properties of its represented keyfile for
+        #   authenticating requests made by this client.
+        #   A `String` will be treated as the path to the keyfile to be used for the construction of
+        #   credentials for this client.
+        #   A `Hash` will be treated as the contents of a keyfile to be used for the construction of
+        #   credentials for this client.
+        #   A `GRPC::Core::Channel` will be used to make calls through.
+        #   A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials
+        #   should already be composed with a `GRPC::Core::CallCredentials` object.
+        #   A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the
+        #   metadata for requests, generally, to give OAuth credentials.
+        # @param scopes [Array<String>]
+        #   The OAuth scopes for this service. This parameter is ignored if
+        #   an updater_proc is supplied.
+        # @param client_config [Hash]
+        #   A Hash for call options for each method. See
+        #   Google::Gax#construct_settings for the structure of
+        #   this data. Falls back to the default config if not specified
+        #   or the specified config is missing data points.
+        # @param timeout [Numeric]
+        #   The default timeout, in seconds, for calls made through this client.
+        # @param metadata [Hash]
+        #   Default metadata to be sent with each request. This can be overridden on a per call basis.
+        # @param service_address [String]
+        #   Override for the service hostname, or `nil` to leave as the default.
+        # @param service_port [Integer]
+        #   Override for the service port, or `nil` to leave as the default.
+        # @param exception_transformer [Proc]
+        #   An optional proc that intercepts any exceptions raised during an API call to inject
+        #   custom error handling.
+        def self.new \
+            credentials: nil,
+            scopes: nil,
+            client_config: nil,
+            timeout: nil,
+            metadata: nil,
+            service_address: nil,
+            service_port: nil,
+            exception_transformer: nil,
+            lib_name: nil,
+            lib_version: nil
+          kwargs = {
+            credentials: credentials,
+            scopes: scopes,
+            client_config: client_config,
+            timeout: timeout,
+            metadata: metadata,
+            exception_transformer: exception_transformer,
+            lib_name: lib_name,
+            service_address: service_address,
+            service_port: service_port,
+            lib_version: lib_version
+          }.select { |_, v| v != nil }
+          Google::Cloud::Translate::V3::TranslationServiceClient.new(**kwargs)
+        end
+      end
+    end
+  end
+end