Translating content

Storefront-facing Llama Upsells text — the labels and messages shoppers see in the Llama Cart and in your Online Store widgets — is translated with Shopify's Translate & Adapt app. The translatable strings are exposed as store metafields holding JSON, so you copy each metafield's content, translate the values, and paste the result under the target language.

How translation works

The Llama Upsells theme app extension renders its UI text from a default English locale that ships with the extension. To present that text in another language, you don't edit the app — you translate the storefront strings through Shopify's translation layer.

Llama Upsells surfaces two metafields under Store metadata in Translate & Adapt:

Both metafields store their content as JSON. Each translatable string lives under a named key (for example, cartTitle or buttonAddToCartText), and you translate the value while leaving the key untouched.

Prerequisites

Translate Llama Upsells content

Open Translate & Adapt and choose a language to translate.

Translate the JSON content

The accepted format for translation is JSON. To translate a metafield:

Llama Cart variables

These keys live in llama-translatable-cart.content. Each one maps to a specific piece of Llama Cart text. The arrow (→) shows the default English value.

Rewards and messages

Cart lines and labels

Discount codes

Buttons and actions

Widget variables

These keys live in llama-translatable-campaigns.active and control the text in your Online Store widgets.

Gift-with-purchase messages live under a nested conditions object

The three gift-with-purchase progress strings — displayMessageOnProgress, displayMessageOnValid, and displayMessageOnInvalid — are not flat top-level keys in the JSON. For a gift-with-purchase widget they sit inside a conditions object, where each entry is keyed by the condition and holds its own copy of those three messages (plus a _conditionName label that helps you identify which spend/quantity rule it belongs to). The shape looks like this:

{
  "_type": "gift_purchase",
  "buttonAddToCartText": "Add",
  "conditions": {
    "<conditionKey>": {
      "_conditionName": "Spend over $50",
      "displayMessageOnProgress": "Spend more to receive this gift!",
      "displayMessageOnValid": "You are qualified to get a free gift",
      "displayMessageOnInvalid": "Spend another to include \"FREE GIFT\""
    }
  }
}

Rich-text, custom-HTML, and per-version/per-market data are aggregated into one metafield

Two more places hold translatable copy in the Llama Cart metafield, and both are arrays keyed by id rather than single named keys:

• richTextBlocks[].text — the text of each rich-text block you've added to the cart, one array entry per block.
• customBlocks[].html — the raw HTML of each custom-HTML block, one array entry per block.

Because these are aggregated, a translator opening llama-translatable-cart.content may see several entries that look alike — they're distinguished only by their id. Translate the text / html value in each entry and leave every id exactly as it is so the translation maps back to the right block. The same pattern applies to the emptyCartCollections, messages, and rewards arrays, which are also keyed by id.

Why the Llama Cart JSON contains multiple versions and markets

The Llama Cart metafield follows the ITranslatableLlamaCart shape: the top level is keyed by a version key (versionKey), and under each version sits a main block plus a marketBased array. So the structure is versionKey → main + marketBased[], where each marketBased entry carries its own id, the list of markets it applies to, and a full data block with the same fields as main.

This is why a single metafield can expand into several near-identical blocks: every active version contributes a main block, and any market with its own adapted copy adds a marketBased entry. Knowing the shape tells you exactly how many blocks to expect — translate main for the default experience, and each marketBased[].data for the markets you adapt.

Next steps