Manual Translation REST APIs
Cloud
26.7.0.clCloud (Latest)
26.6.0.clCloud
26.5.0.clCloud
26.4.0.clCloud
Software
26.3.0.swSoftware (Latest)
10.10.0.swSoftware
10.1.0.swSoftware
GitHub

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 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.

ValueDescription

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:

ColumnDescription

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 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:

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.

ParameterDescription

translations_file

The CSV file containing translations. Must meet the CSV format requirements.

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.

ParameterDescription

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.

ParameterDescription

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:

{
  "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.

ParameterDescription

scope

Optional. Org scope selector. Allowed values: ORG and CLUSTER.

A successful request returns HTTP 204 No Content.

Additional resources🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.