gcloud 0.7.2 → 0.8.0

data/lib/gcloud/translate/api.rb

@@ -0,0 +1,248 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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 "gcloud/translate/connection"
+require "gcloud/translate/translation"
+require "gcloud/translate/detection"
+require "gcloud/translate/language"
+require "gcloud/translate/errors"
+
+module Gcloud
+  module Translate
+    ##
+    # # Api
+    #
+    # Represents top-level access to the Google Translate API. Each instance
+    # requires a public API access key. To create a key, follow the general
+    # instructions at [Identifying your application to
+    # Google](https://cloud.google.com/translate/v2/using_rest#auth), and the
+    # specific instructions for [Server
+    # keys](https://cloud.google.com/translate/v2/using_rest#creating-server-api-keys).
+    # See {Gcloud#translate}.
+    #
+    # @see https://cloud.google.com/translate/v2/getting_started Translate API
+    #   Getting Started
+    #
+    # @example
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   translate = gcloud.translate
+    #
+    #   translation = translate.translate "Hello world!", to: "la"
+    #
+    #   puts translation #=> Salve mundi!
+    #
+    #   translation.from #=> "en"
+    #   translation.origin #=> "Hello world!"
+    #   translation.to #=> "la"
+    #   translation.text #=> "Salve mundi!"
+    #
+    class Api
+      ##
+      # @private The Connection object.
+      attr_accessor :connection
+
+      ##
+      # @private Creates a new Translate Api instance.
+      #
+      # See {Gcloud.translate}
+      def initialize key
+        key ||= ENV["TRANSLATE_KEY"]
+        if key.nil?
+          key_mising_msg = "An API key is required to use the Translate API."
+          fail ArgumentError, key_mising_msg
+        end
+        @connection = Connection.new key
+      end
+
+      ##
+      # Returns text translations from one language to another.
+      #
+      # @see https://cloud.google.com/translate/v2/using_rest#Translate
+      #   Translate 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 Translate API default is
+      #   `:html`.
+      # @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 "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   translation = translate.translate "Hello world!", to: "la"
+      #
+      #   puts translation #=> Salve mundi!
+      #
+      #   translation.detected? #=> true
+      #   translation.from #=> "en"
+      #   translation.origin #=> "Hello world!"
+      #   translation.to #=> "la"
+      #   translation.text #=> "Salve mundi!"
+      #
+      # @example Setting the `from` language.
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   translation = translate.translate "Hello world!",
+      #                                     from: :en, to: :la
+      #   translation.detected? #=> false
+      #   translation.text #=> "Salve mundi!"
+      #
+      # @example Retrieving multiple translations.
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   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 "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   translation = translate.translate "<strong>Hello</strong> world!",
+      #                                     to: :la
+      #   translation.text #=> "<strong>Salve</strong> mundi!"
+      #
+      def translate *text, to: nil, from: nil, format: nil, cid: nil
+        return nil if text.empty?
+        fail ArgumentError, "to is required" if to.nil?
+        to = to.to_s
+        from = from.to_s if from
+        format = format.to_s if format
+        resp = connection.translate(*text, to: to, from: from,
+                                           format: format, cid: cid)
+        fail ApiError.from_response(resp) unless resp.success?
+        Translation.from_response resp, text, to, from
+      end
+
+      ##
+      # Detect the most likely language or languages of a text or multiple
+      # texts.
+      #
+      # @see https://cloud.google.com/translate/v2/using_rest#detect-language
+      #   Detect 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 "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   detection = translate.detect "Hello world!"
+      #   puts detection.language #=> en
+      #   puts detection.confidence #=> 0.7100697
+      #
+      # @example Detecting multiple texts.
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   detections = translate.detect "Hello world!",
+      #                                 "Bonjour le monde!"
+      #   puts detections.count #=> 2
+      #   puts detection.first.language #=> en
+      #   puts detection.first.confidence #=> 0.7100697
+      #   puts detection.last.language #=> fr
+      #   puts detection.last.confidence #=> 0.40440267
+      #
+      def detect *text
+        return nil if text.empty?
+        resp = connection.detect(*text)
+        fail ApiError.from_response(resp) unless resp.success?
+        Detection.from_response resp, 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/translate/v2/using_rest#supported-languages
+      #   Discover 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 "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   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 "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   translate = gcloud.translate
+      #
+      #   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
+        resp = connection.languages language
+        fail ApiError.from_response(resp) unless resp.success?
+        Array(resp.data["languages"]).map { |gapi| Language.from_gapi gapi }
+      end
+    end
+  end
+end

data/lib/gcloud/translate/connection.rb

@@ -0,0 +1,76 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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 "gcloud/version"
+require "google/api_client"
+
+module Gcloud
+  module Translate
+    ##
+    # @private Represents the connection to Translate, as well as expose the API
+    # calls
+    class Connection
+      API_VERSION = "v2"
+
+      attr_accessor :client
+
+      ##
+      # Creates a new Connection instance.
+      def initialize key
+        @client = Google::APIClient.new application_name:    "gcloud-ruby",
+                                        application_version: Gcloud::VERSION,
+                                        authorization: nil
+        @translate = @client.discovered_api "translate", API_VERSION
+        @client.key = key # set key after discovery, helps with tests
+      end
+
+      def translate *text, to: nil, from: nil, format: nil, cid: nil
+        params = { q:           text,
+                   target:      to,
+                   source:      from,
+                   format:      format,
+                   cid:         cid,
+                   prettyprint: false
+                 }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @translate.translations.list,
+          parameters: params
+        )
+      end
+
+      def detect *text
+        @client.execute(
+          api_method: @translate.detections.list,
+          parameters: { q: text, prettyprint: false }
+        )
+      end
+
+      def languages language = nil
+        params = { target:      language,
+                   prettyprint: false }.delete_if { |_, v| v.nil? }
+
+        @client.execute(
+          api_method: @translate.languages.list,
+          parameters: params
+        )
+      end
+
+      def inspect
+        "#{self.class}(#{@project})"
+      end
+    end
+  end
+end

data/lib/gcloud/translate/detection.rb

@@ -0,0 +1,137 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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 Gcloud
+  module Translate
+    ##
+    # # Detection
+    #
+    # Represents a detect language query result. Returned by
+    # {Gcloud::Translate::Api#detect}.
+    #
+    # @see https://cloud.google.com/translate/v2/using_rest#detect-language
+    #   Detect Language
+    #
+    # @example
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   translate = gcloud.translate
+    #
+    #   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 DetectionsListResponse object as
+      # defined by the Google API Client object.
+      def self.from_response resp, text
+        res = text.zip(Array(resp.data.detections)).map do |txt, gapi_list|
+          results = gapi_list.map { |gapi| Result.from_gapi gapi }
+          new txt, results
+        end
+        return res.first if res.size == 1
+        res
+      end
+
+      ##
+      # # Result
+      #
+      # Represents an individual result in a {Gcloud::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