google-cloud-translate 1.4.0 → 2.0.0

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

@@ -1,274 +0,0 @@
-# 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/service"
-require "google/cloud/translate/translation"
-require "google/cloud/translate/detection"
-require "google/cloud/translate/language"
-
-module Google
-  module Cloud
-    module Translate
-      ##
-      # # 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
-      #
-      #   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(
-        #     project_id: "my-todo-project",
-        #     credentials: "/path/to/keyfile.json"
-        #   )
-        #
-        #   translate.project_id #=> "my-todo-project"
-        #
-        def project_id
-          service.project
-        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
-        #
-        #   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
-        #
-        #   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
-        #
-        #   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
-        #
-        #   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
-        #
-        #   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
-        #
-        #   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
-        #
-        #   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
-        #
-        #   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
-        #
-        #   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

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

@@ -1,57 +0,0 @@
-# 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
-      ##
-      # # 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::Credentials.new keyfile
-      #
-      #   translate = Google::Cloud::Translate.new(
-      #     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

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

@@ -1,139 +0,0 @@
-# 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
-      ##
-      # # Detection
-      #
-      # Represents a detect language query result. Returned by
-      # {Google::Cloud::Translate::Api#detect}.
-      #
-      # @see https://cloud.google.com/translation/docs/detecting-language
-      #   Detecting Language
-      #
-      # @example
-      #   require "google/cloud/translate"
-      #
-      #   translate = Google::Cloud::Translate.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::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