Translations - Spree Commerce documentation

For Dashboard UI translations see Dashboard Customization: Translations.

Every translatable record keeps one row per language, so a product genuinely has a French name rather than a French name pasted over the English one.

What can be translated

Resource	Fields
Product	`name`, `description`, `slug`, `meta_title`, `meta_description`
Category	`name`, `description`, `permalink`
Collection	`name`, `description`, `permalink`
Product type	`name`
Option type	`label`
Option value	`label`
Store	`name`, `seo_title`, `meta_description`, `meta_keywords`, and support contact details
Policy	`name`, `body`
Seller	`name`, `about`

Note that slugs are translated too. A French page can live at /produits/sac-spree rather than at the English slug with French words on it — which is what search engines actually reward. See Slugs.

Reading translated content

Ask for a locale and you get that language back. Nothing else about the request changes:

const product = await client.products.get('spree-tote', {}, { locale: 'fr' })

product.name        // "Sac Spree"
product.description // "Un sac fourre-tout élégant…"
product.slug        // "sac-spree"

const { data: categories } = await client.categories.list({}, { locale: 'de' })

// The Admin API resolves by ID only — slugs are not accepted here
const product = await adminClient.products.get('prod_86Rf07xd4z', {}, { locale: 'fr' })

curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
  -H 'X-Spree-API-Key: pk_xxx' \
  -H 'X-Spree-Locale: fr'

If a field has no translation for the requested locale, you get the default-language value rather than an empty string — a half-translated catalogue still renders as a usable page.

Responses vary by locale, so if you cache them, include the locale in the cache key. Spree sets Vary headers for you, which is enough for a CDN but not for a hand-rolled in-memory cache.

Writing translations

Merchants translate in the dashboard, switching locale on the record they’re editing. For bulk work — handing a catalogue to a translation agency — export to CSV, translate, and import it back. Translations can also be written through the Admin API, which is what you’d use to sync from an external translation service. Writes go through one batch endpoint — every entry succeeds or none do — so a product and its option values can be translated in a single request:

await adminClient.translations.batch([
  {
    resource_type: 'product',
    resource_id: 'prod_xxx',
    values: {
      fr: { name: 'Sac Spree', description: 'Un sac fourre-tout élégant…' },
      de: { name: 'Spree Tasche' },
    },
  },
])

// Which resources and fields accept translations
const { data: resources } = await adminClient.translatableResources.list()

curl -X POST 'https://api.mystore.com/api/v3/admin/translations/batch' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{ "translations": [ { "resource_type": "product", "resource_id": "prod_xxx", "values": { "de": { "name": "Baumwolltasche" } } } ] }'

Asking the API which resources are translatable means a translation tool doesn’t need a hardcoded list that goes stale.

Markets — which locale and currency a region gets
Slugs — localized URLs
Custom Fields — translating your own fields
Localization — the locale, currency and country headers

​What can be translated

​Reading translated content

​Writing translations

​Related

What can be translated

Reading translated content

Writing translations

Related