Module: Google::Cloud::Translate

Defined in:: lib/google/cloud/translate.rb,
lib/google/cloud/translate/api.rb,
lib/google/cloud/translate/service.rb,
lib/google/cloud/translate/version.rb,
lib/google/cloud/translate/language.rb,
lib/google/cloud/translate/detection.rb,
lib/google/cloud/translate/translation.rb

Overview

Google Translate API

Google Translate API 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 Translate API for fast, dynamic translation of source text. Language detection is also available in cases where the source language is unknown.

Translate API supports more than ninety 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.

Authenticating

Unlike other Cloud Platform services, which authenticate using a project ID and OAuth 2.0 credentials, Translate API requires a public API access key. (This may change in future releases of Translate API.) Follow the general instructions at Identifying your application to Google, and the specific instructions for Server keys.

Translating texts

Translating text from one language to another is easy (and extremely fast.) The only required arguments to Api#translate are a string and the ISO 639-1 code of the language to which you wish to translate.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new

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!"

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.)

require "google/cloud/translate"

translate = Google::Cloud::Translate.new

translation = translate.translate "chat", to: "en"

translation.detected? #=> true
translation.from #=> "en"
translation.text #=> "chat"

translation = translate.translate "chat", from: "fr", to: "en"

translation.detected? #=> false
translation.from #=> "fr"
translation.text #=> "cat"

You can pass multiple texts to Api#translate.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new

translations = translate.translate "chien", "chat", from: "fr", to: "en"

translations.size #=> 2
translations[0].origin #=> "chien"
translations[0].text #=> "dog"
translations[1].origin #=> "chat"
translations[1].text #=> "cat"

By default, any HTML in your source text will be preserved.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new

translation = translate.translate "<strong>Hello</strong> world!",
                                  to: :la
translation.text #=> "<strong>Salve</strong> mundi!"

Detecting languages

You can use 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.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new

detection = translate.detect "chat"

detection.text #=> "chat"
detection.language #=> "en"
detection.confidence #=> 0.59922177

You can pass multiple texts to Api#detect.

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

Listing supported languages

Translate API adds new languages frequently. You can use Api#languages to query the list of supported languages.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new

languages = translate.languages

languages.size #=> 104
languages[0].code #=> "af"
languages[0].name #=> nil

To receive the names of the supported languages, as well as their ISO 639-1 codes, provide the code for the language in which you wish to receive the names.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new

languages = translate.languages "en"

languages.size #=> 104
languages[0].code #=> "af"
languages[0].name #=> "Afrikaans"

Configuring retries and timeout

You can configure how many times API requests may be automatically retried. When an API request fails, the response will be inspected to see if the request meets criteria indicating that it may succeed on retry, such as 500 and 503 status codes or a specific internal error code such as rateLimitExceeded. If it meets the criteria, the request will be retried after a delay. If another error occurs, the delay will be increased before a subsequent attempt, until the retries limit is reached.

You can also set the request timeout value in seconds.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new retries: 10, timeout: 120

Defined Under Namespace

Classes: Api, Detection, Language, Translation

Constant Summary collapse

VERSION =

"0.21.0"

Class Method Summary collapse

.new(key: nil, retries: nil, timeout: nil) ⇒ Google::Cloud::Translate::Api
Creates a new object for connecting to the Translate service.

Class Method Details

.new(key: nil, retries: nil, timeout: nil) ⇒ `Google::Cloud::Translate::Api`

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, and the specific instructions for Server keys.

Examples:

require "google/cloud/translate"

translate = Google::Cloud::Translate.new key: "api-key-abc123XYZ789"

translation = translate.translate "Hello world!", to: "la"
translation.text #=> "Salve mundi!"

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!"

Parameters:

key (String) —
a public API access key (not an OAuth 2.0 token)
retries (Integer) —
Number of times to retry requests on server error. The default value is 3. Optional.
timeout (Integer) —
Default timeout to use in requests. Optional.

Returns:

(Google::Cloud::Translate::Api)

# File 'lib/google/cloud/translate.rb', line 247

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