Cloud Translation - Advanced supports 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.
If you want to use AutoML custom models for your project, you must enable the AutoML API (automl.googleapis.com). For instructions on installing the Cloud SDK, setting up a project with a service account, and obtaining an access token, see the Setup page. If you plan to use a glossary or the batch features, you also need to create a Cloud Storage bucket and grant your service account access to it.
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.
Comparing models
When you request translation from Cloud Translation - Advanced, you can specify which
translation model to use. If no model is specified the nmt
model is used if the
language pair is supported, otherwise the PBMT model is used.
Model | Best fit | Examples |
---|---|---|
Neural Machine Translation (NMT) model |
General text use cases such as common website content that is not specific to a domain, for example. news articles. |
News articles, Social media, Chat applications, Reviews |
Phrase-Based Machine Translation (PBMT) model | NMT generally results in better quality translations. PBMT might be used by default if the NMT model doesn't exist for a language pair. | Use when NMT is not available. |
AutoML Translation model | Domain specific text. Customers provide training data specific to their use cases, for given language pairs to customize Google's base model for the domain purpose. | Financial News, technical documents, any text that uses terms and jargon unique to that field. |
You specify the translation model using its model ID. For the general Google
models, the model IDs are general/nmt
for the NMT model and general/base
for
the PBMT model. See the next section for information about AutoML Translation model IDs.
Translating text
The input text can be plain text or HTML. Cloud Translation API 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.
Translating input strings
REST & CMD LINE
To translate text, make a POST
request and provide JSON in the request body
that identifies the language to translate from (source_language_code
), the
language to translate to (target_language_code
), and the text to translate
(contents
). You can provide multiple strings of text to translate by including
them in your JSON (see example). You identify your source and 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.
Before using any of the request data below, make the following replacements:
- project-number-or-id: your Google Cloud project number or ID
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/project-number-or-id:translateText
Request JSON body:
{ "sourceLanguageCode": "en", "targetLanguageCode": "ru", "contents": ["Dr. Watson, come here!", "Bring me some coffee!"] }
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/v3/projects/project-number-or-id:translateText
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/v3/projects/project-number-or-id:translateText " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "translations": [ { "translatedText": "Доктор Ватсон, иди сюда!", }, { "translatedText": "Принеси мне кофе!", } ] }
The translations
array contains two translatedText
fields with translations
provided in the requested targetLanguageCode
language (ru
: Russian). The translations are listed in the same order as the
corresponding source array in the request.
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.
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.
Translating text using an AutoML Translation custom model
REST & CMD LINE
This example translates text using an AutoML Translation model whose model ID is
TRL1395675701985363739
. You can get the model ID for an AutoML Translation model
from the list of models in the AutoML Translation UI or from the API response when you
train the model.
Before using any of the request data below, make the following replacements:
- project-number-or-id: your Google Cloud project number or ID
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/project-number-or-id/locations/us-central1:translateText
Request JSON body:
{ "model": "projects/project-number-or-id/locations/us-central1/models/TRL1395675701985363739", "sourceLanguageCode": "en", "targetLanguageCode": "ru", "contents": ["Dr. Watson, please discard your trash. You've shared unsolicited email with me. Let's talk about spam and importance ranking in a confidential mode."] }
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/v3/projects/project-number-or-id/locations/us-central1:translateText
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/v3/projects/project-number-or-id/locations/us-central1:translateText " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "translation": { "translatedText": "Доктор Ватсон, пожалуйста, откажитесь от своего мусора. Вы поделились нежелательной электронной почтой со мной. Давайте поговорим о спаме и важности рейтинга в конфиденциальном режиме.", "model": "projects/project-number/locations/us-central1/models/TRL1395675701985363739" } }
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.
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.
Using the model parameter
REST & CMD LINE
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, with the example showing the selection of base
.
Before using any of the request data below, make the following replacements:
- project-number-or-id: your Google Cloud project number or ID
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/project-number-or-id/locations/global:translateText
Request JSON body:
{ "model": "projects/project-number-or-id/locations/global/models/general/base", "sourceLanguageCode": "en", "targetLanguageCode": "de", "contents": ["Come here!"] }
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/v3/projects/project-number-or-id/locations/global:translateText
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/v3/projects/project-number-or-id/locations/global:translateText " | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "translations": [ { "translatedText": "Komm her!", "model": "projects/project-number/locations/global/models/general/base" } ] }