google-cloud-translate 1.4.0 → 2.0.0

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

@@ -0,0 +1,255 @@
+# 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/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"
+        #
+        #   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 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"
+          #
+          #   translate = Google::Cloud::Translate.new(
+          #     version: :v2,
+          #     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"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   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"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   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"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   translation = translate.translate "Hello world!",
+          #                                     from: :en, to: :la
+          #   translation.detected? #=> false
+          #   translation.text #=> "Salve mundi!"
+          #
+          # @example Retrieving multiple translations.
+          #   require "google/cloud/translate"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   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"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   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"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   detection = translate.detect "Hello world!"
+          #   detection.language #=> "en"
+          #   detection.confidence #=> 0.7100697
+          #
+          # @example Detecting multiple texts.
+          #   require "google/cloud/translate"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   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"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   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"
+          #
+          #   translate = Google::Cloud::Translate.new version: :v2
+          #
+          #   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 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 "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"
+        #
+        #   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

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

@@ -0,0 +1,132 @@
+# 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
+        ##
+        # # 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"
+        #
+        #   translate = Google::Cloud::Translate.new version: :v2
+        #
+        #   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 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
+        ##
+        # # 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"
+        #
+        #   translate = Google::Cloud::Translate.new version: :v2
+        #
+        #   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