Request 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.
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
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 only translate plain text.
- You can translate to only one target language at a time.
For information about adaptive translation quotas and limits, see the Quotas page.
Request translations
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
When using the API, you first create a dataset, import data into the dataset, and then request adaptive translations with your dataset. The dataset persists in your project until you delete it, meaning other users in your project can use it for adaptive translations.
Create a dataset
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" }
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
/** 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);
}
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 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)
}
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 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)
Import data
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 } }
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
/** 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();
}
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 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)
}
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 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)
Translate text
Provide the text to translate and the dataset that Cloud Translation uses
for the translation. Cloud Translation uses the source and target
language from the dataset to determine which languages to use for your
translation. For example, use an en
to es
dataset to
translate text from English to Spanish. For more information, see the
adaptiveMtTranslate method.
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.
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.
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"] }
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 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);
}
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}`,
dataset: `projects/${projectId}/locations/${location}/adaptiveMtDatasets/${
adaptiveMtDatasetName}`,
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",
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)
What's next
- Manage datasets (API only)