lib/google/cloud/translate.rb in google-cloud-translate-0.20.1 vs lib/google/cloud/translate.rb in google-cloud-translate-0.21.0
- old
+ new
@@ -51,14 +51,13 @@
# {Google::Cloud::Translate::Api#translate} are a string and the [ISO
# 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code of the
# language to which you wish to translate.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# translation = translate.translate "Hello world!", to: "la"
#
# puts translation #=> Salve mundi!
#
@@ -71,14 +70,13 @@
# You may want to use the `from` option to specify the language of the
# source text, as the following example illustrates. (Single words do not
# give Translate API much to work with.)
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# translation = translate.translate "chat", to: "en"
#
# translation.detected? #=> true
# translation.from #=> "en"
@@ -92,14 +90,13 @@
# ```
#
# You can pass multiple texts to {Google::Cloud::Translate::Api#translate}.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# translations = translate.translate "chien", "chat", from: "fr", to: "en"
#
# translations.size #=> 2
# translations[0].origin #=> "chien"
@@ -109,14 +106,13 @@
# ```
#
# By default, any HTML in your source text will be preserved.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# translation = translate.translate "<strong>Hello</strong> world!",
# to: :la
# translation.text #=> "<strong>Salve</strong> mundi!"
# ```
@@ -126,14 +122,13 @@
# You can use {Google::Cloud::Translate::Api#detect} to see which language
# the Translate API ranks as the most likely source language for a text. The
# `confidence` score is a float value between `0` and `1`.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# detection = translate.detect "chat"
#
# detection.text #=> "chat"
# detection.language #=> "en"
@@ -141,14 +136,13 @@
# ```
#
# You can pass multiple texts to {Google::Cloud::Translate::Api#detect}.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# detections = translate.detect "chien", "chat"
#
# detections.size #=> 2
# detections[0].text #=> "chien"
@@ -164,14 +158,13 @@
# Translate API adds new languages frequently. You can use
# {Google::Cloud::Translate::Api#languages} to query the list of supported
# languages.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# languages = translate.languages
#
# languages.size #=> 104
# languages[0].code #=> "af"
@@ -181,14 +174,13 @@
# To receive the names of the supported languages, as well as their [ISO
# 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes,
# provide the code for the language in which you wish to receive the names.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate
+ # translate = Google::Cloud::Translate.new
#
# languages = translate.languages "en"
#
# languages.size #=> 104
# languages[0].code #=> "af"
@@ -207,15 +199,63 @@
# reached.
#
# You can also set the request `timeout` value in seconds.
#
# ```ruby
- # require "google/cloud"
+ # require "google/cloud/translate"
#
- # gcloud = Google::Cloud.new
- # translate = gcloud.translate retries: 10, timeout: 120
+ # translate = Google::Cloud::Translate.new retries: 10, timeout: 120
# ```
#
module Translate
+ ##
+ # Creates a new object for connecting to the Translate service.
+ # Each call creates a new connection.
+ #
+ # Unlike other Cloud Platform services, which authenticate using a project
+ # ID and OAuth 2.0 credentials, Google Translate API requires a public API
+ # access key. (This may change in future releases of Google Translate
+ # API.) 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).
+ #
+ # @param [String] key a public API access key (not an OAuth 2.0 token)
+ # @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.
+ #
+ # @return [Google::Cloud::Translate::Api]
+ #
+ # @example
+ # require "google/cloud/translate"
+ #
+ # translate = Google::Cloud::Translate.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"
+ #
+ # ENV["TRANSLATE_KEY"] = "api-key-abc123XYZ789"
+ #
+ # translate = Google::Cloud::Translate.new
+ #
+ # translation = translate.translate "Hello world!", to: "la"
+ # translation.text #=> "Salve mundi!"
+ #
+ def self.new key: nil, retries: nil, timeout: nil
+ key ||= ENV["TRANSLATE_KEY"]
+ key ||= ENV["GOOGLE_CLOUD_KEY"]
+ if key.nil?
+ key_missing_msg = "An API key is required to use the Translate API."
+ fail ArgumentError, key_missing_msg
+ end
+
+ Google::Cloud::Translate::Api.new(
+ Google::Cloud::Translate::Service.new(
+ key, retries: retries, timeout: timeout))
+ end
end
end
end