1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
|
# Google Cloud Translation API
[Google Cloud Translation API](https://cloud.google.com/translation/)
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
{file:AUTHENTICATION.md Authentication Guide}.
## Translating texts
Translating text from one language to another is easy (and extremely
fast.) The only required arguments to
{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/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.)
```ruby
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 {Google::Cloud::Translate::Api#translate}.
```ruby
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.
```ruby
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 {Google::Cloud::Translate::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`.
```ruby
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 {Google::Cloud::Translate::Api#detect}.
```ruby
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
{Google::Cloud::Translate::Api#languages} to query the list of supported
languages.
```ruby
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](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/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.
```ruby
require "google/cloud/translate"
translate = Google::Cloud::Translate.new retries: 10, timeout: 120
```
|