# Manual Translation REST APIs

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/manual-translation-api

# Manual Translation REST APIs

By default, ThoughtSpot translates system UI elements such as menu labels, button text, and navigation controls into the user’s configured locale. However, user-generated content such as object titles, column names, and description text is not automatically translated.

The Manual Translation REST APIs let administrators and developers supply custom locale-specific translations for ThoughtSpot UI strings programmatically, without using the ThoughtSpot Admin portal. You can use these APIs to:

-   Upload a CSV file containing custom translations for one or more locales
    
-   Export existing translations for review and editing
    
-   Retrieve a translation bundle for a specific locale at runtime
    
-   Delete all translations for an org or a cluster
    

These APIs are available from ThoughtSpot Cloud 26.7.0 onwards.

> **NOTE:** To manage manual translations through the ThoughtSpot Admin portal instead of the REST API, see Manual translation in the ThoughtSpot product documentation.

## Before you begin

The import, export, and delete endpoints require `ADMINISTRATION` (**Can administer ThoughtSpot**), `ORG_ADMINISTRATION` (**Can administer Org**), or APPLICATION\_ADMINISTRATION (**Can administer application**) privileges.

The translation bundle endpoint (`POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export`) does not require administrator privileges and is accessible to all authenticated users.

### How manual translations work

When a user opens an embedded ThoughtSpot component, ThoughtSpot applies translations in the following order of precedence:

1.  Custom translations uploaded via the Manual Translation API for the user’s configured locale
    
2.  ThoughtSpot’s built-in system translations for supported locales
    
3.  The ThoughtSpot default locale, US English (`en-US`)
    

If a translation key is present in the uploaded CSV file, the custom value is displayed. If it is absent, ThoughtSpot falls back to its built-in string for that locale.

Uploaded translations are scoped to either a single org (`ORG`) or for all Orgs. See [undefined](#org-scope) for details.

### Org scope

All Manual Translation API endpoints accept an optional `scope` parameter in the request body. This parameter controls the organizational context of the operation.

 
| Value | Description |
| --- | --- |
| 
`ORG`

 | 

**(Default)** Targets the calling user’s current org. Use for all standard single-org or per-org translation management.

 |
| 

`CLUSTER`

 | 

Targets the All Orgs context. Translations uploaded at cluster scope apply across all orgs in a multi-org deployment. Requires Tenant Admin or Org Admin privilege.

 |

If the `scope` parameter is omitted, it defaults to `ORG`.

## CSV file format

The import and export endpoints use a CSV file to represent translation data. All files must use UTF-8 encoding and conform to RFC 4180.

### Required columns

The CSV file must contain exactly three columns, with headers exactly as shown:

 
| Column | Description |
| --- | --- |
| 
`content`

 | 

The original ThoughtSpot UI string in the default locale. This is the lookup key for the translation.

 |
| 

`locale`

 | 

The locale identifier for the translation. Must be one of the [supported locale IDs]({{navprefix}}/{{locale-setting}}#_supported_locale_ids) and must be in lowercase (for example, `fr-fr`, `de-de`, `ja-jp`).

 |
| 

`translated-content`

 | 

The translated string to display when the user’s locale matches the `locale` column value.

 |

> **NOTE:** Column headers are case-sensitive. Use exactly content, locale, and translated-content.

### Constraints

-   The file must have a `.csv` extension.
    
-   Maximum file size: 30 MB.
    
-   Maximum number of data rows per upload: 10,000.
    
-   Maximum characters per cell: 2,000.
    
-   HTML tags and control characters (other than tab, line feed, and carriage return) are not permitted in cell values.
    
-   The `locale` value must be lowercase in every row. For example, use `fr-fr`, not `fr-FR`.
    

### Example

The following example shows a valid CSV file with translations for French and German:

```text
content,locale,translated-content
Sales Performance,fr-fr,Performance des ventes
Sales Performance,de-de,Vertriebsleistung
Total Revenue,fr-fr,Revenu total
Total Revenue,de-de,Gesamtumsatz
New Answer,fr-fr,Nouvelle réponse
New Answer,de-de,Neue Antwort
```

## API endpoints

### Import manual translations

To import a custom translation file, use the `/api/rest/2.0/localizations/manual-translation/import` API endpoint. This endpoint allows you to upload a CSV file containing custom translations. The operation is an **upsert**, that is new translation entries are inserted, and existing entries that match on both the `content` and `locale` columns are updated in place. A single upload can contain translations for multiple locales.

The request body uses `multipart/form-data` encoding.

 
| Parameter | Description |
| --- | --- |
| 
`translations_file`

 | 

The CSV file containing translations. Must meet the [CSV format requirements]({{navprefix}}/{{manual-translation-api}}#csv-format).

 |
| 

`scope`

 | 

_Optional_. Org scope selector. Allowed values are `ORG` and `CLUSTER`.

 |

A successful request returns HTTP `204 No Content`. If the file fails validation (for example, missing headers, oversized file, or invalid locale), the API returns HTTP `400 Bad Request` with an error description.

### Export manual translations

To export or download manual translated terms and labels in a CSV file, use the `/api/rest/2.0/localizations/manual-translation/export` API endpoint. This endpoint downloads all existing manual translations for the specified org scope as a CSV file. The downloaded file uses the same three-column format as the import CSV and can be edited and re-uploaded.

 
| Parameter | Description |
| --- | --- |
| 
`scope`

 | 

Org scope selector. Allowed values are `ORG` and `CLUSTER`.

 |

A successful request returns HTTP `200 OK` with the CSV file in the response body and a `Content-Disposition: attachment; filename=manual-translation.csv` response header. If no translations have been uploaded for the specified scope, the API returns HTTP `404 Not Found`.

### Get translation bundle

To retrieve a JSON map of all manual translations for a specific locale, use the `/api/rest/2.0/localizations/manual-translation/locales/{locale}/export` API endpoint. This endpoint can be used by the embedding applications to load custom translations at runtime, for example, to apply translations during initialization of an embedded ThoughtSpot component.

 
| Parameter | Description |
| --- | --- |
| 
`locale`

 | 

The locale to retrieve translations for. Must be lowercase and match the pattern `^[a-z]{2,}(-[a-z0-9]{2,})?$`. For example, `fr-fr`, `de-de`, `ja-jp`.

 |

A successful request returns HTTP `200 OK` with a JSON object in the following structure:

```json
{
  "data": {
    "translations": {
      "Sales Performance": "Performance des ventes",
      "Total Revenue": "Revenu total",
      "New Answer": "Nouvelle réponse"
    }
  }
}
```

If no translations have been uploaded for the requested locale, the response returns an empty `translations` map.

### Delete manual translations

To delete all manual translations, use the `/api/rest/2.0/localizations/manual-translation/delete` API endpoint. This endpoint deletes all manual translations for the specified org scope. After the delete operation, ThoughtSpot uses the built-in UI strings for all locales until new translations are uploaded.

> **WARNING:** This operation deletes all translations for the specified scope. It cannot be scoped to a single locale or a subset of translation keys. This operation is not reversible.

 
| Parameter | Description |
| --- | --- |
| 
`scope`

 | 

_Optional_. Org scope selector. Allowed values: `ORG` and `CLUSTER`.

 |

A successful request returns HTTP `204 No Content`.

## Additional resources

-   [Configure locale in the Visual Embed SDK and via the Users REST API]({{navprefix}}/{{locale-setting}})
    
-   [Manage translations through the ThoughtSpot Admin portal](https://docs.thoughtspot.com/cloud/latest/manual-translation)