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.

Go to the Adaptive Translation page
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:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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_NUMBER_OR_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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_NUMBER_OR_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/adaptiveMtDatasets" | Select-Object -Expand Content

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)

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:

curl (Linux, macOS, or Cloud Shell)

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_NUMBER_OR_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION/adaptiveMtDatasets/DATASET_ID:importAdaptiveMtFile"

PowerShell (Windows)

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_NUMBER_OR_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/adaptiveMtDatasets/DATASET_ID:importAdaptiveMtFile" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "adaptiveMtFile": {
    "name": "DATASET_NAME",
    "displayName": "FILE_NAME",
    "entryCount": TOTAL_ENTRIES
  }
}

Java

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

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

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)

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:

curl (Linux, macOS, or Cloud Shell)

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_NUMBER_OR_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION:adaptiveMtTranslate"

PowerShell (Windows)

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_NUMBER_OR_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:adaptiveMtTranslate" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "translations": [
    {
      "translatedText": "TRANSLATED_TEXT"
    }
  ],
  "languageCode": "TARGET_LANGUAGE"
}

Java

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

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

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)

What's next

Manage datasets (API only)