The Vertex AI Translation service in Google Distributed Cloud (GDC) air-gapped lets you
translate plain text and HTML between any of the
[supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt).
You can send requests to the Vertex AI Translation API by using `curl` or the
Python client library. The API also provides methods to apply custom glossaries,
detect source languages, list supported languages, and check operation status.

## Before you begin

To translate text, contact your IAM Project Admin to request the
**Vertex AI Translation Developer** (`ai-translation-developer`)
role in your project namespace.

For more information about this role, see
[Prepare IAM permissions](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-ao-permissions.md.txt).

Before you can start using the Vertex AI Translation API, you must have a
project with the Vertex AI Translation API enabled, and you must have the
appropriate credentials. You can also install client libraries to help you make
calls to the API. For more information, see
[Set up a translation project](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-set-up-translation.md.txt).

## Translate text

The `translateText` method takes input text in a particular language and returns
the translated text into another language. You can enter plain or HTML text as
input.

If you enter HTML text, the `translateText` method translates only the text
between the HTML tags without translating the tags. However, it translates
attributes in HTML5 tags, such as `alt` attributes. An example of using HTML5
tags and attributes is used in the syntax to [exclude text from translation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/quickstart-translation.md.txt#exclude-text).
The output retains the untranslated HTML tags and includes the translated text
between them.

> [!NOTE]
> **Note:** Differences can exist between the source and target languages. Because of word order changes in the translation, the order of HTML tags in the output might differ from that in the input text.

Make a `curl` request to the Vertex AI Translation pre-trained
API. Otherwise, interact with the Vertex AI Translation pre-trained API from
a Python script to translate text from one language to another.

The following examples show how to translate an input text from one language to
another:

### curl

Follow these steps to make a `curl` request:

1. [Get an authentication token](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-auth.md.txt).

2. Make the request:

```bash
curl -vv -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID:translateText -d '{"parent": "projects/PROJECT_ID", "source_language_code": "SOURCE_LANGUAGE", "target_language_code": "TARGET_LANGUAGE", "contents": ["INPUT_TEXT"]}'
```

Replace the following:

- `TOKEN`: [the authentication token](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-auth.md.txt) you obtained.
- `ENDPOINT`: the Vertex AI Translation endpoint that you use for your organization. For more information, [view service status and endpoints](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt).
- `PROJECT_ID`: your project ID.
- `SOURCE_LANGUAGE`: the language code of your input text. See the list of [supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt) and their respective language codes.
- `TARGET_LANGUAGE`: the language code you want to translate your text into. See the list of [supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt) and their respective language codes.
- `INPUT_TEXT`: your input text in the source language.

Use the `mime_type` field to specify a type of file. Set the `mime_type`
field to one of the following values:

- `text/plain`: your input is plain text.
- `text/html`: your input is HTML text.

If the `mime_type` field is empty, `text/html` is the default value.

The following example uses the `mime_type` field:

```bash
curl -vv -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID:translateText -d '{"mime_type": "text/html", "parent": "projects/PROJECT_ID", "source_language_code": "SOURCE_LANGUAGE", "target_language_code": "TARGET_LANGUAGE", "contents": ["INPUT_TEXT"]}'
```

The output returns the translated text.

### Python

Follow these steps to use the Vertex AI Translation service from a Python
script:

1. [Install the latest version of the Vertex AI Translation client library](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-install-libraries.md.txt).

2. [Set the required environment variables on a Python script](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-set-up-translation.md.txt#set-env-var).

3. [Authenticate your API request](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-auth.md.txt).

4. Add the following code to the Python script you created:

   ```python
   from google.cloud import translate
   import google.auth
   from google.auth.transport import requests
   from google.api_core.client_options import ClientOptions

   audience = "https://ENDPOINT:443"
   api_endpoint="ENDPOINT:443"

   def translate_client(creds):
     opts = ClientOptions(api_endpoint=api_endpoint)
     return translate.TranslationServiceClient(credentials=creds, client_options=opts)

   def main():
     creds = None
     try:
       creds, project_id = google.auth.default()
       creds = creds.with_gdch_audience(audience)
       req = requests.Request()
       creds.refresh(req)
     except Exception as e:
       print("Caught exception" + str(e))
       raise e
     return creds

   def translate_func(creds):
     tc = translate_client(creds)
     req = {
       "parent": "projects/PROJECT_ID",
       "source_language_code": "SOURCE_LANGUAGE",
       "target_language_code": "TARGET_LANGUAGE",
       "mime_type": "text/plain",
       "contents": ["INPUT_TEXT"]
     }

     resp = tc.translate_text(req)
     print(resp)

   if __name__=="__main__":
     creds = main()
     translate_func(creds)
   ```

   Replace the following:
   - `ENDPOINT`: the Vertex AI Translation endpoint that you use for your organization. For more information, [view service status and endpoints](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt).
   - `PROJECT_ID`: your project ID.
   - `SOURCE_LANGUAGE`: the language code of your input text. See the list of [supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt) and their respective language codes.
   - `TARGET_LANGUAGE`: the language code you want to translate your text into. See the list of [supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt) and their respective language codes.
   - `INPUT_TEXT`: your input text in the source language.

   Use the `mime_type` field to specify a type of file. Set the `mime_type`
   field to one of the following values:
   - `text/plain`: your input is plain text.
   - `text/html`: your input is HTML text.

   If the `mime_type` field is empty, `text/html` is the default value.
5. Save the Python script.

6. Run the Python script to translate the text:

   ```python
   python SCRIPT_NAME
   ```

   Replace `SCRIPT_NAME` with the name you gave to your
   Python script, such as `translation.py`.

For more information on the `translateText` method, see the [Python client library](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/vertex-ai/translation/Python/google.cloud.translate_v3.services.translation_service.TranslationServiceClient.md.txt#google_cloud_translate_v3_services_translation_service_TranslationServiceClient_translate_text).

### Exclude text from translation

Use one of the following HTML tags on the `contents` field of requests to
exclude parts of your text from translation:

- `<span translate="no">TEXT</span>`
- `<span class="notranslate">TEXT</span>`

Replace `TEXT` with the portion of text you want to exclude
from translation.

For example, if you have the following input text in Spanish:

    Hola, esto es una prueba.

The expected translated text to English is:

    Hello, this is a test.

Suppose you only want to translate the following part of the text, excluding
`Hola,` from the input text:

    esto es una prueba.

The expected translated text to English is:

    this is a test.

Use the HTML tags to exclude text from the translation. For example, the
following `curl` request uses the `<span class="notranslate">TEXT</span>`
tag to exclude `Hola,` from the previous input text in Spanish when translating
the text to English:

```bash
curl -vv -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID:translateText -d '{"parent": "projects/PROJECT_ID", "source_language_code": "es", "target_language_code": "en", "contents": ["<span class=\"notranslate\">Hola,</span> esto es una prueba."]}'
```

### Translate with glossary

To translate text with words from a glossary, you must [create a glossary](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-glossary.md.txt):

1. Save the following `request_glossary.json` file:

   ```json
   {
     "sourceLanguageCode": "SOURCE_LANGUAGE",
     "targetLanguageCode": "TARGET_LANGUAGE",
     "contents": ["TEXT"],
     "glossaryConfig": {
       "glossary": "projects/PROJECT_ID/glossaries/GLOSSARY_ID",
       "ignoreCase": IGNORE_CASE_BOOLEAN
     }
   }
   ```

   Replace the following:
   - `PROJECT_ID`: your project ID.
   - `SOURCE_LANGUAGE`: the language in which your text is written. See the list of [supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt) and their respective language codes.
   - `TARGET_LANGUAGE`: the language into which you want to translate your text. See the list of [supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt) and their respective language codes.
   - `TEXT`: translating text which includes glossary words
   - `GLOSSARY_ID`: the ID of glossary, example: `G11111111114524`
   - `IGNORE_CASE_BOOLEAN`: whether glossary term matching is case-insensitive (`true` or `false`).
2. Make the request:

   ```bash
   curl -vv -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID:translateText -d @request_glossary.json
   ```

#### Example and expected output:

Request:

```json
{
  "sourceLanguageCode": "es",
  "targetLanguageCode": "en",
  "contents": ["La novela cuenta la historia de una joven que viaja a Madrid"],
  "glossaryConfig": {
    "glossary": "projects/test-project/glossaries/GLOSSARY_ID",
    "ignoreCase": true
  }
}
```

Response:

```json
{"translations":[
  {
    "translatedText":"The novel tells the story of a young woman who travels to Madrid"}],
    "glossaryTranslations":[{"translatedText":"The novel account the story of a young woman who travels to Madrid",
    "glossaryConfig":
      {
        "glossary":"projects/test-project/glossaries/GLOSSARY_ID"
      }}
  ]}
```

The `translations` field contains the regular machine translation before the glossary is applied;
the `glossaryTranslations` field contains the translation after the glossary is applied.

## Detect language

The `detectLanguage` method returns the language of a text string by sending an
HTTP request.

For example, the following request detects English as the language from the
input text `Hello, this is a test`:

```bash
curl -vv -X POST -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID:detectLanguage -d '{"parent": "projects/PROJECT_ID", "content": "Hello, this is a test"}'
```

## Get an operation

The `getOperation` method returns the latest state of a
[long-running operation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/glossary.md.txt#longrunning).
Use this method to retrieve the operation result generated by the
Vertex AI Translation API service. To use this method, specify your
project ID, the operation ID (`OPERATION_ID`) returned by the
long-running call, and [the Vertex AI Translation endpoint](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt).

For example, the following request returns the state of a long-running
operation, such as [creating a glossary](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-glossary.md.txt),
that is running in your project:

```bash
curl -vv -X GET -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID/operations/OPERATION_ID
```

## List operations

The `listOperations` method returns a list of the [long-running operations](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/glossary.md.txt#longrunning)
that match a specified filter in the request. To use this method, specify your
project ID and [the Vertex AI Translation endpoint](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt).

For example, the following request returns the list of operations running in
your project and limits the page size to 10 results per page:

```bash
curl -vv -X GET -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID/operations?page_size=10
```

## Get supported languages

The `supportedLanguages` method returns the list of languages that the
Vertex AI Translation API supports.

For example, the following request returns the supported languages by specifying
[the Vertex AI Translation endpoint](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt):

```bash
curl -vv -X GET -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN" https://ENDPOINT/v3/projects/PROJECT_ID/supportedLanguages
```

For the complete list of the supported languages, see [Supported languages for Vertex AI Translation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-translation-langs.md.txt).