docs
  1. Advanced
  2. Internationalization
  3. Locales

Locales

Overview

Locales control how SCAYLE selects translations and regional formatting.

A locale combines a language with a territory. Example: en_GB means English for the Great Britain locale. The territory part helps distinguish regional variants, such as en_GB and en_US.

In SCAYLE, the locale does not define the physical market by itself. The shop country does that. A shop in Ireland can use en_GB. A shop in Austria can use de_DE.

Relationship diagram

The following diagram shows how the core concepts relate to each other:

In short: the country defines the market, and the locale defines the language behavior.

Core terms

Country

A country defines market-specific behavior. This includes prices, price rounding, allowed billing and shipping countries, and other country-level settings.

Language

A language describes the text customers should see. In SCAYLE, language-related fields often use a full locale code instead of a two-letter language code.

Locale

A locale combines language and territory, for example de_DE or fr_FR.

Use locales to:

  • resolve translations
  • format text and values for a region
  • distinguish regional language variants

Shop country

A shop country is the SCAYLE unit that combines market and language for one shop.

Today, you create one shop country per country and locale combination. If you want to serve Switzerland in German and French, you create two shop countries.

In several parts of SCAYLE, labels such as "language" or "default language" actually store a locale like en_GB or de_DE.

How SCAYLE models locales today

A shop country currently has:

  • one country
  • one default locale

If you need multiple languages for one country, create multiple shop countries.

Examples:

  • Netherlands + Dutch → one shop country
  • Netherlands + English → another shop country
  • Switzerland + German → one shop country
  • Switzerland + French → another shop country

Standard and non-standard locales

SCAYLE works best with standard locale codes.

Examples:

  • en_GB
  • en_US
  • de_DE
  • fr_FR
  • nl_NL

Some tenants also use custom or non-standard locale codes. Checkout can map those codes to a supported default locale.

Example:

  • a custom English-for-Netherlands locale can be mapped to en_GB

This mapping prevents broken translations. If no exact locale exists, the system can still load a sensible default.

Use standard locales whenever possible. Custom locales add complexity and usually require extra translation management.

How translations work across SCAYLE

SCAYLE does not handle every translation type in the same way.

Product and catalog translations

Product data translations are usually managed by locale in the translation datasets.

This includes:

  • attribute groups
  • simple attributes
  • advanced attributes
  • master categories
  • navigation labels
  • filter labels

For many datasets, translations are shared across shops that use the same locale. This means two shops with the same locale usually read from the same translation container.

That is efficient, but it also matters for multi-brand setups.

If two shops use the same locale, they can share the same product-data translations. Use this carefully when brands need different wording.

Simple vs. advanced attributes

Simple attributes store direct translations per locale.

Advanced attributes are more complex. Their translations are linked through a generated key based on the base-language value. If that base value changes, the related translations may also need to be updated.

Product name fallback

Localized product names follow a separate fallback chain.

SCAYLE first checks whether the advanced attribute group product_name with ID 553 exists.

If it exists, SCAYLE checks whether the product has an advanced attribute value for the current app.

If the translated value exists and is not empty, SCAYLE uses that value.

An empty string is treated like a missing translation.

If no usable translated advanced attribute exists, SCAYLE falls back as follows:

  1. If the app locale is the configured default locale, use the name value from the products table.
  2. If the app locale is not the default locale, check whether a master category exists for the product and app.
  3. If no master category exists, use the name value from the products table.
  4. If a master category exists, use its translated name.
  5. If that master category contains the product name in single quotes, use the translated master category name and append the product name as a suffix.

In short, the translated product_name advanced attribute has the highest priority. If it is missing, products.name is the fallback for default-locale requests. For non-default locales, SCAYLE first tries the translated master category before falling back to products.name.

For dataset-specific details, see Translations and Translate Product Data.

Checkout translations

Checkout uses a layered fallback model.

The effective translation is resolved from several sources, merged by priority:

  1. Panel translations
  2. Locale-specific default translations
  3. Global English defaults

During migration phases, legacy checkout translations can still be part of the resolution chain. Missing keys fall back to the next available layer.

This gives two benefits:

  • tenants can override only the keys they need
  • customers should never see raw translation keys

For checkout-specific behavior, see Localization of Checkout.

How to choose the right locale

Pick the locale by customer language first.

Then check whether SCAYLE already provides a matching default locale.

Good patterns

  • Use de_DE for German-speaking shops in Germany
  • Use de_DE for German-speaking shops in Austria if no Austria-specific locale is needed
  • Use fr_FR for French-speaking shops in Switzerland if no Switzerland-specific locale is needed
  • Use en_GB for English-speaking markets when British English is acceptable

Avoid when possible

  • creating custom locales only to reflect the shop country
  • using separate locales without a real translation or formatting need
  • duplicating locales for each brand

If a standard locale already matches the language you need, prefer that option.

Practical examples

English shop in the Netherlands

If you want an English storefront for customers in the Netherlands:

  • create a shop country for the Netherlands
  • assign an English locale such as en_GB
  • manage Dutch and English as separate shop countries

The country remains Netherlands. The locale controls the language.

Switzerland with multiple languages

If you serve Switzerland in three languages, create three shop countries:

  • Switzerland + de_DE
  • Switzerland + fr_FR
  • Switzerland + it_IT

This is the current SCAYLE model.

Two brands with the same locale

If Brand A and Brand B both use nl_NL, product-data translations may be shared.

That works well for common terms. It can be a problem if each brand needs different wording.

In that case, plan your translation model before rollout. Shared locale translations are not a good fit for brand-specific copy.

Best practices

  • treat locale and country as different concepts
  • prefer standard locales over custom ones
  • create separate shop countries for each country-language combination
  • reuse existing default locales where possible
  • add overrides only where wording must differ
  • validate shared translations early in multi-brand environments
Next up
Countries in SCAYLE Panel