Cloud Translation - Advanced supports translating text by using custom models, and for creating glossaries to ensure that the Cloud Translation API translates a customer's domain-specific terminology correctly.
For instructions on installing the Google Cloud CLI, 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.
To translate formatted documents, such as PDFs, see Translate documents.
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 you must have 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.
Model | Model ID | Best fit | Examples |
---|---|---|---|
Neural Machine Translation (NMT) model | general/nmt |
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 |
Translation large language model (LLM) (Preview) | general/translation-llm |
Alternate model that is offered on Cloud Translation - Advanced in two modes. Text translation for general text use cases, such as conversational messages, that don't require customization. And adaptive translation, which supports customization in real time by using a dataset with examples. |
News articles, Social media, Chat applications, Reviews |
AutoML Translation model | The model ID is generated after model training completes. | Domain specific text. Customers provide training data specific to their use cases, for given language pairs to customize Google's NMT model for the domain purpose. | Financial News, technical documents, any text that uses terms and jargon unique to that field. |
Consideration
Each model supports its own set languages. Check that your source and target languages are supported. For more information, see Supported languages.
Translating text
For translations, the input can be plain text or HTML. Cloud Translation API doesn't 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.
Translating input strings
REST
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
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
Google Cloud CLI.
For instructions on installing the Google Cloud CLI,
setting up a project with a service account, and obtaining an access token,
see the Setup page.
Before using any of the request data, make the following replacements:
- PROJECT_NUMBER_OR_ID: the numeric or alphanumeric ID of your Google Cloud project
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, expand one of these options:
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 Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Go API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Before trying this sample, follow the Java setup instructions in the Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Java API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Node.js API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Before trying this sample, follow the Python setup instructions in the Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Python API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Additional languages
C#: Please follow the C# setup instructions on the client libraries page and then visit the Cloud Translation reference documentation for .NET.
PHP: Please follow the PHP setup instructions on the client libraries page and then visit the Cloud Translation reference documentation for PHP.
Ruby: Please follow the Ruby setup instructions on the client libraries page and then visit the Cloud Translation reference documentation for Ruby.
Translating text using a specific model
REST
You can specify which model to use for translation by using the
model
query parameter.
The following example translates text by using a custom model with a model ID of
1395675701985363739
. You can get the model ID for a custom model from the list
of models in the Google Cloud console or from the API response when you train
the model. To use the translation LLM, specify general/translation-llm
as the
model ID.
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION: The region where the custom model is located, such as
us-central1
.
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION:translateText
Request JSON body:
{ "model": "projects/PROJECT_ID/locations/LOCATION/models/1395675701985363739", "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 named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION:translateText"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION:translateText" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "translation": { "translatedText": "Доктор Ватсон, пожалуйста, откажитесь от своего мусора. Вы поделились нежелательной электронной почтой со мной. Давайте поговорим о спаме и важности рейтинга в конфиденциальном режиме.", "model": "projects/PROJECT_NUMBER/locations/LOCATION/models/1395675701985363739" } }
Go
Before trying this sample, follow the Go setup instructions in the Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Go API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Before trying this sample, follow the Java setup instructions in the Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Java API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Node.js API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Before trying this sample, follow the Python setup instructions in the Cloud Translation quickstart using client libraries. For more information, see the Cloud Translation Python API reference documentation.
To authenticate to Cloud Translation, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Additional languages
C#: Please follow the C# setup instructions on the client libraries page and then visit the Cloud Translation reference documentation for .NET.
PHP: Please follow the PHP setup instructions on the client libraries page and then visit the Cloud Translation reference documentation for PHP.
Ruby: Please follow the Ruby setup instructions on the client libraries page and then visit the Cloud Translation reference documentation for Ruby.
Transliteration
Transliteration is a configuration setting in the translateText
method. When
you enable transliteration, you translate romanized text (Latin script) directly
to a target language. For example, you can translate romanized Japanese text
directly to English, Spanish, or Chinese. The resulting translations are in the
target language's writing system.
In your transliteration requests, include only romanized text. If you mix romanized text with non-romanized text, Cloud Translation can't ensure consistent and proper translations.
Considerations
Transliteration differs from standard text translations in the following ways:
- Transliteration supports a limited number of languages. For more information, see the Transliteration column on the Supported languages page.
- The MIME type must be
text/plain
. HTML is not supported. - Transliteration is supported by the default standard model only. Custom models aren't supported.
- Transliteration has a lower default content quota. For more information, see Quotas and limits.
REST
Set the transliteration_config
field on the
translateText
method.
Before using any of the request data, make the following replacements:
- PROJECT_NUMBER_OR_ID: The numeric or alphanumeric ID of your Google Cloud project.
- LOCATION: Region where you want to run this operation. For
example,
us-central1
. - SOURCE_LANGUAGE: (Optional) The language code of the input text. If known, set to one of the language codes listed in Language support.
- TARGET_LANGUAGE: The target language to translate the input text to. Set to one of the language codes listed in Language support.
- SOURCE_TEXT: Romanized text in the source language to translate.
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID/locations/LOCATION:translateText
Request JSON body:
{ "source_language_code": "SOURCE_LANGUAGE", "target_language_code": "TARGET_LANGUAGE", "contents": "SOURCE_TEXT", "mime_type": "text/plain", "transliteration_config": { "enable_transliteration": true} }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "translations": [ { "translatedText": "TRANSLATED_TEXT", } ] }
Additional resources
- For help on resolving common issues or errors, see the Troubleshooting page.