Skip to content

Latest commit

 

History

History
390 lines (282 loc) · 12 KB

OVERVIEW.md

File metadata and controls

390 lines (282 loc) · 12 KB
Raw

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.

The google-cloud-translate 2.0 gem contains a generated v3 client and a legacy hand-written v2 client. To use the legacy v2 client, call {Google::Cloud::Translate.new} and specify version: :v2. See Migrating to Translation v3 for details regarding differences between v2 and v3.

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 {file:AUTHENTICATION.md Authentication Guide}.

Using the v3 client

The Cloud Translation API v3 includes several new features and updates:

  • Glossaries - Create a custom dictionary to correctly and consistently translate terms that are customer-specific.
  • Batch requests - Make an asynchronous request to translate large amounts of text.
  • AutoML models - Cloud Translation adds support for translating text with custom models that you create using AutoML Translation.
  • Labels - The Cloud Translation API supports adding user-defined labels (key-value pairs) to requests.

Translating texts

Cloud Translation v3 introduces support for translating text using custom AutoML Translation models, and for creating glossaries to ensure that the Cloud Translation API translates a customer's domain-specific terminology correctly.

Performing a default translation:

require "google/cloud/translate"

client = Google::Cloud::Translate.new

project_id = "my-project-id"
location_id = "us-central1"

# The content to translate in string format
contents = ["Hello, world!"]
# Required. The BCP-47 language code to use for translation.
target_language = "fr"
parent = client.class.location_path project_id, location_id

response = client.translate_text contents, target_language, parent

# Display the translation for each input text provided
response.translations.each do |translation|
  puts "Translated text: #{translation.translated_text}"
end

To use AutoML custom models you enable the AutoML API for your project before translating as follows:

require "google/cloud/translate"

client = Google::Cloud::Translate.new

project_id = "my-project-id"
location_id = "us-central1"
model_id = "my-automl-model-id"

# The `model` type requested for this translation.
model = "projects/#{project_id}/locations/#{location_id}/models/#{model_id}"
# The content to translate in string format
contents = ["Hello, world!"]
# Required. The BCP-47 language code to use for translation.
target_language = "fr"
# Optional. The BCP-47 language code of the input text.
source_language = "en"
# Optional. Can be "text/plain" or "text/html".
mime_type = "text/plain"
parent = client.class.location_path project_id, location_id

response = client.translate_text contents, target_language, parent,
  source_language_code: source_language, model: model, mime_type: mime_type

# Display the translation for each input text provided
response.translations.each do |translation|
  puts "Translated text: #{translation.translated_text}"
end

To use a glossary you need to create a Google Cloud Storage bucket and grant your service account access to it before translating as follows:

require "google/cloud/translate"

client = Google::Cloud::Translate.new

project_id = "my-project-id"
location_id = "us-central1"
glossary_id = "my-glossary-id"

# The content to translate in string format
contents = ["Hello, world!"]
# Required. The BCP-47 language code to use for translation.
target_language = "fr"
# Optional. The BCP-47 language code of the input text.
source_language = "en"
glossary_config = {
  # Specifies the glossary used for this translation.
  glossary: client.class.glossary_path(project_id, location_id, glossary_id)
}
# Optional. Can be "text/plain" or "text/html".
mime_type = "text/plain"
parent = client.class.location_path project_id, location_id

response = client.translate_text contents, target_language, parent,
  source_language_code: source_language, glossary_config: glossary_config, mime_type: mime_type

# Display the translation for each input text provided
response.translations.each do |translation|
  puts "Translated text: #{translation.translated_text}"
end

Batch translating texts

Batch translation allows you to translate large amounts of text (with a limit of 1,000 files per batch), and to up to 10 different target languages. Batch translation also supports AutoML models and glossaries. To make batch requests you need to create a Google Cloud Storage bucket and grant your service account access to it before translating as follows:

require "google/cloud/translate"

client = Google::Cloud::Translate.new

input_uri = "gs://cloud-samples-data/text.txt"
output_uri = "gs://my-bucket-id/path_to_store_results/"
project_id = "my-project-id"
location_id = "us-central1"
source_lang = "en"
target_lang = "ja"

input_config = {
  gcs_source: {
    input_uri: input_uri
  },
  # Optional. Can be "text/plain" or "text/html".
  mime_type: "text/plain"
}
output_config = {
  gcs_destination: {
    output_uri_prefix: output_uri
  }
}
parent = client.class.location_path project_id, location_id

operation = client.batch_translate_text \
  parent, source_lang, [target_lang], [input_config], output_config

# Wait until the long running operation is done
operation.wait_until_done!

response = operation.response

puts "Total Characters: #{response.total_characters}"
puts "Translated Characters: #{response.translated_characters}"

Detecting languages

You can detect the language of a text string:

require "google/cloud/translate"

client = Google::Cloud::Translate.new

project_id = "my-project-id"
location_id = "us-central1"
# The text string for performing language detection
content = "Hello, world!"
# Optional. Can be "text/plain" or "text/html".
mime_type = "text/plain"

parent = client.class.location_path project_id, location_id

response = client.detect_language parent, content: content, mime_type: mime_type

# Display list of detected languages sorted by detection confidence.
# The most probable language is first.
response.languages.each do |language|
  # The language detected
  puts "Language Code: #{language.language_code}"
  # Confidence of detection result for this language
  puts "Confidence: #{language.confidence}"
end

Listing supported languages

You can discover the supported languages of the v3 API:

require "google/cloud/translate"

client = Google::Cloud::Translate.new

project_id = "my-project-id"
location_id = "us-central1"

parent = client.class.location_path project_id, location_id

response = client.get_supported_languages parent

# List language codes of supported languages
response.languages.each do |language|
  puts "Language Code: #{language.language_code}"
end

Using the legacy v2 client

Translating texts

Translating text from one language to another is easy (and extremely fast.) The only required arguments to {Google::Cloud::Translate::V2::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 version: :v2

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 version: :v2

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 {Google::Cloud::Translate::V2::Api#translate}.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new version: :v2

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 version: :v2

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

Detecting languages

You can use {Google::Cloud::Translate::V2::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 version: :v2

detection = translate.detect "chat"

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

You can pass multiple texts to {Google::Cloud::Translate::V2::Api#detect}.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new version: :v2

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 {Google::Cloud::Translate::V2::Api#languages} to query the list of supported languages.

require "google/cloud/translate"

translate = Google::Cloud::Translate.new version: :v2

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 version: :v2

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 version: :v2, retries: 10, timeout: 120