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/credentials.rb,
lib/google/cloud/translate/translation.rb

Overview

Google Cloud Translation API

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

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.

Authenticating

Like other Cloud Platform services, Google Cloud Translation API supports authentication using a project ID and OAuth 2.0 credentials. In addition, it supports authentication using a public API access key. (If both the API key and the project and OAuth 2.0 credentials are provided, the API key will be used.) Instructions and configuration options are covered in the Authentication Guide.

Enabling Logging

To enable logging for this library, set the logger for the underlying gRPC library. The logger that you set may be a Ruby stdlib Logger as shown below, or a Google::Cloud::Logging::Logger that will write logs to Stackdriver Logging. See grpc/logconfig.rb and the gRPC spec_helper.rb for additional information.

Configuring a Ruby stdlib logger:

require "logger"

module MyLogger
  LOGGER = Logger.new $stderr, level: Logger::WARN
  def logger
    LOGGER
  end
end

# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
module GRPC
  extend MyLogger
end

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 Translation 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 Translation 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

Translation 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, Credentials, Detection, Language, Translation

Constant Summary collapse

VERSION = 
"1.2.1".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.translate| ... } ⇒ Google::Cloud::Config

Configure the Google Cloud Translate library.

The following Translate configuration parameters are supported:

  • project_id - (String) Identifier for a Translate project. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • retries - (Integer) Number of times to retry requests on server error.
  • timeout - (Integer) Default timeout to use in requests.

Yields:

Returns:

  • (Google::Cloud::Config) —

    The configuration object the Google::Cloud::Translate library uses.



362
363
364
365
366
 
# File 'lib/google/cloud/translate.rb', line 362

def self.configure
  yield Google::Cloud.configure.translate if block_given?

  Google::Cloud.configure.translate
end

.new(project_id: nil, credentials: nil, key: nil, scope: nil, retries: nil, timeout: nil, project: nil, keyfile: nil) ⇒ Google::Cloud::Translate::Api

Creates a new object for connecting to Cloud Translation API. Each call creates a new connection.

Like other Cloud Platform services, Google Cloud Translation API supports authentication using a project ID and OAuth 2.0 credentials. In addition, it supports authentication using a public API access key. (If both the API key and the project and OAuth 2.0 credentials are provided, the API key will be used.) Instructions and configuration options are covered in the Authentication Guide.

Examples:

require "google/cloud/translate"

translate = Google::Cloud::Translate.new(
  project_id: "my-todo-project",
  credentials: "/path/to/keyfile.json"
)

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

Using API Key.

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:

  • project_id (String) —

    Project identifier for the Cloud Translation service you are connecting to. If not present, the default project for the credentials is used.

  • credentials (String, Hash, Google::Auth::Credentials) —

    The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials)

  • key (String) —

    a public API access key (not an OAuth 2.0 token)

  • scope (String, Array<String>) —

    The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access. See Using OAuth 2.0 to Access Google APIs.

    The default scope is:

    • https://www.googleapis.com/auth/cloud-platform
  • 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.

  • project (String) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/google/cloud/translate.rb', line 311

def self.new project_id: nil, credentials: nil, key: nil, scope: nil,
             retries: nil, timeout: nil, project: nil, keyfile: nil
  project_id ||= (project || default_project_id)
  project_id = project_id.to_s # Always cast to a string

  key ||= configure.key
  if key
    return Google::Cloud::Translate::Api.new(
      Google::Cloud::Translate::Service.new(
        project_id, nil, retries: retries, timeout: timeout, key: key
      )
    )
  end

  raise ArgumentError, "project_id is missing" if project_id.empty?

  scope ||= configure.scope
  retries ||= configure.retries
  timeout ||= configure.timeout
  credentials ||= keyfile || default_credentials(scope: scope)
  unless credentials.is_a? Google::Auth::Credentials
    credentials = Translate::Credentials.new credentials, scope: scope
  end

  Translate::Api.new(
    Translate::Service.new(
      project_id, credentials, retries: retries, timeout: timeout
    )
  )
end