This document describes how to use the Cloud Translation - Basic (v2) to translate text.
The input text can be plain text or HTML. Cloud Translation - Basic does not translate any HTML tags in the input, only text that appears between the tags. The output retains the (untranslated) HTML tags, with the translated text between the tags to the extent possible due to differences between the source and target languages. The order of HTML tags in the output may differ from the order in the input text due to word order changes in the translation.
Before you begin
Before you can start using the Cloud Translation API, you must have a project that has the Cloud Translation API enabled and the appropriate credentials. You can also install client libraries for common programming languages to help you make calls to the API.
For more information, see the Setup page.
Translating text
This section demonstrates a few ways to request translations from the
https://translation.googleapis.com/language/translate/v2
endpoint.
Translating input strings
REST & CMD LINE
To translate text, make aPOST
request and provide
JSON in the request body that identifies the language to translate to (target
)
and the text to translate (q
). You can provide multiple segments of text to
translate by including multiple q
fields or a list of values for the q
field. You cannot exceed 128 text segments. You specify target languages by
using their
ISO-639-1
codes.
The following shows an example of a POST
request using
curl
or PowerShell. The example uses the access token for a service account
set up for the project using the Google Cloud Cloud SDK.
For instructions on installing the Cloud SDK,
setting up a project with a service account, and obtaining an access token,
see the Setup page.
HTTP method and URL:
POST https://translation.googleapis.com/language/translate/v2
Request JSON body:
{ "q": ["Hello world", "My name is Jeff"], "target": "de" }
To send your request, choose one of these options:
curl
Save the request body in a file called request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://translation.googleapis.com/language/translate/v2
PowerShell
Save the request body in a file called request.json
,
and execute the following command:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://translation.googleapis.com/language/translate/v2 " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "data": { "translations": [ { "translatedText": "Hallo Welt", "detectedSourceLanguage": "en" }, { "translatedText": "Mein Name ist Jeff", "detectedSourceLanguage": "en" } ] } }
The translations
array contains two translatedText
fields with translations
provided in the requested target
language (de
: German). The translations are listed in the same order as the
corresponding source array in the request.
C#
Before trying this sample, follow the C# setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation C# API reference documentation.
Go
Before trying this sample, follow the Go setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation PHP API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Ruby API reference documentation.
Specifying a model
By default, when you make a translation request to the Cloud Translation API, your text is translated using the Neural Machine Translation (NMT) model. If the NMT model is not supported for the requested language translation pair, then the Phrase-Based Machine Translation (PBMT) model is used.
Comparing models
The NMT model can provide improved translation for longer and more complex content. For example, consider the following request:
{ "q": "So let us begin anew--remembering on both sides that civility is not a sign of weakness, and sincerity is always subject to proof. Let us never negotiate out of fear. But let us never fear to negotiate.", "target": "de" }
Because no model
is specified in the request, and the translation language
pair of English to German is supported by the NMT model, the request is
translated using the nmt
model. The following is returned in the
response's translations
field:
"translatedText": "Fangen wir also von neuem an - auf beiden Seiten erinnern wir uns, daß die Höflichkeit kein Zeichen der Schwäche ist und die Aufrichtigkeit immer unter Beweis gestellt wird. Lasst uns nie aus Furcht verhandeln. Aber lassen Sie uns niemals Angst haben, zu verhandeln.", "detectedSourceLanguage": "en", "model": "nmt"
Alternatively, you can specifically request that the text be translated using
the base
(PBMT) model.
{ "q": "So let us begin anew--remembering on both sides that civility is not a sign of weakness, and sincerity is always subject to proof. Let us never negotiate out of fear. But let us never fear to negotiate.", "target": "de", "model": "base", }
Using the base
model returns the following result in the response's
translations
field, which differs from the translation using the nmt
model.
"translatedText": "Lassen Sie uns also neu beginnen - auf beiden Seiten nicht vergessen, dass Zivilität ist kein Zeichen von Schwäche, und Aufrichtigkeit ist immer unter Beweis. Lassen Sie uns nie aus Angst verhandeln. Aber lassen Sie uns nie zu verhandeln fürchten.", "detectedSourceLanguage": "en", "model": "base"
Using the model parameter
You can specify which model to use for translation by using the
model
query
parameter. Specify base
to use the PBMT model, and nmt
to use the
NMT model. If you specify the NMT model in your request and the requested language
translation pair is not supported for the NMT model, then the PBMT model is used.
The following sample shows how to use the model
parameter in a translate
request.
REST & CMD LINE
To translate text using thenmt
model, include the model
parameter in
your POST
request.
HTTP method and URL:
POST https://translation.googleapis.com/language/translate/v2
Request JSON body:
{ "q":"So let us begin anew--remembering on both sides that civility is not a sign of weakness, and sincerity is always subject to proof. Let us never negotiate out of fear. But let us never fear to negotiate.", "target":"de", "model": "base" }
To send your request, choose one of these options:
curl
Save the request body in a file called request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://translation.googleapis.com/language/translate/v2
PowerShell
Save the request body in a file called request.json
,
and execute the following command:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://translation.googleapis.com/language/translate/v2 " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "data": { "translations": [ { "translatedText": "Fangen wir also von vorne an - denken wir auf beiden Seiten daran, dass Höflichkeit kein Zeichen von Schwäche ist und dass Aufrichtigkeit immer ein Beweis ist. Lasst uns niemals aus Angst verhandeln. Aber fürchten wir uns niemals vor Verhandlungen.", "detectedSourceLanguage": "en" } ] } }
C#
Before trying this sample, follow the C# setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation C# API reference documentation.
Go
Before trying this sample, follow the Go setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation PHP API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in the Translation Quickstart Using Client Libraries. For more information, see the Translation Ruby API reference documentation.