The AI.TRANSLATE function

This document describes the AI.TRANSLATE function, which translates text strings between languages. AI.TRANSLATE brings high-quality Translation LLM (TLLM) capabilities to your SQL workflows, while also supporting standard Neural Machine Translation (NMT) workloads.

The AI.TRANSLATE function uses your end-user credentials by default for standard translation tasks, reducing the need for additional set up steps and authentication.

Syntax

AI.TRANSLATE(
  content,
  target_language
  [, source_language => source_language]
  [, model => model_name]
  [, return_details => return_details]
)

Arguments

The AI.TRANSLATE function takes the following arguments:

  • content: a STRING value that represents the text to translate. This can be a string literal, column name, or string expression.
  • target_language: a STRING value that specifies a supported language code to translate the text to.
  • source_language: a STRING value that specifies the language code of the original content. If omitted, the underlying API uses automatic language detection.
  • model_name: a STRING value that indicates the backend translation engine. To use the TLLM model, set the value to translation-llm. If omitted, the value defaults to nmt.
  • return_details: a BOOL value. If set to TRUE, the function returns a STRUCT with additional details about the translation process, including the translated text, the full response from the Translation API, and any error messages. If omitted, the value defaults to FALSE, and only the translated text is returned.

Output

If return_details is set to FALSE, the function returns a STRING value that contains the translated text.

If return_details is set to TRUE, the AI.TRANSLATE function returns a STRUCT with the following fields:

  • result: a STRING value that contains the successfully translated text. If an error occurs, then this value is empty.
  • status: a STRING value that contains the top-level execution status. If the operation is successful, the string contains "OK". If there is an error, the string contains the API error message or HTTP code.
  • details: a JSON type that contains the full RPC response payload from the Translation API.

Examples

The following examples demonstrate how to use the AI.TRANSLATE function.

Translate with the default model

The following example translates text from an unspecified language to French using the default TLLM model:

SELECT AI.TRANSLATE('Hello, how are you?', 'fr');

The output is similar to the following:

"Bonjour, comment allez-vous ?"

Specify a source language

The following example specifies that the original text is in English:

SELECT AI.TRANSLATE(
  'Hello, how are you?',
  'fr',
  source_language => 'en'
);

The output is similar to the following:

"Bonjour, comment allez-vous ?"

Use a different model

The following example uses the TLLM model to translate the text:

SELECT AI.TRANSLATE(
  'Hello, how are you?',
  'fr',
  model => 'translation-llm'
);

The output is similar to the following:

"Bonjour comment allez-vous ?"

Return translation details

The following example sets return_details to TRUE to retrieve additional details about the translation process:

SELECT AI.TRANSLATE(
    'Hello, how are you?',
    'fr',
    return_details => TRUE
  );

The output is similar to the following:

{"result":"Bonjour, comment allez-vous ?","status":"","details":"..."}

What's next