Customisers
update_customiser_language_translations
destructive writeUpdate customiser language translations
Translate a language a page at a time, or correct individual draft values, before the language is published.
Overview
Writes draft values for up to 100 translation keys of one customiser language per call. Keys the call does not name keep their values, a value replaces the current draft, and draft_value null clears a key back to blank. Unknown and retired keys are refused with invalid_translation_key, and a value that drops a placeholder its source copy needs is refused with validation_failed. Nothing a shopper sees changes until publish_customiser_language. The result reports counts and whether the language can now be published, not the values. It requires the customisers:write scope; idempotency_key is optional, and dry_run true checks the write without saving anything.
Permission
Requires thecustomisers:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A customiser id from list_customisers and a language code from list_customiser_languages.
- The keys to write, from get_customiser_language with include translations.
- A merchant has connected this store and approved the customisers:write scope.
Side effects
- Replaces the draft value of each named key, or clears it when draft_value is null. Published copy does not change.
- Clears the customiser cached storefront configuration and runs the language sync.
- Claims the idempotency_key for at least 24 hours when one is sent.
Arguments
The customiser id, from list_customisers.
The BCP 47 language tag the language is addressed by, such as fr or pt-BR, from list_customiser_languages.
The keys to write, between 1 and 100 per call, each with its draft value. A key may appear once. Keys this list does not name are unchanged. Send larger dictionaries in several calls.
A translation key this language carries, such as selection:12:title, from get_customiser_language with include translations.
The draft value to write. Null clears it back to blank, which makes a required key block publishing again.
An optional client-generated key unique to this logical write, such as a UUID. Repeating the call with the same key and the same arguments replays the original result; the route does not require one.
When true, the write is checked against the keys the language accepts and the placeholders each source copy needs is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false. A dry run claims no key.
Result
How many keys were given a value and how many were cleared, the count of required keys still blank, and whether the language can now be published. A dry run returns the write verdict instead and saves nothing.
How many of the named keys were given a value. Absent on a dry run.
How many of the named keys were cleared back to blank. Absent on a dry run.
How many required keys of the language still have a blank draft after the write. Absent on a dry run.
Whether publish_customiser_language would now pass the required-copy check: true exactly when missing_required_key_count is zero. Absent on a dry run.
Present and true only when dry_run was requested.
Present only on a dry run, and always true: a failing dry run returns a tool error instead.
Present only on a dry run: the write verdict.
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
Error cases
The key was already used with other arguments. Re-send the original arguments or use a new key.
The connection was approved without customisers:write.
Read invalid_keys. Each named key is unknown to this language or retired. Read the current keys with get_customiser_language.
No customiser with that id, or no language with that code on it.
A value is too long, a key appears twice, an entry names a read-only property, or a value drops a placeholder such as {price} that its source copy needs. Read errors for the pointer.
Translate two keys and clear a third
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_customiser_language_translations",
"arguments": {
"customiser_id": 42,
"language_code": "fr",
"translations": [
{
"key": "selection:12:title",
"draft_value": "Couleur"
},
{
"key": "selection:13:title",
"draft_value": "Police"
},
{
"key": "selection:14:title",
"draft_value": null
}
],
"idempotency_key": "3c4d5e6f-7081-4923-a4b5-c6d7e8f90a1b"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"customiser_id": 42,
"language_code": "fr",
"written_key_count": 2,
"cleared_key_count": 1,
"missing_required_key_count": 83,
"publishable": false,
"idempotent_replay": false
}
}
}A key the language does not carry (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_customiser_language_translations",
"arguments": {
"customiser_id": 42,
"language_code": "fr",
"translations": [
{
"key": "selection:999:title",
"draft_value": "Couleur"
}
],
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "invalid_translation_key",
"title": "Invalid translation key",
"detail": "The write names translation keys this language cannot accept. Read the translations to see the keys it carries, then retry with only those.",
"recovery": "Remove or correct each key in invalid_keys. Read the language translations with get_customiser_language and include translations to see the keys it accepts.",
"invalid_keys": [
{
"key": "selection:999:title",
"reason": "unknown"
}
]
}
}
}
}