Translate text by using adaptive translation
When you request an adaptive translation, you provide the text to translate and example translations that Cloud Translation uses to tailor its responses.
For programmatic translation requests, you can include example translations in a dataset or as part of your translation request. When you use a dataset, Cloud Translation automatically selects five reference sentences that are most similar to your source sentence to customize translations. If you include reference sentences in your translation request, Cloud Translation uses all of them to customize the translation.
Before you begin
To use adaptive translation, you must enable the Cloud Translation API in your project and set up authentication. For more information, see the Cloud Translation Setup.
Also, check that your source and target languages are supported by adaptive translation.
Data requirements and suggestions
If you create a dataset or use the Google Cloud console, you must provide example translations in a TSV or TMX file. The examples must be sentence pairs in your intended source and target languages. We recommend that you provide examples that cover the vocabulary, usage, and grammatical quirks of your domain. For additional tips, see Data preparation in the AutoML Translation documentation.
Your data must include at least 5 sentence pairs and no more than 10,000 pairs if you use the console and no more than 30,000 pairs if you use the API. A segment pair can be at most 512 characters (total).
Limitations
- You can translate to only one target language at a time.
- Adaptive translation has limits on the number of input and output characters. For more information, see the Adaptive translation limits on the Quotas page.
Request translations
For translations, the input can be plain text or HTML. Cloud Translation 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.
Console
When using the Google Cloud console, select a file that includes your example translations and then request translations. Cloud Translation doesn't store your imported data. If you prefer to work with persistent datasets, use the API.
Go to the AutoML Translation console.
Select a local file or a file in Cloud Storage that contains your example translations.
After you select a file, Cloud Translation sets the Source language and Target language fields based on your data. For example, if you import an English to Portuguese dataset, the console lets you translate only English sentences to Portuguese.
Enter text in the source language field.
Adaptive translation does have limits on the number of input and output characters. For more information, see the Adaptive translation limits on the Quotas page.
To adjust parameters, use the sliders or text fields to set values:
- Temperature - Controls the degree of randomness in token selection. For lower temperatures, expect a true or correct response. For higher temperatures, expect more diverse or unexpected results.
- Number of examples - Sets the number of examples to use from your source data to prompt the LLM.
Select Compare with NMT model to include translations from the default Google NMT model along with the adaptive translation output.
Click Translate.
In a few moments, Cloud Translation returns a response in the target language field. Cloud Translation doesn't return any text beyond the output character limit.
API
Use the API to request adaptive translations by including reference sentence pairs or by specifying a dataset.
Adaptive translations with reference sentence pairs
To include example translations as part of your translation requests, include
your example source and target sentence pairs in the referenceSentencePairs
field, which is part of the referenceSentenceConfig
object. For more
information, see the adaptiveMtTranslate method.
You can include up to five sentence pairs.
REST
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: The region where your translation request is handled,
such as
us-central1
. - REFERENCE_SOURCE: A sentence in the source language that is part of a reference sentence pair.
- REFERENCE_TARGET: A sentence in the target language that is part of a reference sentence pair.
- SOURCE_LANGUAGE: The language code of the source text.
- TARGET_LANGUAGE: The language code of the language to translate the source text to.
- SOURCE_TEXT: The text to translate.
- MIME_TYPE (Optional): The format of the source text, such as
text/html
ortext/plain
. By default, the MIME type is set totext/plain
.
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION:adaptiveMtTranslate
Request JSON body:
{ "referenceSentenceConfig": { "referenceSentencePairLists": [ { "referenceSentencePairs": [{ "sourceSentence": REFERENCE_SOURCE_1_1, "targetSentence": REFERENCE_TARGET_1_1 }, { "sourceSentence": REFERENCE_SOURCE_1_2, "targetSentence": REFERENCE_SOURCE_1_2 }] } ], "sourceLanguageCode": SOURCE_LANGUAGE, "targetLanguageCode": TARGET_LANGUAGE } "content": ["SOURCE_TEXT"], "mimeType": "MIME_TYPE" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "translations": [ { "translatedText": "TRANSLATED_TEXT" } ], "languageCode": "TARGET_LANGUAGE" }
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.
Java
/** Translates using AdaptiveMt. */
private static void adaptiveMtTranslate(
TranslationServiceClient translationServiceClient, String projectId, String sourceLang, String targetLang, Pair<String, String> referencePairs) {
ReferenceSentencePairList refList = ReferenceSentencePairList.newBuilder();
for (Pair<String, String> referencePair: referencePairs) {
ReferenceSentencePair refPair = ReferenceSentencePair.newBuilder()
.setSourceSentence(referencePair.getKey())
.setTargetSentence(referencePair.getValue());
refList.addReferenceSentencePair(refPair);
}
AdaptiveMtTranslateRequest request =
AdaptiveMtTranslateRequest.newBuilder()
.setParent(LocationName.of(projectId, "us-central1").toString())
.setSourceLanguageCode(sourceLang)
.setTargetLanguageCOde(targetLang)
.addReferenceSentencePairLists(refList)
.build();
AdaptiveMtTranslateResponse response = translationServiceClient.adaptiveMtTranslate(request);
System.out.println("Translating using AdaptiveMt");
System.out.println(response);
}
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.
Node.js
async function translate() {
const request = {
parent: `projects/${projectId}/locations/${location}`,
referenceSentenceConfig: {
referenceSentencePairLists: [
{
referenceSentencePairs: [{
sourceSentence: 'Sample reference source 1'
targetSentence: 'Sample reference target 1'
},
{
sourceSentence: 'Sample reference source 2'
targetSentence: 'Sample reference target 2'
}]
}
],
sourceLanguageCode: 'en'
targetLanguageCode: 'ja'
},
content: ['Sample translate query']
} const [response] = await translationClient.adaptiveMtTranslate(request)
console.log('Translating')
console.log(response)
}
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.
Python
def adaptive_mt_translate():
# Create a client
client = translate.TranslationServiceClient()
# Initialize the request
request = translate.AdaptiveMtTranslateRequest(
parent="projects/PROJECT_ID/locations/LOCATION",
reference_sentence_config=[
"reference_sentence_pair_lists": [
"reference_sentence_pairs": {
"source_sentence": 'REFERENCE_SOURCE_1_1'
"target_sentence": 'REFERENCE_TARGET_1_1'
},
"reference_sentence_pairs": {
"source_sentence": 'REFERENCE_SOURCE_1_2'
"target_sentence": 'REFERENCE_TARGET_1_2'
}
],
"source_language_code": 'SOURCE_LANGUAGE'
"target_language_code": 'TARGET_LANGUAGE'
],
content=["SOURCE_TEXT"]
)
# Make the request
response = client.adaptive_mt_translate(request)
# Handle the response
print(response)
Adaptive translations with a dataset
To use a dataset with translations, create a dataset and import sentence pairs first. If you already have a dataset, you can request adaptive translations with it. The dataset persists in your project until you delete it.
Create a dataset where you import your example translations.
The source and target languages must match the languages that you intend to use in your translations. For more information, see the adaptiveMtDataset.create method.
REST
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: The region where your source dataset is located, such
as
us-central1
. - DATASET_ID: A unique identifier for your dataset.
- DISPLAY_NAME: A descriptive name for your dataset.
- SOURCE_LANGUAGE: The language code of the input text. For supported language codes, see Supported languages.
- TARGET_LANGUAGE: The target language to translate the input text to. For supported language codes, see Supported languages.
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets
Request JSON body:
{ "name": "projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID, "display_name": "DISPLAY_NAME", "source_language_code": "SOURCE_LANGUAGE", "target_language_code": "TARGET_LANGUAGE" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID", "displayName": "DISPLAY_NAME", "sourceLanguageCode": "SOURCE_LANGUAGE", "targetLanguageCode": "TARGET_LANGUAGE" }
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.
/** Creates an AdaptiveMtDataset. */ private static void createAdaptiveMtDataset( TranslationServiceClient translationServiceClient, String projectName, String datasetName) { String adaptiveMtDatasetName = String.format( "projects/%s/locations/LOCATION/adaptiveMtDatasets/%s", projectName, datasetName); AdaptiveMtDataset adaptiveMtDataset = AdaptiveMtDataset.newBuilder() .setName(adaptiveMtDatasetName) .setDisplayName("DATASET_DISPLAY_NAME") .setSourceLanguageCode("SOURCE_LANGUAGE_CODE") .setTargetLanguageCode("TARGET_LANGUAGE_CODE") .build(); CreateAdaptiveMtDatasetRequest request = CreateAdaptiveMtDatasetRequest.newBuilder() .setParent(LocationName.of("PROJECT_NAME", "LOCATION").toString()) .setAdaptiveMtDataset(adaptiveMtDataset) .build(); AdaptiveMtDataset dataset = translationServiceClient.createAdaptiveMtDataset(request); System.out.println("Created dataset"); System.out.println(dataset); }
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.
async function createAdaptiveMtDataset() { // Construct request const request = { parent: `projects/${projectId}/locations/${location}`, adaptiveMtDataset: { name: `projects/${projectId}/locations/${location}/adaptiveMtDatasets/${ adaptiveMtDatasetName}`, displayName: 'DATASET_DISPLAY_NAME', sourceLanguageCode: 'SOURCE_LANGUAGE_CODE', targetLanguageCode: 'TARGET_LANGUAGE_CODE', } }; // Run request const [response] = await translationClient.createAdaptiveMtDataset(request); console.log('Created') console.log(response) }
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.
def create_adaptive_mt_dataset(): # Create a client client = translate.TranslationServiceClient() # Initialize request argument(s) adaptive_mt_dataset = translate.AdaptiveMtDataset() adaptive_mt_dataset.name = "projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID" adaptive_mt_dataset.display_name = "DATASET_DISPLAY_NAME" adaptive_mt_dataset.source_language_code = "SOURCE_LANGUAGE_CODE" adaptive_mt_dataset.target_language_code = "TARGET_LANGUAGE_CODE" request = translate.CreateAdaptiveMtDatasetRequest( parent="projects/PROJECT_ID/locations/LOCATION", adaptive_mt_dataset=adaptive_mt_dataset, ) # Make the request response = client.create_adaptive_mt_dataset(request=request) # Handle the response print(response)
After you create a dataset, populate it with example translations from a TSV or TMX file.
You can import data from multiple files into a single dataset. For more information, see the adaptiveMtDatasets.importAdaptiveMtFile method.
REST
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: The region where your dataset is located, such as
us-central1
. - DATASET_ID: The unique identifier of your dataset where the data is to be imported.
- GCS_FILE_PATH: The path to the source data file in
Cloud Storage, such as
gs://example/data.tsv
.
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID:importAdaptiveMtFile
Request JSON body:
{ "gcs_input_source": { "input_uri": "GCS_FILE_PATH" } }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "adaptiveMtFile": { "name": "DATASET_NAME", "displayName": "FILE_NAME", "entryCount": TOTAL_ENTRIES } }
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.
/** Imports an AdaptiveMtFile. */ private static String importAdaptiveMtFile( TranslationServiceClient translationServiceClient, String projectId, String datasetId, String gcsUri) { String adaptiveMtDatasetName = String.format( "projects/%s/locations/LOCATION/adaptiveMtDatasets/%s", projectId, datasetId); ImportAdaptiveMtFileRequest importAdaptiveMtFileRequest = ImportAdaptiveMtFileRequest.newBuilder() .setParent(adaptiveMtDatasetName) .setGcsInputSource(GcsInputSource.newBuilder().setInputUri(gcsUri).build()) .build(); ImportAdaptiveMtFileResponse response = translationServiceClient.importAdaptiveMtFile(importAdaptiveMtFileRequest); System.out.println("Importing file"); System.out.println(response); return response.getAdaptiveMtFile().getName(); }
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.
async function importAdaptiveMtFile() { const request = { parent: `projects/${projectId}/locations/${location}/adaptiveMtDatasets/${ adaptiveMtDatasetName}`, gcsInputSource: {inputUri: gcs_file_uri} } const [response] = await translationClient.importAdaptiveMtFile(request) console.log('Importing file') console.log(response) }
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.
def import_adaptive_mt_file(): # Create a client client = translate.TranslationServiceClient() gcs_input_source = translate.GcsInputSource() gcs_input_source.input_uri = "gs://SOURCE_LOCATION/FILE.tsv" # Initialize the request request = translate.ImportAdaptiveMtFileRequest( parent="projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID", gcs_input_source=gcs_input_source ) # Make the request response = client.import_adaptive_mt_file(request) # Handle the response print(response)
Request an adaptive translation by providing the source text to translate and the dataset that Cloud Translation uses to customize the translation.
Cloud Translation uses the source and target language from the dataset to determine which languages to use for your translation. For example, an
en
toes
dataset translates text from English to Spanish. For more information, see the adaptiveMtTranslate method.REST
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: The region where your source dataset is located, such
as
us-central1
. - DATASET_NAME: The name of the dataset that
Cloud Translation uses to customize your translations, formatted as
projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID
. You can get dataset names by listing all datasets in your project. - SOURCE_TEXT: The text to translate.
- MIME_TYPE (Optional): The format of the source text, such as
text/html
ortext/plain
. By default, the MIME type is set totext/plain
.
HTTP method and URL:
POST https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION:adaptiveMtTranslate
Request JSON body:
{ "dataset": "DATASET_NAME", "content": ["SOURCE_TEXT"], "mimeType": "MIME_TYPE" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "translations": [ { "translatedText": "TRANSLATED_TEXT" } ], "languageCode": "TARGET_LANGUAGE" }
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.
/** Translates using AdaptiveMt. */ private static void adaptiveMtTranslate( TranslationServiceClient translationServiceClient, String projectId, String datasetId) { String adaptiveMtDatasetName = String.format( "projects/%s/locations/LOCATION/adaptiveMtDatasets/%s", projectId, datasetId); AdaptiveMtTranslateRequest request = AdaptiveMtTranslateRequest.newBuilder() .setParent(LocationName.of(projectId, "us-central1").toString()) .setDataset(adaptiveMtDatasetName) .addContent("Sample translation text") .build(); AdaptiveMtTranslateResponse response = translationServiceClient.adaptiveMtTranslate(request); System.out.println("Translating using AdaptiveMt"); System.out.println(response); }
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.
async function translate() { const request = { parent: `projects/${projectId}/locations/${location}`, dataset: `projects/${projectId}/locations/${location}/adaptiveMtDatasets/${ adaptiveMtDatasetName}`, content: ['Sample translate query'] } const [response] = await translationClient.adaptiveMtTranslate(request) console.log('Translating') console.log(response) }
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.
def adaptive_mt_translate(): # Create a client client = translate.TranslationServiceClient() # Initialize the request request = translate.AdaptiveMtTranslateRequest( parent="projects/PROJECT_ID/locations/LOCATION", dataset="projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID", content=["Sample translation request"] ) # Make the request response = client.adaptive_mt_translate(request) # Handle the response print(response)