Sign Customiser

Customiser languages

Update language translations

Copy page

Write draft values for the language. The body names the keys to change and the value to give each of them; a key the body does not name keeps the value it has, and draft_value: null clears one back to blank.

PATCH/api/v3/customisers/{customiser_id}/languages/{language_code}/translations

Overview

Nothing a shopper sees changes: publishing the language is what promotes draft values to published copy. Only draft_value is writable. Every other property the read publishes is server-owned — the catalogue supplies the key, the group, whether it is required, and the source copy; a publish supplies the published values; the sync supplies the staleness — so naming one is a 422 pointing at it rather than a value silently dropped. A key may appear once; a second entry for the same key is refused rather than resolved. A 422 problem with code invalid_translation_key means the body names keys this language cannot accept, with a pointer per offending entry and a reason of unknown (the catalogue has never carried it) or retired (the copy it translated is gone). A 422 validation_failed with a pointer at /translations/{index}/draft_value means a value dropped a placeholder its source copy requires — a value that loses {price} would render a broken sentence in the storefront. The write clears the customiser cached storefront configuration and runs the advisory language sync. It never regenerates your Shopify products, product images, or product cache. Send an Idempotency-Key header (1-255 visible ASCII characters, e.g. a UUID) to make the write safe to retry: repeating the same key with the same body replays the original response (marked Idempotency-Replay: true) without executing again; the same key with a different body is a 409 problem with code idempotency_key_conflict. The header is optional here, as on every update operation. Requires the customisers:write scope. A 400 problem means the body is not valid JSON or the Idempotency-Key header is malformed; a 422 problem with code unknown_field means the body names properties this operation does not define. 401, 403, 404, and 429 problems behave as on the read operation, with customisers:write as the required scope.

Authorisation

Bearer token required. Include it in theAuthorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id, from the list customisers operation.

Example: 1

language_codestringpathrequired

The language tag, from the list customiser languages operation.

Example: fr

Request body

translationsarraybody

Request body example

application/json
{
  "translations": [
    {
      "key": "selection:12:label",
      "draft_value": "Couleur"
    }
  ]
}
Update language translations
curl https://web.signcustomiser.com/api/v3/customisers/1/languages/fr/translations \
  --request PATCH \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "translations": [
    {
      "key": "selection:12:label",
      "draft_value": "Couleur"
    }
  ]
}'
Response
{
  "data": {
    "object": "customiser_language_translations_write_receipt",
    "customiser_id": 42,
    "language_code": "fr",
    "written_key_count": 2,
    "cleared_key_count": 1,
    "missing_required_key_count": 82,
    "publishable": false,
    "keys": [
      "selection:12:label",
      "selection:13:label",
      "settings:custom_sizing_title"
    ]
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/languages/fr/translations",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}