commercetools product translation is based on language-aware data such as LocalizedString fields, multilingual slugs and product attribute labels, presented through APIs in the customer’s actual Store and locale context. A properly localized composable commerce storefront needs more than translated product names: it must preserve SKU identity, variant selections, price and inventory facts, search discovery, cart data and checkout communication while showing natural text in the selected language.
This guide explains commercetools localization, Project languages, Store languages, localeProjection, storeProjection, Product Projections, LocalizedString product names and descriptions, localized slugs, localized enum values and headless ecommerce SEO. It is designed for international merchants, developers and translation teams that need to understand how language selection flows into a composable storefront without confusing it with currency, country or sales-channel eligibility.
In brief, define Project and Store languages; choose which catalog fields can hold localized values; translate source facts without changing products or variants; request the correct product projection; verify documented fallback; configure search, routes and frontend messages; and complete a multilingual cart-to-order test. Check the published API result rather than the staged editing view, and approve a new language only after direct links, failures, notifications and accessibility have been tested.
Quick answer: localized commercetools content needs the correct projection
commercetools can hold one product with several language-specific names, descriptions and slugs. Product Projection requests can narrow returned locales through explicit localeProjection or Store-context storeProjection, with documented fallback to available Project languages. These settings do not translate the frontend interface or authorize an item for every market. The correct implementation connects data-model languages, Store assortment, route generation, search, cart identity and customer communication deliberately.
Four definitions that prevent most multilingual errors
A Project language is a supported language in the Project configuration. A LocalizedString is an object that maps locale identifiers to values for a translatable field. A Product Projection is a customer-facing view of product information in a requested context, which may differ from staged editing data. A Store can supply its own context including language and assortment. Separately, price and currency depend on commercial configuration. Treating these concepts as interchangeable produces unreliable advice.
Detailed lessons: build a reliable composable multilingual store
1. Project languages establish the available locale set
commercetools Projects define a list of languages, and Stores can restrict relevant languages to a particular sales context. Language configuration is not the same thing as a translation of every product field. The customer may never see the raw API value. A frontend chooses which projection to request, which language to display and which action to take on the returned resource. That handoff is where accurate translations can become misleading if the context is wrong.
Example from a working store. A merchant enables French in its project but the storefront shows the English product because no French value was supplied or the Store context does not include it. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Document project languages, any Store-specific languages and the target audience; verify the existing translated values before declaring a locale launch complete. Write down the source resource, intended locale and Store, then reproduce the result with an explicit API request or browser route. A repeatable observation is more useful than an impression that the page looks different.
Acceptance test. Query one known product in each intended locale and compare actual name, description and slug values. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
2. LocalizedString is a map, not a duplicated product
A LocalizedString holds language-keyed text values associated with one underlying resource. A product name can therefore differ by locale while the product’s stable identity remains unchanged. A translation project should preserve what remains true independently of language: product identity, variant relationships, inventory, policy and transaction values. Everything else should be changed intentionally, with the correct owner approving that change.
Example from a working store. An integration creates a separate product for each language, splitting reviews and inventory even though only the marketing name varies. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Model translated titles and descriptions through the platform’s supported localized fields and keep product, SKU and variant identities stable across the audience. Ask a fluent reader what they believe they are buying and have a catalog specialist confirm the technical facts. Both judgments need to agree before a high-risk message is accepted.
Acceptance test. Compare API representations in two languages and confirm they identify the same product and variants. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
3. Localized product name and description
Product names and descriptions are LocalizedString fields that can express culturally natural text, but specifications and claims require factual equivalence. Think through the buyer’s path rather than one database field. Someone might find a product through search, save a cart, follow an emailed link or switch language while checking compatibility. The words must still describe the same commercial facts.
Example from a working store. A translated appliance description changes the supported voltage and suggests a warranty that is not offered in that market. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Translate user-facing explanatory text with a product specialist’s review of measurements, compatibility, duration and exclusions. Compare the language-specific display with the stable product and variant IDs. The acceptance test fails if an apparently harmless word change maps to a different resource.
Acceptance test. Compare the translated item with the source catalog and ensure no technical or contractual assertion changed accidentally. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
4. Localized slugs require stable routes
Product slugs can be language-specific and must satisfy commercetools field constraints and the uniqueness requirements in the Project. An ordinary reader does not care which API supplied the label. They care whether an option, warning or restriction is understandable and corresponds to what actually happens next. This is why localized content needs behavioral testing as well as proofreading.
Example from a working store. A French route uses a translated slug that clashes with another product or a page generator uses the English slug when it constructs a link. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Plan a locale-aware slug inventory and route resolver, preserve product identity behind human-readable paths, and handle old addresses with controlled redirects. Use a normal case and a missing-data case. The second test exposes fallback behavior and makes it possible to decide whether a translated page is truly complete.
Acceptance test. Open direct product URLs in two languages and verify correct item resolution, canonical choices and redirect behavior. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
5. Category titles and descriptions
Categories can use localized names and descriptions, but their references and parent-child structure also determine navigation. Many multilingual defects look similar: a missing translation, wrong locale projection, unpublished product, unavailable Store assortment or cached response can all produce a misleading screen. Distinguish these causes before changing content.
Example from a working store. A translated category displays ‘trail shoes’ while its underlying category membership includes unrelated accessories, confusing buyers. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Review category label translation alongside hierarchy, product assignment and navigation copy, with stable category keys for integrations. Retest from a fresh browser session or direct URL. Cached state and client navigation often conceal a wrong projection or unsupported localized slug.
Acceptance test. Browse from localized top navigation through a category into a product without pasting a deep link. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
6. Category slugs and breadcrumb alignment
Localized category paths must map to the correct category resources; merely translating the breadcrumb label does not create a valid route. A useful review is not a literal comparison of sentences alone. It checks the intention of the message, the conditions behind it and the actual product or operation to which it applies. Clear local phrasing must not introduce a new promise.
Example from a working store. A product URL works in German, but the breadcrumb leads to a missing or default-language collection page. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Resolve category addresses using supported localized values and design predictable fallback if a particular locale’s slug is missing. Make a small controlled change in staging and inspect the exact returned value after publication. This helps separate a translation mistake from a stale resource or unrefreshed build.
Acceptance test. Select a category from a fresh session, inspect breadcrumb destinations and compare the actual category resource IDs. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
7. Store languages versus localeProjection
A Store can specify languages and a product projection may use the Store’s locale list through storeProjection. An explicit localeProjection may take precedence in the API request. Translation reaches beyond a catalog. Frontend message bundles, search relevance, metadata, emails and error states are separate systems that still contribute to a shopper’s understanding of one transaction.
Example from a working store. A headless storefront sends one locale in its user state but the product API request projects another, leaving mixed-language names and categories. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Review actual request parameters and decide whether Store context or explicit locale projection is authoritative for each query. Where numbers or legal conditions appear, compare against the authoritative commerce source. Do not infer a new amount, eligibility or warranty from language alone.
Acceptance test. Issue controlled requests and compare the returned LocalizedString keys with the intended customer language. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
8. Fallback to Project language order
When a localized field lacks a requested value, product projection behavior can check the Project’s configured languages in order and return another available value. Respect the structure of the data model. Stable keys link services together; language-dependent values help people read those services. Mixing the two creates expensive mistakes that no stylistic edit can repair.
Example from a working store. A Spanish page unexpectedly shows German text because a team assumed fallback would always choose English first. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Inspect the configured language ordering and missing-field behavior, and define which fallback content is acceptable to customers. Keep a concise evidence record containing expected wording, actual wording, product identifier, request context and final user outcome. It gives reviewers an unambiguous way to confirm a fix.
Acceptance test. Deliberately omit a harmless translation in staging, request the locale and compare the API response with storefront rendering. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
9. Product Projections and published content
Product Projections are designed for storefront presentation and generally serve published current data, subject to specific API permissions and projections. The customer may never see the raw API value. A frontend chooses which projection to request, which language to display and which action to take on the returned resource. That handoff is where accurate translations can become misleading if the context is wrong.
Example from a working store. An editor reviews a French staged description in a management view but public product projections continue to return the previous wording. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Distinguish staged changes from current published representation, check publication state and use the correct API and scope when testing. Write down the source resource, intended locale and Store, then reproduce the result with an explicit API request or browser route. A repeatable observation is more useful than an impression that the page looks different.
Acceptance test. Read the Product Projection that ordinary shoppers receive, not only the editing representation. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
10. Staged versus current product data
commercetools separates staged and current product states, and changes intended for customers require the appropriate publication process. A translation project should preserve what remains true independently of language: product identity, variant relationships, inventory, policy and transaction values. Everything else should be changed intentionally, with the correct owner approving that change.
Example from a working store. A translation was saved correctly but appears only in staged data; the team assumes the language selector is broken. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Follow the product publishing workflow and verify the correct representation is projected under the intended Store and locale. Ask a fluent reader what they believe they are buying and have a catalog specialist confirm the technical facts. Both judgments need to agree before a high-risk message is accepted.
Acceptance test. Compare staged and current versions of the same stable product ID before and after the publication operation. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
11. Product visibility and Store assortment
A localized item does not necessarily belong to every Store or Product Selection. Language availability alone does not authorize sale. Think through the buyer’s path rather than one database field. Someone might find a product through search, save a cart, follow an emailed link or switch language while checking compatibility. The words must still describe the same commercial facts.
Example from a working store. A French route resolves the right product name but the relevant Store cannot sell it because its assortment excludes the item. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Evaluate Store assignment, Product Selections, published state and product availability separately from linguistic coverage. Compare the language-specific display with the stable product and variant IDs. The acceptance test fails if an apparently harmless word change maps to a different resource.
Acceptance test. Request the item under the actual Store context and verify it can legitimately be shown and purchased. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
12. SKU and variant identity
Variant SKU identifiers and product keys connect catalog content to stock, order and fulfillment systems and should not be treated as translatable labels. An ordinary reader does not care which API supplied the label. They care whether an option, warning or restriction is understandable and corresponds to what actually happens next. This is why localized content needs behavioral testing as well as proofreading.
Example from a working store. A translated color name is used as a variant key, making a cart refer to the wrong item when the shopper changes language. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Keep immutable identifiers separate from localized option labels and check option-to-variant mapping in the storefront. Use a normal case and a missing-data case. The second test exposes fallback behavior and makes it possible to decide whether a translated page is truly complete.
Acceptance test. Compare cart line items, SKU, variant ID and quantity across language changes. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
13. Localized enum values
A LocalizedEnumValue can present language-dependent labels while keeping its stable enum key, making it suitable for controlled option or attribute vocabularies. Many multilingual defects look similar: a missing translation, wrong locale projection, unpublished product, unavailable Store assortment or cached response can all produce a misleading screen. Distinguish these causes before changing content.
Example from a working store. A shopper selects the displayed French color, but the cart uses a different internal key because translations were paired incorrectly. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Review each key-label association and test the exact attribute value across catalog, search facet, variant selector and cart. Retest from a fresh browser session or direct URL. Cached state and client navigation often conceal a wrong projection or unsupported localized slug.
Acceptance test. Apply one filter in two languages and confirm it selects the same underlying enum key and items. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
14. Custom fields and localized types
Custom fields may support LocalizedString or localized enum representations when a project’s type definitions explicitly use those field types. A useful review is not a literal comparison of sentences alone. It checks the intention of the message, the conditions behind it and the actual product or operation to which it applies. Clear local phrasing must not introduce a new promise.
Example from a working store. A brand promise stored as a plain String is expected to vary by locale, yet the integration supplies only one value. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Inspect the Custom Field type and its supported field definitions before deciding where translated values will be stored. Make a small controlled change in staging and inspect the exact returned value after publication. This helps separate a translation mistake from a stale resource or unrefreshed build.
Acceptance test. Read the custom field in multiple locales and check that its type and update actions behave as designed. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
15. Product Types determine translatable attributes
Product Type definitions describe attributes and their data structures; a field does not automatically become localizable because its label looks textual. Translation reaches beyond a catalog. Frontend message bundles, search relevance, metadata, emails and error states are separate systems that still contribute to a shopper’s understanding of one transaction.
Example from a working store. An editor translates an attribute in a spreadsheet, but the target field is not configured to store a localized representation. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Plan the data model before importing and identify which attributes are LocalizedString, localized enum, number, Boolean or reference fields. Where numbers or legal conditions appear, compare against the authoritative commerce source. Do not infer a new amount, eligibility or warranty from language alone.
Acceptance test. Inspect the Product Type schema for the representative product and compare it with the translated payload. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
16. Attribute value versus attribute label
A technical attribute value and the label shown to customers may require different translation handling; numeric values still need consistent units. Respect the structure of the data model. Stable keys link services together; language-dependent values help people read those services. Mixing the two creates expensive mistakes that no stylistic edit can repair.
Example from a working store. A jacket’s waterproof rating remains an accurate number, but the translated label describes breathability rather than waterproofness. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Protect the scientific or commercial value and translate the explanation or facet label through an appropriate localized field or UI resource. Keep a concise evidence record containing expected wording, actual wording, product identifier, request context and final user outcome. It gives reviewers an unambiguous way to confirm a fix.
Acceptance test. Check product detail, product comparison and filters for the same attribute code and measured value. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
17. Search APIs and language-sensitive discovery
commercetools provides product search and projection-related APIs with their own supported query and locale behavior; the frontend must request and render results consistently. The customer may never see the raw API value. A frontend chooses which projection to request, which language to display and which action to take on the returned resource. That handoff is where accurate translations can become misleading if the context is wrong.
Example from a working store. A localized product page is correct, yet search suggestions use an old term because the search integration handles language independently. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Identify the exact search endpoint, query configuration and index behavior used by the storefront before applying generic locale advice. Write down the source resource, intended locale and Store, then reproduce the result with an explicit API request or browser route. A repeatable observation is more useful than an impression that the page looks different.
Acceptance test. Search for everyday target-language terms and compare result IDs, filtering and displayed titles. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
18. Facets and filters across languages
Facets must preserve structured field meaning even when their labels and enumerated values are localized for readers. A translation project should preserve what remains true independently of language: product identity, variant relationships, inventory, policy and transaction values. Everything else should be changed intentionally, with the correct owner approving that change.
Example from a working store. A German filter says ‘width’ but queries the product’s height value, creating a plausible yet incorrect list. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Map each displayed label to its real product field, enum key and query, and review unit formatting without altering underlying measurements. Ask a fluent reader what they believe they are buying and have a catalog specialist confirm the technical facts. Both judgments need to agree before a high-risk message is accepted.
Acceptance test. Repeat the same narrowing sequence in two languages and compare product IDs and stable attribute values. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
19. Country and currency are separate from language
Project settings and commerce resources also govern countries, currencies, prices, taxes and shipping independently of language selection. Think through the buyer’s path rather than one database field. Someone might find a product through search, save a cart, follow an emailed link or switch language while checking compatibility. The words must still describe the same commercial facts.
Example from a working store. A merchant changes a product name to French and assumes the price has automatically become suitable for France. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Build a matrix of audience locale, country, currency, price selection, tax and fulfillment context and explain actual differences explicitly. Compare the language-specific display with the stable product and variant IDs. The acceptance test fails if an apparently harmless word change maps to a different resource.
Acceptance test. Change only the locale in a controlled test, then compare currency codes, amounts and eligible delivery options. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
20. Cart projections and line item names
When a Cart belongs to a Store, localized values on its line items may be projected according to the Store’s languages; the original purchased resource remains identifiable. An ordinary reader does not care which API supplied the label. They care whether an option, warning or restriction is understandable and corresponds to what actually happens next. This is why localized content needs behavioral testing as well as proofreading.
Example from a working store. A customer adds a product in English, changes language and sees a new label but fears the product has changed. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Use stable line item and variant references, render localized names from the intended projection and clearly communicate any market-driven availability change. Use a normal case and a missing-data case. The second test exposes fallback behavior and makes it possible to decide whether a translated page is truly complete.
Acceptance test. Inspect product and line-item identifiers as well as translated visible names before and after a locale change. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
21. Checkout and UI translation ownership
Product localization in the Commerce APIs does not automatically translate a React or other custom storefront’s buttons, validation, consent or payment-provider messages. Many multilingual defects look similar: a missing translation, wrong locale projection, unpublished product, unavailable Store assortment or cached response can all produce a misleading screen. Distinguish these causes before changing content.
Example from a working store. A product name and cart item are Spanish but the checkout failure message is untranslated and gives no useful recovery instruction. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Maintain separate interface language resources for the frontend and integrate the active locale into third-party components where supported. Retest from a fresh browser session or direct URL. Cached state and client navigation often conceal a wrong projection or unsupported localized slug.
Acceptance test. Run a successful order and at least one safe failed checkout in each advertised language. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
22. Orders and transactional communication
Order records need accurate product, price and fulfillment data; localized notifications may come from an external messaging service that requires explicit configuration. A useful review is not a literal comparison of sentences alone. It checks the intention of the message, the conditions behind it and the actual product or operation to which it applies. Clear local phrasing must not introduce a new promise.
Example from a working store. An order confirmation email translates the product but drops a shipping restriction that was visible on the checkout page. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Map order data into templates with an explicit language policy and preserve the stored transaction facts, dates and amounts. Make a small controlled change in staging and inspect the exact returned value after publication. This helps separate a translation mistake from a stale resource or unrefreshed build.
Acceptance test. Compare the authorized order with delivered email, invoice, tracking page and customer-support message. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
23. Custom translation data and TMS imports
Translation management integrations need stable resource keys, locale mapping, workflow ownership and careful handling of concurrent updates. Translation reaches beyond a catalog. Frontend message bundles, search relevance, metadata, emails and error states are separate systems that still contribute to a shopper’s understanding of one transaction.
Example from a working store. An external provider imports a LocalizedString map built from an older product version, wiping out a newly corrected description. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Use resource IDs and version-aware updates, review diff reports and require explicit approval for changes to protected facts. Where numbers or legal conditions appear, compare against the authoritative commerce source. Do not infer a new amount, eligibility or warranty from language alone.
Acceptance test. Read back the affected localized fields after import and verify no source-language value was lost. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
24. Optimistic concurrency and version conflicts
commercetools resources use versioned updates to prevent conflicting modifications; translators and integrations must handle rejected concurrent changes safely. Respect the structure of the data model. Stable keys link services together; language-dependent values help people read those services. Mixing the two creates expensive mistakes that no stylistic edit can repair.
Example from a working store. Two editors update different languages of one product and one import fails because it targets an outdated resource version. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Detect the version conflict, retrieve current data, merge approved locale changes and retry through the supported update process. Keep a concise evidence record containing expected wording, actual wording, product identifier, request context and final user outcome. It gives reviewers an unambiguous way to confirm a fix.
Acceptance test. Verify the final resource version contains both intended language values without reverting an unrelated change. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
25. Caching and stale localized responses
Storefront caches, API projection parameters and static site builds can make a corrected translation appear out of date after publication. The customer may never see the raw API value. A frontend chooses which projection to request, which language to display and which action to take on the returned resource. That handoff is where accurate translations can become misleading if the context is wrong.
Example from a working store. A French catalog update is visible in an API test but an older page render persists behind a language-agnostic cache key. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Inspect cache keys, invalidation and deployment outputs for the Store and locale, then confirm the app requests the same projected values. Write down the source resource, intended locale and Store, then reproduce the result with an explicit API request or browser route. A repeatable observation is more useful than an impression that the page looks different.
Acceptance test. Reload the localized URL from a fresh session and compare its response with the underlying current Product Projection. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
26. International SEO, URLs and hreflang
Localized slugs help human-readable addresses, but canonical tags, alternate language links, metadata and sitemap choices belong to the frontend or publishing integration. A translation project should preserve what remains true independently of language: product identity, variant relationships, inventory, policy and transaction values. Everything else should be changed intentionally, with the correct owner approving that change.
Example from a working store. Every language version points canonical to the English product even though its own translated content is intended for discovery. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Define indexable equivalent pages, route translation and localized metadata, while maintaining stable product identity underneath. Ask a fluent reader what they believe they are buying and have a catalog specialist confirm the technical facts. Both judgments need to agree before a high-risk message is accepted.
Acceptance test. Inspect rendered HTML and direct links for each language, including unavailable products and missing translated slugs. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
27. Right-to-left text and accessible interaction
A commerce API supplying localized strings does not guarantee that a storefront can present right-to-left layouts or long translated labels correctly. Think through the buyer’s path rather than one database field. Someone might find a product through search, save a cart, follow an emailed link or switch language while checking compatibility. The words must still describe the same commercial facts.
Example from a working store. A long Arabic variant label overflows its menu and the screen reader announces the default-language name. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Test layout direction, typography, focus order, keyboard activation, input labeling and text expansion using realistic target-language strings. Compare the language-specific display with the stable product and variant IDs. The acceptance test fails if an apparently harmless word change maps to a different resource.
Acceptance test. Complete a product selection and checkout on phone and desktop with accessibility features enabled. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
28. Security of localized product data and API permissions
Different credentials may expose staged, unpublished or published data, and public storefronts should use the minimum approved scopes. An ordinary reader does not care which API supplied the label. They care whether an option, warning or restriction is understandable and corresponds to what actually happens next. This is why localized content needs behavioral testing as well as proofreading.
Example from a working store. An integration used for translation previews accidentally exposes unapproved drafts to anonymous visitors because it queries management data. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Separate editing and public clients, verify OAuth scopes and project contexts, and avoid embedding privileged tokens in a storefront. Use a normal case and a missing-data case. The second test exposes fallback behavior and makes it possible to decide whether a translated page is truly complete.
Acceptance test. Inspect anonymous product queries and confirm that unpublished or restricted catalog data remains inaccessible. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
29. An end-to-end quality assurance matrix
A useful test spans language, Store, product state, SKU, country, currency, search, cart, checkout and customer communication rather than a single translated screenshot. Many multilingual defects look similar: a missing translation, wrong locale projection, unpublished product, unavailable Store assortment or cached response can all produce a misleading screen. Distinguish these causes before changing content.
Example from a working store. A team verifies 10,000 translated titles but misses that most direct localized links redirect to English and the receipt uses outdated copy. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Start with a small representative set, then expand tests by business risk and resource coverage while preserving meaningful sample evidence. Retest from a fresh browser session or direct URL. Cached state and client navigation often conceal a wrong projection or unsupported localized slug.
Acceptance test. Record expected identifiers, language responses, final order facts and owner-approved exceptions for each launch locale. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
30. A phased rollout and maintenance plan
Translations require maintenance when product data, site behavior or supported markets change; launch readiness is an ongoing responsibility. A useful review is not a literal comparison of sentences alone. It checks the intention of the message, the conditions behind it and the actual product or operation to which it applies. Clear local phrasing must not introduce a new promise.
Example from a working store. A new product variant arrives after the French rollout and appears with default-language option labels even though existing items remain complete. The surface symptom can look like a translation error, but it may be caused by the data model, API request, published representation or frontend rendering. Identify the owning layer before editing words.
Practical resolution. Include language review in catalog publication, product type changes, frontend releases and customer support escalation. Make a small controlled change in staging and inspect the exact returned value after publication. This helps separate a translation mistake from a stale resource or unrefreshed build.
Acceptance test. Retest one ordinary and one difficult product journey after each relevant release and track missing translations until resolved. Have a second person verify the customer-facing meaning and explain which data remain invariant across the comparison. If they cannot follow the same product or transaction through the change, investigate before release.
Twelve practical troubleshooting situations
Situation 1: French name exists but the product page shows English
Read the raw localized fields, the requested localeProjection and any Store-specific language projection. Confirm whether the missing French key or the frontend’s preferred language produces the fallback. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 2: Translated slug resolves to a different product
Test uniqueness and route mapping in the Project, then check the frontend’s resolver and previous redirects. Stable product identity must win over a convenient human-readable path. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 3: A new description is visible only to editors
Compare staged and current data and confirm publication state. Use the Product Projection normally available to anonymous customers as the release check. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 4: Localized filter labels describe the wrong property
Inspect the attribute definition or localized enum key, then compare the search query and returned stable values. Repair the key-label relationship before changing marketing copy. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 5: The same item has different monetary claims across locales
Distinguish language from country, Store, currency and price selection. A language switch should not merely relabel the same number as another currency. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 6: Variant selection changes after switching language
Keep SKU and variant identifiers in application state. The displayed label is a translation, not a reliable durable identifier for a purchased item. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 7: Some product text falls back unexpectedly
Inspect Project language order, LocalizedString coverage and locale projection behavior. Decide which missing values are safe and which must block a launch. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 8: A cart line item is displayed in the wrong language
Check Store binding and projected localized line-item content, then compare the underlying item ID and variant to the intended language context. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 9: The store search does not recognize a local term
Inspect the actual search API, query language and indexed field behavior. Work from a known available product rather than inventing a separate localized duplicate. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 10: An API integration drops another editor’s translation
Look for resource version conflicts and stale payloads. Read current data, merge approved changes and retry through supported versioned update actions. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 11: French metadata appears on English pages
Trace locale through server rendering, route context and head tags. Check canonical and alternate URLs against actual corresponding products. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Situation 12: A translated cart leads to an English payment error
Identify the frontend message source and payment provider language handling. A LocalizedString catalog value does not localize external checkout components. Make the investigation concrete with a Project, Store, requested locale, product reference and actual customer action. A reviewer should be able to distinguish a wrong translation from a valid commerce restriction.
After correcting the real cause, compare the original failure, the default language and the intended new language. Confirm that the corrected display still points to the same product and does not change the amount, promise or availability without authorization.
Worked example: a multilingual bicycle helmet storefront
A business sells one helmet in sizes small, medium and large. Its Project supports English, German and French, while different Stores serve distinct assortments. Begin with a stable product key, Product Type and variant SKUs. Enter appropriate LocalizedString values for the name and description, and design language-specific slugs that point to the same underlying item. For a safety-related product, retain the actual certification, fit advice, material facts and included accessories. Do not substitute a local marketing claim for the real product specification. Review a localized color label as an enum value only if the data model supports the correct stable key.
Next request the product through the real storefront’s Store and locale projection. Compare the exact API response to the rendered title, variant selector, navigation and product route. If a French field is intentionally missing, inspect the documented fallback and decide whether the customer still receives a comprehensible product warning. Test product publication state and the Store’s assortment. A translated name must not make an unavailable helmet purchasable. Search for the product using an ordinary target-language term, then compare the returned ID and visible facets against the original item.
Choose the medium variant, add it to a cart and switch language. Confirm the cart’s line item still contains the same SKU and quantity and that the visible name corresponds to the selected locale. Use a controlled eligible country and currency for checkout, then run an intentional invalid-address case. Inspect the real order record, receipt and support links. Finally open the direct localized slug on a new device and check metadata, keyboard use and long translated labels. The launch is credible when the language journey is complete and the purchased helmet remains identical.
Four-week learning and release plan
Week one: understand the model
Inventory Project languages, Stores, Product Types, LocalizedString fields, localized enum labels and protected technical identifiers. Map country, currency and price context separately. Choose two variants of one product for a repeatable test.
Close the week by storing an example with the actual resource and locale, the expected response and the observed customer result. A failed case should have a named owner and a repeatable next test; a passing case should remain in the regression collection.
Week two: create and publish controlled translations
Enter approved names, descriptions, category content and localized slugs. Compare staged with current product data and publish through the appropriate workflow. Test localeProjection and storeProjection and document observed missing-field fallback.
Close the week by storing an example with the actual resource and locale, the expected response and the observed customer result. A failed case should have a named owner and a repeatable next test; a passing case should remain in the regression collection.
Week three: complete customer journeys
Review search APIs and filter meanings, localized routes, cart projections, variant stability, checkout failure messages and transactional communications. Use real responses rather than relying on a single frontend screenshot.
Close the week by storing an example with the actual resource and locale, the expected response and the observed customer result. A failed case should have a named owner and a repeatable next test; a passing case should remain in the regression collection.
Week four: audit release and maintain it
Inspect direct URLs, meta information, hreflang, accessibility, cache behavior, role permissions and translation imports. Record regression tests for every future product, attribute and frontend release.
Close the week by storing an example with the actual resource and locale, the expected response and the observed customer result. A failed case should have a named owner and a repeatable next test; a passing case should remain in the regression collection.
Frequently asked questions
Does commercetools automatically translate a product when a language is added?
No. Adding a supported language and supplying language-keyed values are separate actions. A Product Projection can use fallback when the requested localized value is absent.
What is the difference between localeProjection and storeProjection?
localeProjection explicitly names locales for a Product Projection, while storeProjection uses a Store context and its configured languages. Check the endpoint’s documented priority and the actual request.
Will a LocalizedString change the product ID or SKU?
No. Language-dependent display values can be attached to one product. Stable identifiers and variant references should remain independent of translation.
Why does a translated field not appear publicly?
It might be staged, unpublished, absent for the projected locale, outside the Store context or lost in frontend presentation or caching.
Are localized slugs enough for international SEO?
No. The storefront still needs working routes, equivalent page relationships, appropriate metadata, canonicals, alternate links and searchable localized content.
Does choosing French also select EUR?
Not by itself. Country, currency, price selection and Store policies remain separately configured.
Can attribute filters be multilingual?
Yes where the data model and search integration support localized labels or enumerated values. They must still map to the same underlying property or key.
What is a sensible release test?
Verify a supported product through search, a direct localized URL, variants, cart, checkout, a safe failure and post-purchase communication, comparing the stable underlying transaction.
Official documentation and connected education
commercetools Project languages and settings; commercetools Product Projections, localeProjection and storeProjection; commercetools Custom Types and localized enum fields; commercetools Project products on locales. Check individual endpoint documentation for the exact API implementation and the current Project configuration.
Continue learning at Master Art of Translation | The Complete System for Moving Meaning Between Languages and Translate Like a Pro | Series Index.