How do you translate a Sylius storefront so that product names, taxons, options, order messages and checkout appear in the intended language without confusing languages with markets? Sylius is a Symfony-based commerce framework, and its multilingual design distinguishes locales, channels, dynamic catalog content and interface messages. A reliable translation plan must keep those layers connected while leaving prices, inventory and payment logic governed by the actual store configuration.
People researching Sylius product translation, Sylius locales and channels, Symfony translation files, storefront internationalization, taxon translations, localized product options, multilingual checkout and Sylius SEO often face two kinds of advice: administrative instructions for merchant content and development instructions for interface strings. Both are relevant, but neither covers the entire purchasing journey alone. This guide turns that distinction into practical, testable steps for international ecommerce teams.
Begin by choosing an active sales channel and two supported locales. Translate product, taxon and option content where the installed version makes those fields available; handle static interface strings through the appropriate Symfony and Sylius translation setup; then verify storefront routes, product selection, checkout, payments, notifications and SEO. Treat channel currency, availability and shipping eligibility as commercial facts, not as phrases a translator may rewrite. Publish the language only when a complete customer journey is understandable and accurate.
Quick answer: internationalizing a Sylius storefront
Choose a channel and locales explicitly, translate catalog content separately from static UI messages, and keep commercial settings in their own scope. Start with a product that has options and variants, a taxon route, a permitted delivery address and a complete order. Inspect the visible language at every point, including an invalid form state and the email after checkout. The first aim is not maximum translated strings; it is one honest end-to-end customer journey that survives switching languages.
What makes Sylius localization distinctive
Sylius combines a Symfony application, flexible merchant data and an extensible sales-channel model. Official Sylius Academy training explains locales in common URL patterns, dynamic versus static translations and default-language fallback. A customized or headless storefront may implement language selection and URL rules differently, so these are concepts to verify against the actual application rather than claims that every site has an identical administration screen.
Detailed lessons for merchants, editors, translators and developers
1. Understand the Sylius framework boundary
Sylius is a highly configurable ecommerce framework rather than a fixed set of screenshots. Teams can override storefront templates, add bundles and build a headless presentation, which changes where readers encounter translatable strings. The first useful question is where this value comes from, not what synonym might sound better. Commerce interfaces assemble text from several systems and a change made in the wrong one will not survive the next render.
A production shop may use a custom React frontend while its Sylius administration remains in a separate interface and language. Inventory the actual deployed frontend, Sylius backend and extensions; do not assume that translating the administration language changes every storefront component. A reviewer should be able to repeat the exact action and see the same result. That matters more than a translation completion percentage.
Trace one visible product title and one checkout label to their owning data or translation catalog. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
2. Separate locale from channel
A locale defines linguistic and regional presentation; a sales channel defines a commercial scope and can control supported locales, currency and sales conditions. A channel is not merely another word for language. The visible phrase and the purchase record answer different questions. A sentence helps the customer decide; an identifier, channel rule or checkout state decides what the system actually processes.
One store sells to an English-speaking UK audience and a French-speaking audience through different commercial channels, but the language and currency requirements do not line up one-to-one. Build a channel-by-locale matrix showing permitted combinations rather than equating French with France or English with US dollars. Treat disagreement between the two as a defect requiring investigation, not as an invitation to make the copy sound more persuasive.
Visit each permitted combination and confirm the displayed language, currency, catalog and selling rules. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
3. Use locale codes consistently
Sylius documentation and training illustrate locales such as en_US, pl_PL and de_DE. Application routes and internal identifiers may use locale codes whose exact syntax differs from browser language tags. Imagine a reader visiting without any knowledge of the source language. They must be able to move from discovery to selection and payment without relying on implied English meanings.
An editor pastes an arbitrary locale string into a storefront route and then assumes the missing content must be a translation failure. Take supported locale identifiers from the installed Sylius configuration and map them deliberately to UI labels and external metadata. Look for a broken path, a hidden assumption or a missing refusal message as carefully as for a mistranslated noun.
Test locale selection, direct URLs and browser language behavior for an allowed and a disallowed code. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
4. Plan fallback behavior explicitly
The documented localization model can fall back to default-language content when translations are absent. Fallback is useful for availability but can conceal incomplete work from customers. Some errors are linguistic, while others are introduced by routing, data configuration or template rendering. Those categories deserve separate diagnosis even when they produce the same visible symptom.
A Polish storefront shows the product heading in Polish but a long English warning because the second field has no approved translation. Define when a source-language fallback is acceptable and when the product must be withheld until critical information is translated. Keep a reproducible record that names the customer locale, commercial channel, page and expected outcome.
Remove a harmless test translation in staging and record what renders, what language selector shows and what SEO metadata says. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
5. Distinguish static from dynamic text
Static storefront messages often come through the Symfony translation layer, while product and catalog descriptions are dynamic merchant-managed translations. A translation file does not automatically translate database content. A useful localization decision preserves what is true and improves what is understandable. Translation should never invent a new shipping offer, price, product identity or legal entitlement.
A developer updates a ‘Buy now’ string in a catalog but the visible product name continues to come from Sylius product data. Classify the string by ownership before editing: interface, product, taxon, option, marketing content or external integration. Check a normal state and an edge case, because the boundary between language and commerce is often visible only when something fails.
Check one representative example from each class and note how it is changed and released. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
6. Choose a manageable pilot catalog
A pilot should contain product structures that challenge translation: simple products, options, variants, category navigation and one special condition. A single perfect hero page hides most risks. The next screen is part of the meaning of the current screen. A clear button cannot compensate for the wrong result after it is pressed.
A brand translates the main product hero but overlooks options, stock-driven variants and checkout summaries because it never tested them. Pick a small catalog with both simple and configurable items, and include an item that cannot ship to every market. Verify a complete task in both languages with the same commercial object as the reference.
Document the product codes, variant codes, localized labels, prices and expected purchase outcomes before translating. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
7. Keep product codes and variant identities stable
Sylius products and variants carry identifiers used by inventory and other business systems. Display names can change by locale without changing those commercial identities. Source text can be grammatically good and still mislead in another market. Readers need culturally clear terminology while the commercial scope remains explicit.
A translated product name looks like a different listing, prompting an editor to duplicate a variant instead of supplying a translation. Track the technical product and variant codes as protected identifiers and translate only the fields approved for human-facing text. Escalate unresolved business conditions rather than filling them with plausible words.
Purchase the same configured item in two locales and reconcile the saved variant code against fulfillment data. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
8. Translate the complete product story
A clear target-language product page must preserve purpose, composition, size, compatibility, warranty, exclusions and any safety information. Product localization is not just a title field. International storefronts must serve people, not just routes. Test keyboard access, narrow screens and unfamiliar customer paths when judging whether a translation is ready.
An outdoor power supply is advertised fluently in German but the voltage and adapter requirements remain unclear. Create a translation review sheet that separates promotional language from factual specifications and required warnings. Record what remains confusing after the language change and connect that observation to a named correction owner.
Ask a target-language reviewer to explain what is included, what is incompatible and what customer action is required. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
9. Product options need coherent terminology
Options and option values can appear in selectors, variant names, filters, baskets and order messages. Inconsistent terms make an otherwise correct product look unreliable. The first useful question is where this value comes from, not what synonym might sound better. Commerce interfaces assemble text from several systems and a change made in the wrong one will not survive the next render.
The same finish is called ‘matte’ on the detail page and a different term in the order summary. Develop one approved term per option and value, then map where Sylius or custom frontend code renders that term. A reviewer should be able to repeat the exact action and see the same result. That matters more than a translation completion percentage.
Compare a selected variant across the product page, cart, checkout and confirmation with the correct underlying code. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
10. Taxons are customer navigation
Sylius taxons provide catalog organization, and their translated labels and descriptions can affect menus, breadcrumbs and navigation. A local reader should not have to know the source language to find a category. The visible phrase and the purchase record answer different questions. A sentence helps the customer decide; an identifier, channel rule or checkout state decides what the system actually processes.
A French customer understands a shoe listing but cannot find it through the category menu because all taxons are English. Review the taxon hierarchy and identify which names, descriptions and paths need language-specific text. Treat disagreement between the two as a defect requiring investigation, not as an invitation to make the copy sound more persuasive.
Browse from a localized root category to the intended product and inspect breadcrumbs and filter names. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
11. Menus, navigation and custom pages
Many international stores combine Sylius catalog resources with custom CMS pages or frontend-managed menus. Those components have separate editors and translation workflows. Imagine a reader visiting without any knowledge of the source language. They must be able to move from discovery to selection and payment without relying on implied English meanings.
An accurate translated product is linked from a navigation menu that still points to the default locale. Document the source of navigation links, static landing pages and editorial content; review their target-language routes. Look for a broken path, a hidden assumption or a missing refusal message as carefully as for a mistranslated noun.
Use a clean browser to navigate through the entire local path without pasting a product link directly. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
12. Symfony translator domains
Symfony translations organize interface messages into catalogs and domains, while bundles and theme overrides may introduce their own messages. The catalog key should remain technical identity, not be rewritten as prose. Some errors are linguistic, while others are introduced by routing, data configuration or template rendering. Those categories deserve separate diagnosis even when they produce the same visible symptom.
A developer translates the displayed value but accidentally renames its message key, causing fallback in a template. Preserve stable keys, placeholders and expected pluralization semantics; route overrides through the project’s documented translation mechanism. Keep a reproducible record that names the customer locale, commercial channel, page and expected outcome.
Trigger normal, empty, validation and error states to verify the correct phrase and runtime substitutions. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
13. Placeholders and variable substitution
A message with quantity, product name, amount or date is partly generated at runtime. A good translation preserves every required placeholder and allows the target language’s natural word order. A useful localization decision preserves what is true and improves what is understandable. Translation should never invent a new shipping offer, price, product identity or legal entitlement.
An order notice contains a missing product name because a translator removed a variable token from a locale file. Make placeholders visible in the translator’s brief and validate required tokens during build or review. Check a normal state and an edge case, because the boundary between language and commerce is often visible only when something fails.
Render the message with long names, zero and plural quantities, and different dates to catch grammatical and layout defects. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
14. Singular, plural and grammatical agreement
Different languages may require more than one plural form, and a phrase that reads well with one item may fail with five. Translation must respect the formatting capabilities of the frontend. The next screen is part of the meaning of the current screen. A clear button cannot compensate for the wrong result after it is pressed.
A cart message shows the same singular noun for one and many products, leaving the sentence unnatural. Use the project’s supported pluralization mechanism rather than manual string concatenation that assumes English grammar. Verify a complete task in both languages with the same commercial object as the reference.
Exercise the smallest and largest likely quantities, including zero where that form appears. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
15. Language switch and product continuity
Changing locale should feel like continuing the same shopping task, not entering an unrelated store. Where translations are unavailable, the fallback destination should be predictable. Source text can be grammatically good and still mislead in another market. Readers need culturally clear terminology while the commercial scope remains explicit.
A buyer selects a jacket in Polish, switches language and returns to the storefront homepage with the chosen variant forgotten. Define the expected destination for the product, category and cart under each locale and channel combination. Escalate unresolved business conditions rather than filling them with plausible words.
Switch in both directions on important routes and check the product identity and selected options. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
16. Channel currency and pricing
Currency belongs to market configuration, not to a translation file. A language may be spoken across many countries whose prices, tax structures and fulfillment rules differ. International storefronts must serve people, not just routes. Test keyboard access, narrow screens and unfamiliar customer paths when judging whether a translation is ready.
A French-language label displays ‘EUR’ while the checkout charges in an actual channel set to another currency. Confirm the channel’s currency and pricing scope with the commerce owner before localizing any financial explanations. Record what remains confusing after the language change and connect that observation to a named correction owner.
Compare listing price, tax, cart total, checkout amount and payment receipt under the same selected channel. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
17. Inventory availability and variations
Availability may differ by channel, warehouse, variant or custom fulfillment logic. Translation must not promise that a variant is purchasable where it is unavailable. The first useful question is where this value comes from, not what synonym might sound better. Commerce interfaces assemble text from several systems and a change made in the wrong one will not survive the next render.
A translated page says an item is ready for dispatch but the configured channel has no eligible stock. Review the visible stock and delivery claims alongside the deployed availability rules, including out-of-stock messages. A reviewer should be able to repeat the exact action and see the same result. That matters more than a translation completion percentage.
Test one available and one unavailable variant in each relevant channel without editing inventory records as a language fix. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
18. Shipping and address formats
Address entry, shipping-method labels and delivery rules are highly contextual. Localizing a postal address form does not automatically create a shipping service for that country. The visible phrase and the purchase record answer different questions. A sentence helps the customer decide; an identifier, channel rule or checkout state decides what the system actually processes.
A German checkout is translated, but it offers a carrier that cannot deliver to the entered destination. Separate text review from shipping-zone configuration; show a truthful unavailable-delivery message where necessary. Treat disagreement between the two as a defect requiring investigation, not as an invitation to make the copy sound more persuasive.
Test valid and invalid addresses, changing a region and reading shipping explanations on mobile. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
19. Checkout states and required consents
Checkout may include custom forms, plugins, guest accounts and terms. Text must identify what action the customer is authorizing and what happens afterward. Imagine a reader visiting without any knowledge of the source language. They must be able to move from discovery to selection and payment without relying on implied English meanings.
A customer agrees to a privacy statement presented only in the source language while shipping fields are otherwise translated. Review every pane in the installed checkout, including unchecked consent, required fields and failure messages. Look for a broken path, a hidden assumption or a missing refusal message as carefully as for a mistranslated noun.
Complete a guest order and an account order, deliberately causing at least one validation error. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
20. Payment flows outside the storefront
Hosted payment pages or embedded elements may have their own supported languages. The platform’s locale does not necessarily control every third-party payment screen. Some errors are linguistic, while others are introduced by routing, data configuration or template rendering. Those categories deserve separate diagnosis even when they produce the same visible symptom.
A buyer leaves a localized checkout, encounters English text at the payment provider and returns to a default-language success page. Review provider locale parameters, supported language lists and callback routes with the payment integrator. Keep a reproducible record that names the customer locale, commercial channel, page and expected outcome.
Test an authorized payment, a canceled attempt and a failed attempt, reconciling states to the same order. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
21. Email and customer-notification language
Order confirmations, shipping notifications and refund messages can use templates, bundles or external mail tools. Locale selection must be passed to the place that renders each message. A useful localization decision preserves what is true and improves what is understandable. Translation should never invent a new shipping offer, price, product identity or legal entitlement.
A Polish-language purchase generates a French order email because a background worker loses the customer locale. Capture message language at the appropriate point in the application, test rendering with stored order data, and preserve financial facts. Check a normal state and an edge case, because the boundary between language and commerce is often visible only when something fails.
Verify subject, body, variable values, support links and attachments in a real test inbox. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
22. SEO aliases and canonical page identity
A locale-aware storefront should expose stable, understandable paths and search metadata for equivalent pages. The exact URL implementation depends on the project. The next screen is part of the meaning of the current screen. A clear button cannot compensate for the wrong result after it is pressed.
The translated product is reachable but its canonical element selects a page in another locale, undermining language discovery. Review localized title and description, canonical URL, alternate-language links and redirects in rendered HTML. Verify a complete task in both languages with the same commercial object as the reference.
Crawl sample product and taxon paths from each locale and check for dead ends or incorrect cross-language canonicalization. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
23. Search indexes and language-specific filters
Search technology may come from Sylius integrations or a custom storefront, so translated database fields may not automatically become searchable in every locale. Source text can be grammatically good and still mislead in another market. Readers need culturally clear terminology while the commercial scope remains explicit.
A French product name displays correctly on its page but cannot be found through search because only default-language fields were indexed. Determine how the deployed search service indexes translations, terms and option values; test queries in the customer’s wording. Escalate unresolved business conditions rather than filling them with plausible words.
Reindex in a staging environment and compare search results, facets and category links by locale. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
24. Editorial change and review status
A catalog changes after translation: products acquire new ingredients, warranty terms or promotions. The localization team needs a way to know when existing translations are outdated. International storefronts must serve people, not just routes. Test keyboard access, narrow screens and unfamiliar customer paths when judging whether a translation is ready.
A source description revises a technical limit, but the German description still gives the old number. Log source changes, prioritize safety and commerce-affecting edits, and assign reviewers to each active language. Record what remains confusing after the language change and connect that observation to a named correction owner.
Make a controlled revision in staging and follow it through the target-language review and release path. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
25. Accessibility and localization in layout
Longer target-language expressions, accented letters and right-to-left scripts can change spacing and focus order. Accurate words are ineffective when a buyer cannot operate controls. The first useful question is where this value comes from, not what synonym might sound better. Commerce interfaces assemble text from several systems and a change made in the wrong one will not survive the next render.
A translated checkout button wraps behind an overlay on a narrow phone screen. Test responsive components, keyboard focus, screen-reader labels and any graphical text alongside linguistic accuracy. A reviewer should be able to repeat the exact action and see the same result. That matters more than a translation completion percentage.
Verify a real journey using keyboard-only navigation and a narrow viewport, not only a desktop screenshot. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
26. Extensions and version upgrades
Sylius projects commonly include plugins, theme customizations and developer-maintained overrides. Upgrades can add keys, templates and content fields that bypass an earlier translation review. The visible phrase and the purchase record answer different questions. A sentence helps the customer decide; an identifier, channel rule or checkout state decides what the system actually processes.
An updated payment plugin introduces a new eligibility warning rendered in the default language. Maintain an extension inventory and include multilingual regression in upgrade acceptance, especially for payments and checkout. Treat disagreement between the two as a defect requiring investigation, not as an invitation to make the copy sound more persuasive.
Replay representative orders and search all visible language strings after each relevant deployment. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
27. Release decisions and ownership
A launch checklist should distinguish translation quality, system behavior, legal approval, business configuration and search visibility. No one person can safely approve all of these merely by reading copy. Imagine a reader visiting without any knowledge of the source language. They must be able to move from discovery to selection and payment without relying on implied English meanings.
A language edition has 98 percent translated strings but the last two percent contains an untranslated cancellation term and a broken payment error. Assign named owners to editorial, legal, commerce and technical checks, and make critical defects block release. Look for a broken path, a hidden assumption or a missing refusal message as carefully as for a mistranslated noun.
Use documented pass or fail examples so each newly translated locale has an understandable standard. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
28. Continuous improvement from real inquiries
Customers reveal gaps that automated checks may not identify: misleading size language, unexplained payment rules or inconsistent returns wording. Treat support evidence as a source of improvements. Some errors are linguistic, while others are introduced by routing, data configuration or template rendering. Those categories deserve separate diagnosis even when they produce the same visible symptom.
Repeated questions about ‘free returns’ may show that the localized policy overstates the actual conditions. Review support cases by language and stage of the customer journey, correct misleading copy, and extend regression coverage. Keep a reproducible record that names the customer locale, commercial channel, page and expected outcome.
Measure whether the exact question recurs after correction instead of treating a revised sentence as sufficient proof. When reviewing, capture the locale, channel, URL, selected variation and rendered message. Link the observation to the appropriate technical or business owner; a translated sentence is complete only when the resulting action is also correct.
Practical situations: diagnosis before translation
These situations illustrate why a multilingual release needs more than proofreading. The point of each case is to identify the true system boundary and confirm an outcome customers can rely upon.
Situation 1: French product name but English variant values
Dynamic product translations were supplied, but option values follow another content or display path. A localization reviewer should reproduce the symptom first, then identify whether the owner is Sylius data, a Symfony translation catalog, a frontend component or market configuration. Fixes made without identifying the owner tend to recur.
Inspect the option translation, variant rendering and custom template; verify selected codes remain stable. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 2: Locale route yields a blank or 404 page
The displayed locale code or route may not match supported configuration, or the equivalent content is missing. Retest as a new visitor and as a returning customer. Compare the rendered text with the product and order records rather than trusting that the repaired screen looks convincing.
Test an allowed direct route and the language-switch path before changing translation text. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 3: A Polish taxon leads to an English category
The menu text and target resource are managed separately and may be out of sync. Use one known-good product and a controlled channel to isolate the issue. Then check at least one additional locale so the correction does not create a new regression elsewhere.
Inspect the actual navigation destination, taxon translation and route generation under the selected channel. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 4: Storefront copy conflicts with channel stock
A translated message promises delivery even where the channel has no eligible variant. Release only after the observed result answers the customer’s real question and the system still performs the correct commerce action. Preserve a short before-and-after example for future upgrades.
Check availability data and correct the business promise with the responsible merchandiser. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 5: Checkout changes currency after language selection
Changing locale accidentally switches channel or the frontend assumes language implies market. A localization reviewer should reproduce the symptom first, then identify whether the owner is Sylius data, a Symfony translation catalog, a frontend component or market configuration. Fixes made without identifying the owner tend to recur.
Separate language selection from channel selection and compare totals before and after the change. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 6: A shipping error cannot be understood
A locale-specific shipping validation message is untranslated or suppressed by a custom form. Retest as a new visitor and as a returning customer. Compare the rendered text with the product and order records rather than trusting that the repaired screen looks convincing.
Reproduce the unsupported destination, locate the owning bundle string and retest the message. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 7: Confirmation email comes in another language
The order processing or mail integration does not retain the customer’s intended locale. Use one known-good product and a controlled channel to isolate the issue. Then check at least one additional locale so the correction does not create a new regression elsewhere.
Trace the locale from checkout to message rendering and verify a real received copy. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 8: Wrong plural on cart quantity
The template concatenates translated pieces or ignores locale-specific pluralization rules. Release only after the observed result answers the customer’s real question and the system still performs the correct commerce action. Preserve a short before-and-after example for future upgrades.
Replace string concatenation with supported message plural forms and test zero, one and several. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 9: Payment cancellation returns to homepage
The provider callback has no locale context, making the post-payment path confusing. A localization reviewer should reproduce the symptom first, then identify whether the owner is Sylius data, a Symfony translation catalog, a frontend component or market configuration. Fixes made without identifying the owner tend to recur.
Test return routes for successful, canceled and failed payment states without changing the underlying order. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 10: Translated slug redirects to a different product
The URL mapping associates a language alias with the wrong identity. Retest as a new visitor and as a returning customer. Compare the rendered text with the product and order records rather than trusting that the repaired screen looks convincing.
Compare product codes and route rules, then test canonical and alternate language URLs. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 11: Search ignores translated product title
The search index is keyed to the default-language field or lacks locale filters. Use one known-good product and a controlled channel to isolate the issue. Then check at least one additional locale so the correction does not create a new regression elsewhere.
Inspect index settings, rebuild a test index and verify results using natural target-language queries. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 12: Target description hides warranty exclusion
The localized marketing text has been shortened in a way that alters a commercial promise. Release only after the observed result answers the customer’s real question and the system still performs the correct commerce action. Preserve a short before-and-after example for future upgrades.
Compare conditions clause by clause and escalate legal wording to an approved reviewer. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 13: A long German button breaks layout
The translation is linguistically accurate but the UI was designed around short English labels. A localization reviewer should reproduce the symptom first, then identify whether the owner is Sylius data, a Symfony translation catalog, a frontend component or market configuration. Fixes made without identifying the owner tend to recur.
Test wrapping, responsive spacing and accessible focus behavior instead of replacing the message with an ambiguous abbreviation. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 14: A plugin update introduces raw translation keys
An added template uses a key not present in the released locale catalog. Retest as a new visitor and as a returning customer. Compare the rendered text with the product and order records rather than trusting that the repaired screen looks convincing.
Check the extension version, translation domain and build artifacts, then run checkout regression. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 15: Product photos contain source-language text
An instruction graphic still uses the default language even though the product description was translated. Use one known-good product and a controlled channel to isolate the issue. Then check at least one additional locale so the correction does not create a new regression elsewhere.
Produce or link accessible target-language instructions without altering the actual product specifications. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Situation 16: Language switch changes the chosen size
A locale switch rebuilds page state and loses the selected variant. Release only after the observed result answers the customer’s real question and the system still performs the correct commerce action. Preserve a short before-and-after example for future upgrades.
Test state persistence and confirm the same variant code before purchase. Keep both the buyer-visible outcome and the commercial system result in the acceptance record. If they disagree, the language edition is not ready for that task.
Worked example: selling one configurable backpack in two locales
Imagine a backpack offered in English and Polish, with two sizes and two colors. There is one underlying product and four combinations. First record the product code, variant codes, base specifications, shipping restrictions and the channels in which the item is available. The translated product title and description help customers understand the backpack. They must not create new commercial identities or imply that a different warranty is included. Translate the option names and values through the installed Sylius setup, and check how those values appear in selectors, cart rows and confirmation messages.
Now browse the Polish taxon hierarchy instead of opening a saved direct link. Find the backpack through a target-language search, select one size and color, and add it to the basket. Compare the saved variant code with the equivalent English selection. Deliberately enter an unsupported destination address and read the resulting shipping message. Enter a valid address and proceed. Compare displayed price, currency, tax, shipping and final amount to the actual channel and checkout records. A polished Polish description is not proof of a correct Polish purchase if channel rules silently change.
Continue through a test payment method and capture success, cancellation and error states. Read the resulting email, support link and return-policy wording. Switch locale at a product page and cart, and observe whether the same selection is maintained or an explicit fallback is presented. Finally inspect rendered canonical and alternate language URLs. Release when an independent Polish reader can complete the journey and a commerce reviewer confirms that the same product and expected market conditions were processed.
Four-week implementation and learning plan
In week one, map channels, enabled locales, product and taxon structure, translator permissions and frontend architecture. Build a written matrix of channel-locale combinations and select a small pilot. Verify one product ID and variation code across both languages. Decide which default-language fallback behavior is safe for customer-facing content.
In week two, translate product, option and taxon content and the interface messages needed for a real shopping journey. Review placeholders and plural forms. Walk from localized category navigation through search and product configuration. Ask a native or expert target-language reader to inspect product facts and marketing claims separately.
In week three, test valid and invalid addresses, checkout fields, consent, coupons, payment redirects, email subjects and order summaries. Compare the transaction record with the text shown to the customer. Review channel currency, price and delivery claims with a merchant owner, because translation does not authorize altering those terms.
In week four, test search indexing, responsive layout, accessibility, SEO routes and metadata, and missing-translation fallback. Add multilingual regression cases to the project’s ordinary test suite. Publish the pilot only after business, content and technical owners have signed off their respective conditions, then expand to additional products in measured groups.
Frequently asked questions
Does adding a locale translate every Sylius product automatically? No. Supported locales make language versions possible, but teams must supply and review the content, and custom fields or storefronts may need their own translation handling.
Are a channel and a locale interchangeable? No. Language describes presentation; a channel is a commercial scope. A channel can support multiple locales and may determine price, availability and fulfillment behavior.
Where do button translations live? Many static interface messages are managed using Symfony translation catalogs or application-specific overrides, while product content is usually managed as translatable commerce data.
Why does my translated item still show English? Examine missing translations, fallback settings, custom templates, caches and the locale selected on the request before assuming the translation has been lost.
What is the strongest launch test? Buy a configurable item through a fully localized path, including an error state, and reconcile the saved order with the confirmation email and channel rules.
Official resources and related learning
Sylius Documentation; Sylius Academy: Translations Overview; Sylius: Basic Configuration. Documentation and implementation may differ across Sylius versions, frontend stacks and extensions.
Continue with Master Art of Translation | The Complete System for Moving Meaning Between Languages and the Translate Like a Pro | Series Index for adjacent professional localization topics.