Translation API Get and Submit Translations

Once you've discovered translatable items with the describe endpoints, use the /translations endpoint to read current translations and to create, update, or delete them.

Get Translations

GET /api/3.0/translations?language=fr&type=field&entityName=Account

Returns master values paired with their current translations for the specified language and type.

Parameter	Required	Description
`language`	Yes	Active language code (e.g., `fr`, `de`, `es`, `pt-BR`, `es-MX`).
`type`	Yes	Translation type. See Translation Types Reference.
`entityName`	Conditional	Required for entity-dependent types (Entity, Field, Picklist, Button, Layout, RecordType, ValidationRule, LookupFilter).
`relatedId`	Conditional	Required for Picklist (field ID) and Layout (layout ID).

Response:

[
  {
    "RelatedToId": "a0F000000001xyz",
    "Type": "Field",
    "Aspect": "Label",
    "Name": "fr",
    "UniqueName": "AccountName",
    "MasterValue": "Account Name",
    "TranslationValue": "Nom du compte",
    "OutDated": false
  },
  {
    "RelatedToId": "a0F000000001xyz",
    "Type": "Field",
    "Aspect": "Help Text",
    "Name": "fr",
    "UniqueName": "AccountName",
    "MasterValue": "The primary name of the account",
    "TranslationValue": "",
    "OutDated": false
  },
  {
    "RelatedToId": "a0F000000002abc",
    "Type": "Field",
    "Aspect": "Label",
    "Name": "fr",
    "UniqueName": "Industry",
    "MasterValue": "Industry",
    "TranslationValue": "Industrie",
    "OutDated": false
  }
]

Translation object fields:

Field	Description
`RelatedToId`	ID of the translatable item.
`Type`	Translation type.
`Aspect`	Translation aspect (e.g., Label, Help Text). Empty for single-value types.
`Name`	Language code.
`UniqueName`	Unique identifier for the item (e.g., field name, app name).
`MasterValue`	The English / master language source.
`TranslationValue`	The current translation. Empty string if not yet translated.
`OutDated`	Reserved flag (currently always `false`).

Submit Translations

POST /api/3.0/translations
Content-Type: application/json

Creates, updates, or deletes translations. To delete a translation (and let the master value serve as fallback), send an empty translationValue.

Request body:

{
  "language": "fr",
  "translations": [
    {
      "type": "Field",
      "relatedToId": "a0F000000001xyz",
      "aspect": "Label",
      "translationValue": "Nom du compte"
    },
    {
      "type": "Field",
      "relatedToId": "a0F000000001xyz",
      "aspect": "Help Text",
      "translationValue": "Le nom principal du compte"
    },
    {
      "type": "App",
      "relatedToId": "a0A000000001mno",
      "translationValue": "Gestion des partenaires"
    },
    {
      "type": "Tab",
      "relatedToId": "a0T000000001abc",
      "translationValue": ""
    }
  ]
}

Translation item fields:

Field	Required	Description
`type`	Yes	Translation type. See Translation Types Reference.
`relatedToId`	Yes	ID of the item being translated.
`aspect`	Conditional	Required for multi-aspect types; omitted (or empty) for single-value types.
`translationValue`	Yes	The translation. Empty string deletes the translation.

Success response (HTTP 200):

{
  "success": true,
  "upserted": 3,
  "deleted": 1
}

Error response (HTTP 400):

{
  "success": false,
  "errors": ["Language 'xx' is not active"]
}

Worked Example: Translate All Fields of an Entity

Get active languages:
```
GET /api/3.0/translations/languages
```

Discover field metadata for the entity:

GET /api/3.0/translations/describe?type=field&entityName=Account

Fetch current translations:

GET /api/3.0/translations?language=fr&type=field&entityName=Account

Submit translations:

POST /api/3.0/translations

{
  "language": "fr",
  "translations": [
    { "type": "Field", "relatedToId": "a0F000000001xyz", "aspect": "Label", "translationValue": "Nom du compte" },
    { "type": "Field", "relatedToId": "a0F000000001xyz", "aspect": "Help Text", "translationValue": "Le nom principal du compte" }
  ]
}

Worked Example: Translate App Names

Discover the apps:

GET /api/3.0/translations/describe?type=app

Fetch current translations:

GET /api/3.0/translations?language=de&type=app

Submit:

POST /api/3.0/translations

{
  "language": "de",
  "translations": [
    { "type": "App", "relatedToId": "a0A000000001mno", "translationValue": "Partnerverwaltung" },
    { "type": "App", "relatedToId": "a0A000000002pqr", "translationValue": "Vertrieb" }
  ]
}

Worked Example: Full Entity Translation in One POST

Use the full-entity describe call (GET /translations/describe?type=entity&entityName=Lead) to gather every translatable element in one round trip, then submit all translations together:

POST /api/3.0/translations

{
  "language": "fr",
  "translations": [
    { "type": "Entity", "relatedToId": "a0B000000002def", "aspect": "Label", "translationValue": "Prospect" },
    { "type": "Entity", "relatedToId": "a0B000000002def", "aspect": "PluralLabel", "translationValue": "Prospects" },
    { "type": "Field", "relatedToId": "a0F000000005abc", "aspect": "Label", "translationValue": "Nom de l'entreprise" },
    { "type": "Button", "relatedToId": "a0B000000006def", "aspect": "Label", "translationValue": "Convertir" }
  ]
}

Worked Example: Delete a Translation

To remove a translation and revert to the master value, submit an empty translationValue:

POST /api/3.0/translations

{
  "language": "fr",
  "translations": [
    { "type": "Field", "relatedToId": "a0F000000001xyz", "aspect": "Help Text", "translationValue": "" }
  ]
}

Response:

{ "success": true, "upserted": 0, "deleted": 1 }

Tips

Batch submissions. The POST endpoint accepts an array of translations in one call. Batching reduces round trips and lets the server apply them as a single unit.
Handle empty cells consistently. An empty translationValue in POST deletes; an empty string in GET means "not yet translated".
Use the entity-full describe (GET /translations/describe?type=entity&entityName=X) when building tools that handle one entity at a time — it returns everything you need in one call.

<< Describe Endpoints | Translation Types Reference >>

Table of Contents