Multilanguage

Activate and configure

Multilanguage is a free, opt-in add-on. Activate it under Apps or Settings → Plugins → Multilanguage. The Plugins section also contains a horizontal Digital E-Commerce settings tab.

Set the shop's default language under Settings → General. Add target languages under the Multilanguage tab. Source content stays in the existing product/page editors; translations are stored separately. Deactivation preserves translations.

The source language is captured when the add-on is first configured. Changing the shop default later changes delivery fallback, not the language of stored original content. Built-in checkout phrases have German source text independently of the shop's source language.

Admin configuration uses a shop admin session. The storefront endpoints use the shop's publishable key and origin allowlist, as described in Authentication. Admin routes are served by the shop-admin backend; store routes by shop and checkout backends. The combined API serves both.

Select the response language

Use a query parameter on supported read endpoints:

curl "$SELLFORGE_API_URL/api/store/products?lang=en" \
  -H "X-Public-Key: $SELLFORGE_PUBLIC_KEY" \
  -H "Origin: $STOREFRONT_ORIGIN"

lang supports canonical language tags such as en, fr and pt-BR. An enabled exact language wins; otherwise an enabled base language is used (en-GB → en). An unsupported language falls back to the shop default. Invalid syntax returns 400. Omitting lang selects the shop default. A GET request has no language body.

Fallback is per field: current requested-language translation → current shop-default translation → original text. Outdated translations are kept for editing but not delivered. An explicit source-language request returns original text. Responses include Content-Language and private/no-store cache control; storefront caches must additionally separate shops and languages.

Localized responses cover product names/descriptions, options, variants, metadata SEO text, image text, customer-visible custom-field presentation, category/brand names, published CMS pages, product page-builder layouts, legal pages and shop branding. Business IDs, slugs, SKUs, raw custom-field values, option identifiers, prices and inventory do not change. Admin reads retain source content unless lang is explicitly supplied.

Edit translations

Product and page editors contain a side-by-side Translations panel. Settings → Plugins offers a resource browser for products, categories, brands, pages, layouts, custom components, product fields, shipping methods, plans, sales, legal content, branding, email templates and checkout phrases.

Read queries require language. Lists accept q, offset (default 0), limit (default 20, maximum 50) and status=all|missing|stale. Follow next_offset until it is null. Status filtering applies within each scanned page; an empty filtered page can still have a next page.

Resource kinds are product, category, brand, page, layout, component, field, shipping, plan, sale, legal, branding, email and checkout. Use the product ID for layouts, shop for branding/checkout, a legal key such as terms, or an email key such as order_confirmation.

Each document returns revision and fields containing path, source, source_hash, value, format and status. Copy the revision and source hash from the latest read when writing:

For large documents, set fields_limit (1–50) and fields_offset. The response includes total_fields and next_fields_offset; follow the latter until null. MCP reads use this field pagination automatically, preserving complete source text and hashes.

{
  "revision": 0,
  "fields": [
    {
      "path": "/name",
      "value": "Handbook",
      "source_hash": "REPLACE_WITH_THE_64_CHARACTER_HASH_FROM_THE_READ"
    }
  ]
}

Only paths offered by the source document are accepted. Keep template placeholders intact. URL translations accept HTTPS or local paths. Empty/null values remove a field translation and restore fallback. A source change or concurrent translation edit returns 409; read again and reconcile changes rather than replaying an old write.

All reads and writes are bound to the authenticated shop and the resource area's existing permissions. A foreign resource ID returns 404.

Connected AI apps

Use the existing connection under API Tokens → Connected AI Apps. Translation runs in that AI client using its model. Sellforge supplies source text and receives translated fields; the connection does not grant Sellforge a provider API key or background model invocation.

The integrated /mcp endpoint offers three tools per area: uebersetzungen_<area>_liste, uebersetzungen_<area>_lesen and uebersetzungen_<area>_speichern. Areas are catalog, content, shipping, digital and marketing.

The corresponding <area>:read and <area>:write connection scopes apply. Catalog permissions cannot edit email/legal translations, and translation scopes cannot activate plugins or change authentication/billing settings. Ask the connected app to read missing/stale texts, preserve placeholders, and save only those fields. The editor's Copy AI task button prepares this request.

Checkout and customer communication

Pass lang in the creation body of POST /api/store/checkout-sessions, POST /api/store/abo-sessions, or POST /api/store/cart. Otherwise the shop default is used.

The hosted checkout response includes language, languages and an i18n text dictionary. Its language selector persists the choice through PATCH /api/checkout/:id/language with { "lang": "en" } before payment starts. GET language overrides are presentation-only; use the PATCH route to persist a change. After order creation, changing the checkout language returns 409.

The selected language is stored with the cart/order. Product-name snapshots and translated order-confirmation, shipping and refund templates use that language. Missing or outdated email fields use the same fallback rules. Manual customer-facing source text and configured translations remain separate from the German Sellforge administration interface.