Translations - Spree Commerce documentation

Overview

Two different things need translating, and they’re handled separately because they belong to different people. Your content — product names, descriptions, category names — is written by whoever runs the store. Spree stores a version of each field per language. The interface — button labels, error messages, email wording — is written by Spree, and is already translated into dozens of languages by the community.

Which languages a region gets is decided by its Market. A market sets the default locale alongside the currency, so a visitor from France lands on French prices and French copy without choosing anything.

Translating content

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.

Translating the interface

Spree’s own strings — everything in the dashboard and in transactional emails — come from a community-maintained project covering 40+ languages.

spree bundle add spree_i18n

bundle add spree_i18n

That’s the whole installation. Locales are picked up automatically; nothing needs copying into your app.

See the supported locales in the Spree I18n repository. Contributions are welcome if yours is incomplete.

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

​Overview

​Translating content

​What can be translated

​Reading translated content

​Writing translations

​Translating the interface

​Related

Overview

Translating content

What can be translated

Reading translated content

Writing translations

Translating the interface

Related