Skip to content
ShuttleShuttle Docs
Status
View as MarkdownPlain text for AI toolsOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this pageOpen in GitHub CopilotAsk questions about this page

Import branded strings from a file

Replaces the wording of many strings in one request, for one branding and language. It is how a translation is loaded: export the language to a CSV, send it out for translation, import the file back. Merchant View reads the file in the browser, matches every row against the strings on screen, shows what will be imported and what it could not match, and sends the changed rows as one request. Export is done entirely in the browser and makes no server call.

Where you can do this

Section titled “Where you can do this”

Before you start

Section titled “Before you start”
  • Every id in the file begins with the key of a strings mapping published by a provider integration installed on the client; the mapping is what turns the id into the message the provider integration actually reads.
  • A branding to write to. When an item names none, the client’s default branding is used.
  • A language. Importing into a language that the branding has no strings for adds it; there is no separate add-language operation, as Override a branded string describes.
  • In Merchant View, the screen must have loaded the strings for the branding and language being imported, because the file is matched against them before anything is sent.

Rules

Section titled “Rules”

Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.

Rule Checked by What you see
The body must carry a non-empty strings array or a string object The API VALIDATION_ERROR: “API body error: missing string object”
Every item must carry an id The API VALIDATION_ERROR: “API body error: missing string id”
Every id’s prefix must match a strings mapping; one unmatched id rejects the whole file before anything is written The API VALIDATION_ERROR: “strings mapping not found”
Every item is applied exactly as a single save: a value equal to the one the string already inherits removes the override instead of storing it, so the string goes back to inheriting. See Override a branded string and Reset a branded string to its original The API (silent)
A string id that several provider integrations share is written to every one of them The API (behaviour, not an error)
The import is not atomic: mapping groups are written one after another, and a failure part-way leaves the earlier groups saved The API the failing write’s error, with earlier strings already changed
One branding write at a time per client; a write still waiting after 10 seconds is refused The API INVALID: “BOLT-7059”
The file travels as one JSON body, which must be under 10 MB The API 413
The import targets the branding and language on screen, not anything in the file; Merchant View warns in the confirmation when the file name does not contain the selected language code Merchant View screen warning shown, import still allowed
Merchant View sends only rows whose id it already lists and whose text differs from what is shown; unmatched ids are listed in the confirmation and dropped, unchanged rows are skipped Merchant View screen ids listed as ignored, nothing sent for them
Merchant View drops the file’s first row when its first cell contains “id”, so a file with no header whose first id contains those letters loses that row Merchant View screen that row is not imported
A file that would change nothing cannot be submitted from Merchant View Merchant View screen Import disabled, “0 strings” message
Rows Merchant View could not parse are counted and reported as skipped in the confirmation Merchant View screen count shown, rows not sent

What happens

Section titled “What happens”
  • Every string in the file that was matched and changed now carries the new wording for the branding and language that were on screen. Strings not named in the file are left exactly as they were: an import is a partial update, never a replacement.
  • Any imported value that is identical to the wording the string inherits removes the override instead, so that string goes back to following its parent branding or the provider integration’s own wording.
  • The response lists the imported strings as they now stand, and Merchant View’s list updates from it without reloading the screen.
  • The new wording is what customers and staff see the next time a screen or message using those strings is loaded; where several provider integrations share a string, it changes in all of them.
  • Importing into a language the branding had no strings for adds that language to the branding.
  • A file that fails part-way leaves the strings written so far changed. Re-importing the same file is safe.

Who can do this

Section titled “Who can do this”
  • Roles: Admin only. Support does not hold branding: screen terminology is business setup, not customer service.
  • Permission keys (for clients managing permissions directly): Merchant View opens the localisation screen only when a branding permission names one of the session’s brandings exactly, so a user granted branding at division level is refused by the screen although the server would accept the call. The screen also opens for a deep-link session without that check; the server’s check still applies.
  • Admin app: the branding selector needs the same permission. Export is done in the browser and calls nothing. The upload control takes one .csv file at a time, so a language is one file and one request.
Section titled “Related”

Was this page helpful?