google-cloud-translate-v2 0.1.0

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

@@ -0,0 +1,180 @@
+# 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/translate/v2/api"
+require "google/cloud/translate/v2/version"
+require "google/cloud" unless defined? Google::Cloud.new
+require "google/cloud/env"
+
+module Google
+  module Cloud
+    module Translate
+      ##
+      # # Google Cloud Translation API
+      #
+      # [Google Cloud Translation API](https://cloud.google.com/translation/)
+      # provides a simple, programmatic interface for translating an arbitrary
+      # string into any supported language. It is highly responsive, so websites
+      # and applications can integrate with Translation API for fast, dynamic
+      # translation of source text. Language detection is also available in cases
+      # where the source language is unknown.
+      #
+      # Translation API supports more than one hundred different languages, from
+      # Afrikaans to Zulu. Used in combination, this enables translation between
+      # thousands of language pairs. Also, you can send in HTML and receive HTML
+      # with translated text back. You don't need to extract your source text or
+      # reassemble the translated content.
+      #
+      module V2
+        ##
+        # Creates a new object for connecting to Cloud Translation API. Each call creates a new connection.
+        #
+        # Like other Cloud Platform services, Google Cloud Translation API supports authentication using a project ID
+        # and OAuth 2.0 credentials. In addition, it supports authentication using a public API access key. (If both the
+        # API key and the project and OAuth 2.0 credentials are provided, the API key will be used.) Instructions and
+        # configuration options are covered in the {file:AUTHENTICATION.md Authentication Guide}.
+        #
+        # @param [String] project_id Project identifier for the Cloud Translation service you are connecting to. If not
+        #   present, the default project for the credentials is used.
+        # @param [String, Hash, Google::Auth::Credentials] credentials The path to the keyfile as a String, the contents
+        #   of the keyfile as a Hash, or a Google::Auth::Credentials object. (See {Translate::V2::Credentials})
+        # @param [String] key a public API access key (not an OAuth 2.0 token)
+        # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the set of resources and operations that
+        #   the connection can access. See [Using OAuth 2.0 to Access Google
+        #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+        #
+        #   The default scope is:
+        #
+        #   * `https://www.googleapis.com/auth/cloud-platform`
+        # @param [Integer] retries Number of times to retry requests on server error. The default value is `3`.
+        #   Optional.
+        # @param [Integer] timeout Default timeout to use in requests. Optional.
+        # @param [String] endpoint Override of the endpoint host name. Optional. If the param is nil, uses the default
+        #   endpoint.
+        #
+        # @return [Google::Cloud::Translate::V2::Api]
+        #
+        # @example
+        #   require "google/cloud/translate/v2"
+        #
+        #   translate = Google::Cloud::Translate::V2.new(
+        #     version: :v2,
+        #     project_id: "my-todo-project",
+        #     credentials: "/path/to/keyfile.json"
+        #   )
+        #
+        #   translation = translate.translate "Hello world!", to: "la"
+        #   translation.text #=> "Salve mundi!"
+        #
+        # @example Using API Key.
+        #   require "google/cloud/translate/v2"
+        #
+        #   translate = Google::Cloud::Translate::V2.new(
+        #     key: "api-key-abc123XYZ789"
+        #   )
+        #
+        #   translation = translate.translate "Hello world!", to: "la"
+        #   translation.text #=> "Salve mundi!"
+        #
+        # @example Using API Key from the environment variable.
+        #   require "google/cloud/translate/v2"
+        #
+        #   ENV["TRANSLATE_KEY"] = "api-key-abc123XYZ789"
+        #
+        #   translate = Google::Cloud::Translate::V2.new
+        #
+        #   translation = translate.translate "Hello world!", to: "la"
+        #   translation.text #=> "Salve mundi!"
+        #
+        def self.new project_id: nil, credentials: nil, key: nil, scope: nil, retries: nil, timeout: nil, endpoint: nil
+          project_id ||= default_project_id
+
+          configuration = translation_config
+          key ||= configuration&.key || ENV["TRANSLATE_KEY"] || ENV["GOOGLE_CLOUD_KEY"]
+          retries ||= configuration&.retries
+          timeout ||= configuration&.timeout
+          endpoint ||= configuration&.endpoint
+
+          if key
+            return Google::Cloud::Translate::V2::Api.new(
+              Google::Cloud::Translate::V2::Service.new(
+                project_id.to_s, nil, retries: retries, timeout: timeout, key: key, host: endpoint
+              )
+            )
+          end
+
+          scope ||= configuration&.scope
+          credentials ||= default_credentials scope: scope
+
+          unless credentials.is_a? Google::Auth::Credentials
+            credentials = Google::Cloud::Translate::V2::Credentials.new credentials, scope: scope
+          end
+
+          project_id = resolve_project_id project_id, credentials
+          raise ArgumentError, "project_id is missing" if project_id.empty?
+
+          Google::Cloud::Translate::V2::Api.new(
+            Google::Cloud::Translate::V2::Service.new(
+              project_id, credentials, retries: retries, timeout: timeout, host: endpoint
+            )
+          )
+        end
+
+        ##
+        # @private Default project.
+        def self.default_project_id
+          translation_config&.project_id ||
+            ENV["TRANSLATE_PROJECT"] ||
+            Google::Cloud.configure.project_id ||
+            Google::Cloud.env.project_id
+        end
+
+        ##
+        # @private Default credentials.
+        def self.default_credentials scope: nil
+          translation_config&.credentials ||
+            Google::Cloud::Config.credentials_from_env(
+              "TRANSLATE_CREDENTIALS", "TRANSLATE_CREDENTIALS_JSON", "TRANSLATE_KEYFILE", "TRANSLATE_KEYFILE_JSON"
+            ) ||
+            Google::Cloud.configure.credentials ||
+            Google::Cloud::Translate::V2::Credentials.default(scope: scope)
+        end
+
+        ##
+        # @private Default configuration.
+        def self.default_config
+          Google::Cloud.configure
+        end
+
+        ##
+        # @private Resolve project.
+        def self.resolve_project_id project_id, credentials
+          # Always cast to a string
+          return project_id.to_s unless credentials.respond_to? :project_id
+
+          # Always cast to a string
+          project_id || credentials.project_id.to_s
+        end
+
+        ##
+        # @private The global config from google-cloud-translate, or nil if not available
+        def self.translation_config
+          return nil unless Google::Cloud.configure.subconfig? :translate
+          Google::Cloud.configure.translate
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,254 @@
+# 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/translate/v2/service"
+require "google/cloud/translate/v2/translation"
+require "google/cloud/translate/v2/detection"
+require "google/cloud/translate/v2/language"
+
+module Google
+  module Cloud
+    module Translate
+      module V2
+        ##
+        # # Api
+        #
+        # Represents top-level access to the Google Cloud Translation API. Translation API supports more than one
+        # hundred different languages, from Afrikaans to Zulu. Used in combination, this enables translation between
+        # thousands of language pairs. Also, you can send in HTML and receive HTML with translated text back. You don't
+        # need to extract your source text or reassemble the translated content.
+        #
+        # @see https://cloud.google.com/translation/docs/getting-started Cloud Translation API Quickstart
+        #
+        # @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 Api
+          ##
+          # @private The Service object.
+          attr_accessor :service
+
+          ##
+          # @private Creates a new Api instance.
+          #
+          # See {Google::Cloud.translate}
+          def initialize service
+            @service = service
+          end
+
+          ##
+          # The Cloud Translation API project connected to.
+          #
+          # @example
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new(
+          #     project_id: "my-todo-project",
+          #     credentials: "/path/to/keyfile.json"
+          #   )
+          #
+          #   translate.project_id #=> "my-todo-project"
+          #
+          def project_id
+            service.project_id
+          end
+          alias project project_id
+
+          ##
+          # Returns text translations from one language to another.
+          #
+          # @see https://cloud.google.com/translation/docs/translating-text#Translate Translating Text
+          #
+          # @param [String] text The text or texts to translate.
+          # @param [String] to The target language into which the text should be translated. This is required. The value
+          #   must be an [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code.
+          # @param [String] from The source language of the text or texts. This is an [ISO
+          #   639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. This is optional.
+          # @param [String] format The format of the text. Possible values include `:text` and `:html`. This is
+          #   optional. The Translation API default is `:html`.
+          # @param [String] model The model used by the service to perform the translation. Can be either `base` to use
+          #   the Phrase-Based Machine Translation (PBMT) model, or `nmt` to use the Neural Machine Translation (NMT)
+          #   model. The default is `nmt`.
+          #
+          #    If the model is `nmt`, and the requested language translation pair is not supported for the NMT model,
+          #    then the request is translated using the PBMT model.
+          #
+          # @param [String] cid The customization id for translate. This is optional.
+          #
+          # @return [Translation, Array<Translation>] A single {Translation} object if just one text was given, or an
+          #   array of {Translation} objects if multiple texts were given.
+          #
+          # @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.detected? #=> true
+          #   translation.from #=> "en"
+          #   translation.origin #=> "Hello world!"
+          #   translation.to #=> "la"
+          #   translation.text #=> "Salve mundi!"
+          #   translation.model #=> "base"
+          #
+          # @example Using the neural machine translation model:
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   translation = translate.translate "Hello world!",
+          #                                     to: "la", model: "nmt"
+          #
+          #   translation.to_s #=> "Salve mundi!"
+          #   translation.model #=> "nmt"
+          #
+          # @example Setting the `from` language.
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   translation = translate.translate "Hello world!",
+          #                                     from: :en, to: :la
+          #   translation.detected? #=> false
+          #   translation.text #=> "Salve mundi!"
+          #
+          # @example Retrieving multiple translations.
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   translations = translate.translate "Hello my friend.",
+          #                                      "See you soon.",
+          #                                      from: "en", to: "la"
+          #   translations.count #=> 2
+          #   translations[0].text #=> "Salve amice."
+          #   translations[1].text #=> "Vide te mox."
+          #
+          # @example Preserving HTML tags.
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   translation = translate.translate "<strong>Hello</strong> world!",
+          #                                     to: :la
+          #   translation.text #=> "<strong>Salve</strong> mundi!"
+          #
+          def translate *text, to: nil, from: nil, format: nil, model: nil, cid: nil
+            return nil if text.empty?
+            raise ArgumentError, "to is required" if to.nil?
+            to = to.to_s
+            from = from.to_s if from
+            format = format.to_s if format
+            text = Array(text).flatten
+            gapi = service.translate text, to: to, from: from, format: format, model: model, cid: cid
+            Translation.from_gapi_list gapi, text, to, from
+          end
+
+          ##
+          # Detect the most likely language or languages of a text or multiple texts.
+          #
+          # @see https://cloud.google.com/translation/docs/detecting-language Detecting Language
+          #
+          # @param [String] text The text or texts upon which language detection should be performed.
+          #
+          # @return [Detection, Array<Detection>] A single {Detection} object if just one text was given, or an array
+          #   of {Detection} objects if multiple texts were given.
+          #
+          # @example
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   detection = translate.detect "Hello world!"
+          #   detection.language #=> "en"
+          #   detection.confidence #=> 0.7100697
+          #
+          # @example Detecting multiple texts.
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   detections = translate.detect "Hello world!",
+          #                                 "Bonjour le monde!"
+          #   detections.count #=> 2
+          #   detections.first.language #=> "en"
+          #   detections.first.confidence #=> 0.7100697
+          #   detections.last.language #=> "fr"
+          #   detections.last.confidence #=> 0.40440267
+          #
+          def detect *text
+            return nil if text.empty?
+            text = Array(text).flatten
+            gapi = service.detect text
+            Detection.from_gapi gapi, text
+          end
+
+          ##
+          # List the languages supported by the API. These are the languages to and from which text can be translated.
+          #
+          # @see https://cloud.google.com/translation/docs/discovering-supported-languages
+          #   Discovering Supported Languages
+          #
+          # @param [String] language The language and collation in which the names of the languages are returned. If
+          #   this is `nil` then no names are returned.
+          #
+          # @return [Array<Language>] An array of {Language} objects supported by the API.
+          #
+          # @example
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   languages = translate.languages
+          #   languages.count #=> 104
+          #
+          #   english = languages.detect { |l| l.code == "en" }
+          #   english.name #=> nil
+          #
+          # @example Get all languages with their names in French.
+          #   require "google/cloud/translate/v2"
+          #
+          #   translate = Google::Cloud::Translate::V2.new
+          #
+          #   languages = translate.languages "fr"
+          #   languages.count #=> 104
+          #
+          #   english = languages.detect { |l| l.code == "en" }
+          #   english.name #=> "Anglais"
+          #
+          def languages language = nil
+            language = language.to_s if language
+            gapi = service.languages language
+            Array(gapi["languages"]).map { |g| Language.from_gapi g }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# 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 "googleauth"
+
+module Google
+  module Cloud
+    module Translate
+      module V2
+        ##
+        # # Credentials
+        #
+        # Represents the authentication and authorization used to connect to the Cloud Translation API.
+        #
+        # @example
+        #   require "google/cloud/translate/v2"
+        #
+        #   keyfile = "/path/to/keyfile.json"
+        #   creds = Google::Cloud::Translate::V2::Credentials.new keyfile
+        #
+        #   translate = Google::Cloud::Translate.new(
+        #     version: :v2,
+        #     project_id: "my-todo-project",
+        #     credentials: creds
+        #   )
+        #
+        #   translate.project_id #=> "my-todo-project"
+        #
+        class Credentials < Google::Auth::Credentials
+          SCOPE = ["https://www.googleapis.com/auth/cloud-platform"].freeze
+          PATH_ENV_VARS = ["TRANSLATE_CREDENTIALS",
+                           "TRANSLATE_KEYFILE",
+                           "GOOGLE_CLOUD_CREDENTIALS",
+                           "GOOGLE_CLOUD_KEYFILE",
+                           "GCLOUD_KEYFILE"].freeze
+          JSON_ENV_VARS = ["TRANSLATE_CREDENTIALS_JSON",
+                           "TRANSLATE_KEYFILE_JSON",
+                           "GOOGLE_CLOUD_CREDENTIALS_JSON",
+                           "GOOGLE_CLOUD_KEYFILE_JSON",
+                           "GCLOUD_KEYFILE_JSON"].freeze
+          DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"].freeze
+        end
+      end
+    end
+  end
+end