Set up languages and classifications
Add a language
Locale, fallback, which attributes, who translates.
Adding a language is four decisions and about ten minutes of clicking. The decisions are what matter — three of them are hard to change once translated data exists.
Before you begin. Decide whether this is a new language in an existing
market or a new market. Austria selling in German is a new market (different
prices, different tax, same language). France is both. Getting this wrong means
redoing the price lists, not just the translations. See
Currencies and tax.
Locales belong to markets
A market is a business context — a country or region with its own currency, its
own tax classes and its own locales. A locale is a language plus a country:
de-DE, de-AT, fr-CH, en-GB. One market can carry several.
Why the country half matters even when the language is identical:
- Prices and tax differ between
de-DEandde-ATeven though the text is the same. - Formats differ — dates, decimal separators, address layout.
- Vocabulary differs more than people expect. Swiss German commercial vocabulary is not German German, and an Austrian buyer notices.
- Search engines need it. A
de-ATpage and ade-DEpage with the same content need hreflang links so the right one is served in the right country, and neither is treated as duplicate content.
Steps
- Go to Configuration › Markets.
- Open the market, or create it if this is a new country context. Set its currency, tax classes and default locale.
- Add the locale: language code, country code, and its code (
fr-CH). - Mark one locale per market as default. This is the locale a buyer gets before they choose, and the one completeness reports against by default.
- Set the fallback chain for the new locale — the ordered list of locales to try when a value is empty. Regional variant first, then base language, then your source language. See the table below.
- Decide which attributes are actually in scope for this language, and write it down. Not every localizable attribute needs translating in every market.
- Assign the storefront to the market and enable the language switch. See Languages and markets.
- Confirm a search index exists for the new locale before you announce anything — each locale searches its own index.
Choosing the fallback
| Chain | Behaviour | Use for |
|---|---|---|
de-AT → de-DE → (empty) | Austrian text, else German, else nothing | Regional variants of a language you already have |
fr-CH → fr-FR → en → (empty) | French, else English | A new language with a partial catalog |
pl-PL → en → (empty) | Polish, else English | Markets where English is acceptable to buyers |
pl-PL → (empty) | Polish or nothing | Where mixed language is worse than a gap |
Do not fall back to your source language for long text. A German product
name in a Polish result list is recognisable and useful. Three paragraphs of
German marketing prose on a Polish product page tells the buyer the shop was not
built for them. Fall back on
name, leave description empty, and let
completeness report the gap honestly.Which attributes are in scope
Go through your localizable attributes once and put each in one of three buckets for this language:
| Bucket | Attributes | Who does it |
|---|---|---|
| Must have before launch | Category labels, family labels, option labels, name | Professional translator or a native speaker in the market |
| Should have, phased | short_description for the top 500 articles | Machine draft plus review |
| Nice to have | description, application_notes on the tail | Machine draft, reviewed when someone has time |
The first bucket is a few thousand short strings and is what makes the shop feel translated. Do it properly and do it first — see How catalog translation works.
Who translates
Three roles, and they should be three different people:
- Translator — enters and edits values for one or more locales. Sees the source value and the target field, and nothing else they could break.
- Reviewer — approves machine drafts and translator work, moving a value to the reviewed state. Usually someone in the market, often from Sales.
- Terminology owner — maintains the glossary: brand names, norm designations, material codes and the terms that must always be translated the same way. One person, not a committee.
The reviewer role is the one companies skip, and it is the one that decides whether the catalog is trusted in that market. A salesperson in the country who spends two hours a week approving is worth more than an agency you never speak to.
What to check
- Switch the storefront to the new locale. The navigation, the category names and the facet labels must all be in the new language. If the facets are still German, the option labels were not translated.
- Open a product with no translation and confirm the fallback behaves the way you configured it — not blank where you expected fallback, not German prose where you expected blank.
- Check completeness for the new locale. The number will be low. That is correct and it is your work list.
- Search a common term in the new language. A near-total zero-result rate here is normal on day one and is the fastest measure of translation progress from then on.