Menu

Translations API Routes

A translation is a localized version of content in a specific locale. For example, a product description in French. These API routes allow admin users to manage translations for different locales and resources.

GET /admin/translations#

List Translations

Retrieve a list of translations. The translations can be filtered by fields such as reference_id (For example, the ID of a product). The translations can also be sorted or paginated.

Feature flag: This API route is only available when the translation feature flag is enabled. Set the MEDUSA_FF_TRANSLATION environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

qstringOptional
Search query to filter translations by their fields.
reference_idstring | string[]Optional
Filter translations by a reference ID. For example, the ID of a product.
referencestringOptional
Filter translations by the resource they belong to. For example, product or product_variant.
locale_codestring | string[]Optional
Filter translations by a locale code in BCP 47 format.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
with_deletedbooleanOptional
The translation's with deleted.
fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.

Request examples

Responses

200 OK

limitnumber
The maximum number of translations returned.
offsetnumber
The number of translations skipped before retrieving the returned translations.
countnumber
The total number of translations matching the query.
estimate_countnumberOptional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
translationsobject[]
The list of translations.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/translations/batch#

Manage Translations

Manage translations in bulk by creating, updating, or deleting multiple translations in a single request. You can manage translations for various resources such as products, product variants, categories, and more.

Feature flag: This API route is only available when the translation feature flag is enabled. Set the MEDUSA_FF_TRANSLATION environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request body (application/json)

createobject[]Optional
The translations to create.
updateobject[]Optional
The translations to update.
deletestring[]Optional
The translations to delete.

Request examples

Responses

200 OK

createdobject[]
The created translations.
updatedobject[]
The updated translations.
deletedobject
Summary of the deleted translations.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • translation.created: Emitted when translations are created.
  • translation.updated: Emitted when translations are updated.
  • translation.deleted: Emitted when translations are deleted.

GET /admin/translations/entities#

List Translatable Entities

Retrieve a list of translatable entities. The entities can be filtered by fields such as id. The entities can also be sorted or paginated.

Feature flag: This API route is only available when the translation feature flag is enabled. Set the MEDUSA_FF_TRANSLATION environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

typestring
Filter by a translatable entity type.
Example: product
idstring | string[]Optional
Filter by an entity's ID.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
with_deletedbooleanOptional
The translation's with deleted.
fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

dataobject[]
The list of translatable entities.
countnumber
The total number of translatable entities.
offsetnumber
The number of items skipped before retrieving the returned items.
limitnumber
The maximum number of items returned in the response.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/translations/settings#

List Translation Settings

Retrieve the list of translatable fields for all entities, such as products and collections. You can also filter the results by entity type or active entities.

Feature flag: This API route is only available when the translation feature flag is enabled. Set the MEDUSA_FF_TRANSLATION environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

entity_typestringOptional
The entity to retrieve translation settings for.
Example: product
is_activebooleanOptional
Filter resources by whether translations is activated for them or not. If not provided, all resources are returned.

Request examples

Responses

200 OK

translation_settingsobject
The translation settings details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/translations/settings/batch#

Manage Translation Settings

Create, update, or delete multiple translation settings.

Feature flag: This API route is only available when the translation feature flag is enabled. Set the MEDUSA_FF_TRANSLATION environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request body (application/json)

createobject[]Optional
The translation settings to create.
updateobject[]Optional
The translation settings to update.
deletestring[]Optional
The translation settings to delete.

Request examples

Responses

200 OK

createdobject[]
The created translation settings.
updatedobject[]
The updated translation settings.
deletedobject
The deletion result.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/translations/statistics#

Retrieve Translation Statistics

Get statistics on translations for specified locales and entity types. This includes overall translation progress for each entity type, and statistics for each locale within those entity types.

Feature flag: This API route is only available when the translation feature flag is enabled. Set the MEDUSA_FF_TRANSLATION environment variable to true to enable it.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

localesstring | string[]
The locale codes to retrieve translation statistics for. Locale codes are in BCP 47 format.
entity_typesstring | string[]
The table names of entities to retrieve translation statistics for.

Request examples

Responses

200 OK

statisticsobject
The translation statistics for different entity types. The key is the entity type, and the value is an object containing the statistics for that entity type.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page