How can you translate a Saleor ecommerce storefront without mixing up catalog translations, language-specific URLs, market channels and the words owned by a separate frontend? Saleor is a GraphQL-centered commerce platform. Product names, category labels, attributes and translated slugs can be handled through its data model and translation API, but storefront buttons, editorial sections and checkout interface text may belong to a different application layer. Professional localization begins by distinguishing those owners.
People searching for Saleor product translation, Saleor GraphQL languageCode, productTranslate mutations, translated product slugs, Saleor Dashboard translations, international storefront routing, channel currencies, multilingual SEO and checkout localization need a complete answer, not just a translated product name. A storefront can show flawless translated catalog content while still using the wrong channel, broken URL, untranslated validation message or inconsistent purchase conditions. This guide explains how to verify the full journey.
First choose the intended language and sales channel independently. Translate the catalog fields through Saleor’s supported translation mechanisms, set any language-specific slug strategy deliberately, provide frontend and editorial copy through their actual owners, then verify product routes, search, navigation, cart, checkout, payments, order notices and metadata. Confirm every commercial condition against the selected channel. A useful multilingual release is a complete experience whose language makes the actual transaction understandable.
Quick answer: translate Saleor by content owner, language and channel
A good Saleor localization starts with three inventories. First identify what Saleor itself stores as translatable catalog data. Second identify what the storefront or CMS owns as interface and editorial copy. Third identify which channel controls price, availability, tax and delivery. Provide translations in the relevant layer, not in a guessed substitute. A pilot should include one product with variants, category navigation, two locales, at least one market channel, a deliberately invalid checkout and a completed test order. Review localized SEO and route behavior after the data and purchasing journey agree.
What is distinctive about Saleor translation?
Saleor is GraphQL-centric and supports explicit translation operations for products, categories, variants and related catalog resources. Its Dashboard provides translation editing, while storefronts such as the open-source Paper reference implementation separate catalog text, editorial content and frontend functional strings. Product and category translated slugs are version-dependent and require matching frontend route support. Channels, meanwhile, define commercial behavior such as currencies, prices and shipping availability rather than a reader’s language. A clear implementation respects these divisions instead of offering a single translation setting as a cure-all.
In-depth lessons: building a reliable international Saleor storefront
1. Know what Saleor translates and what the storefront owns
Saleor is a commerce backend exposed through GraphQL. It supplies translated catalog data, while a custom or reference storefront must decide how to display messages, route URLs and localize editorial content. Start by asking which part of the architecture owns the value. A visible product page may combine a GraphQL response, a CMS section and a frontend message; editing one of them does not necessarily change the others.
A developer translates a product name in Saleor Dashboard but the React storefront’s ‘Add to bag’ button stays English. Inventory GraphQL catalog fields, frontend message files, CMS content and integration messages before assigning translation work. For release evidence, record the product identity, requested language, channel, URL and the value shown to the reader.
Trace at least one visible value from each layer and document its update path. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
2. Language and channel are separate dimensions
Saleor channels represent markets or commercial scopes controlling currency, price, visibility, stock and checkout conditions. A language identifies how a reader sees text; it is not a channel currency. The danger is confusing presentation with the underlying transaction. A translation may improve understanding, but it cannot change a stock rule or currency merely because the wording suggests it.
A visitor selects French and unexpectedly sees euros even though the channel used for payment remains denominated in another currency. Create a supported language-and-channel matrix and decide whether every combination is valid or whether some pairs require deliberate routing. Test the next customer action rather than treating a saved field as successful localization.
Test the same language in two channels and two languages in one channel, when supported, while comparing actual monetary values. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
3. Understand GraphQL languageCode
Saleor’s GraphQL schema exposes translation-related fields and language codes. The frontend must pass the intended code to queries that support translated values. A localized route must convey equivalent content without misdirecting the visitor to another product. Language-specific labels are valuable only if links remain tied to the correct catalog object.
An API query returns default-language titles because the caller never supplied the chosen language code. Inspect the deployed schema, use supported enum values and check how query fragments request the translation object. Open the route directly as a new visitor and compare it with navigation through the locale switcher.
Compare the same product query with and without the selected language, then test missing translation behavior. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
4. Product title versus product identity
A translated title changes the customer-facing label, not the ID, SKU, warehouse record or variant identity. Catalog data should remain connected to the same purchasable object. In a global shop, the right answer depends on the customer’s language and their commercial market independently. That is why a seemingly small label can reveal a deeper routing problem.
A Spanish product title is entered as a duplicate product, causing two stock pools to exist for one physical item. Track product and variant identifiers separately from translated names and slugs, and keep commerce identifiers protected. Compare at least two language-channel combinations and read both the screen and the GraphQL result.
Verify that orders placed in two languages refer to the same intended product and variant. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
5. Translate the useful product description
Product translation includes explanatory and commercial content, not merely the headline. A description should preserve usage, materials, limitations, included items and any warnings. What matters is the complete meaning of the decision offered to the customer. Names, warnings, quantities, eligibility and order evidence must agree, not merely share a language.
A translated clothing listing omits the fabric-care conditions while keeping every promotional adjective. Review factual clauses and safety instructions line by line, then adapt style without changing what is promised. Deliberately trigger a failure state because that is where hardcoded strings and missing policies often surface.
Have a target-language reviewer identify what is included, what is excluded and what would make the product unsuitable. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
6. Product variants and selectable options
Saleor variants and attributes help shoppers choose concrete combinations. Their labels and translated display values must remain tied to the correct variant identities. Before fixing a strange phrase, separate missing content from wrong fallback, stale cache and misconfigured market data. Each failure has a different remedy and responsible owner.
A variant appears as size M in one language but its alternative-language summary shows the wrong color. Review attribute labels, values and variant display names through the relevant GraphQL translations and storefront rendering. A concise reproduction record makes it possible to verify a change after another release.
Select the same combination in each language and reconcile the underlying variant ID. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
7. Categories, collections and hierarchy
Categories and collections are discovery tools whose names and descriptions are part of the customer’s mental map of the catalog. Translating products without navigation leaves many items effectively hidden. Translated content should remain accessible to someone who does not know the source language. Navigation, controls and support instructions are part of the translation experience.
A buyer searches in German but the menu, category breadcrumb and collection headings are still English. Translate appropriate navigation resources, check the actual menu integration and maintain equivalent hierarchy where intended. Read the next screen, and test from category discovery rather than jumping straight to the translated page.
Browse from an international homepage through a translated category to the product without using a saved direct URL. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
8. Use Dashboard translation screens carefully
Saleor Dashboard has dedicated translation views and entity links, with improvements documented for versions 3.21 onward. The screens help editors but do not replace testing the live storefront. A perfect linguistic edit can still fail when the storefront constructs a URL or message incorrectly. Technical and editorial checks complement rather than replace each other.
An editor saves a French value, assumes it is published everywhere, and misses a frontend cache that still serves English. Confirm the content source, language code and deployment behavior; check Dashboard changes against the API and rendered page. Confirm the visible outcome with a saved commerce record and the intended language’s metadata.
Record both the saved translation and the page or API response that customers actually receive. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
9. GraphQL translation mutations and permissions
The Saleor Products API includes operations such as productTranslate, productVariantTranslate, categoryTranslate, collectionTranslate and bulk variants in supported schemas. Translators need appropriate access and validation. Start by asking which part of the architecture owns the value. A visible product page may combine a GraphQL response, a CMS section and a frontend message; editing one of them does not necessarily change the others.
A bulk import updates product names while skipping attributes or generating untranslated errors that nobody inspects. Map each data type to its permitted mutation and permissions, and record which fields must be reviewed by commerce or legal owners. For release evidence, record the product identity, requested language, channel, URL and the value shown to the reader.
Run a small controlled mutation, inspect GraphQL errors and read back the changed translation before scaling. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
10. Check the deployed Saleor schema version
API types and fields evolve. Official documentation identifies versioned Saleor schemas; relying on a mutation or slug capability from another version can produce confusing implementation errors. The danger is confusing presentation with the underlying transaction. A translation may improve understanding, but it cannot change a stock rule or currency merely because the wording suggests it.
A storefront expects a translated slug lookup argument, but its backend deployment predates that capability. Pin development guidance to the deployed version and inspect the actual GraphQL schema rather than copying examples blindly. Test the next customer action rather than treating a saved field as successful localization.
Test the intended query and mutation against staging before a bulk translation project starts. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
11. Translated slugs are optional and version dependent
Saleor 3.21 and later supports translated slugs for certain catalog entities, but a storefront must deliberately resolve them. A translated display name alone does not generate a working localized URL. A localized route must convey equivalent content without misdirecting the visitor to another product. Language-specific labels are valuable only if links remain tied to the correct catalog object.
A Polish product link uses a Polish slug that the current frontend cannot resolve, returning a 404 despite the translated title. Choose whether localized slugs are enabled, understand primary-slug identity and build ordered lookup fallbacks as appropriate. Open the route directly as a new visitor and compare it with navigation through the locale switcher.
Open a localized path directly, navigate with language switch and follow old aliases to their intended canonical pages. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
12. Primary slugs and identity-based cache keys
A localized URL is a presentation route. The catalog’s primary slug or ID may remain the stable reference used by webhooks and cache invalidation. In a global shop, the right answer depends on the customer’s language and their commercial market independently. That is why a seemingly small label can reveal a deeper routing problem.
A translated slug gets updated, yet the page retains an old value because the cache was invalidated only for the primary path. Design cache and webhook logic around stable entity identity while accounting for every localized path that displays the entity. Compare at least two language-channel combinations and read both the screen and the GraphQL result.
Update one translation in staging, then check all affected language URLs and cached search data. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
13. Canonical and alternate language links
International SEO requires equivalence between language versions, correct rendered metadata and sensible redirects. Merely translating the page title is not enough. What matters is the complete meaning of the decision offered to the customer. Names, warnings, quantities, eligibility and order evidence must agree, not merely share a language.
Every localized product has a unique title, but all pages emit a canonical pointing at the English URL. Generate canonicals and hreflang alternatives from the actual locale routes and product identity, handling absent translations explicitly. Deliberately trigger a failure state because that is where hardcoded strings and missing policies often surface.
Inspect rendered HTML for multiple products and categories instead of relying on client-side preview states. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
14. Separate editorial content from catalog content
A store’s trust banner, shipping explanation, home sections and campaign stories might be in a CMS or a Saleor model rather than the product catalog translation fields. Before fixing a strange phrase, separate missing content from wrong fallback, stale cache and misconfigured market data. Each failure has a different remedy and responsible owner.
The product title is French, but the announcement bar promises an English-language promotion with different conditions. Identify the owner of every marketing surface and connect it to the locale and channel data used to render it. A concise reproduction record makes it possible to verify a change after another release.
Check that translated editorial claims match the live commercial promotion and market eligibility. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
15. Frontend functional messages
Buttons, validation errors, screen-reader labels, filter controls and empty states are often owned by frontend localization files such as next-intl messages in Saleor’s Paper reference storefront. Other frontends may differ. Translated content should remain accessible to someone who does not know the source language. Navigation, controls and support instructions are part of the translation experience.
The API returns French names, but a custom checkout still presents hardcoded English validation text. Translate the frontend’s documented message catalogs, preserve variables and run tests for normal and error states. Read the next screen, and test from category discovery rather than jumping straight to the translated page.
Trigger an empty search, invalid input, out-of-stock selection and empty cart in each supported language. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
16. Language selector and market selector design
A language change should not silently change the selected commercial market. Where a configured language-market matrix forbids a combination, the UI needs a clear choice and predictable destination. A perfect linguistic edit can still fail when the storefront constructs a URL or message incorrectly. Technical and editorial checks complement rather than replace each other.
A buyer chooses Korean while the UI routes to a market with incompatible delivery, then loses the product context. Model permissible combinations, link each selector to the proper state and explain when a market switch affects price or fulfillment. Confirm the visible outcome with a saved commerce record and the intended language’s metadata.
Switch language and market separately on product, cart and account pages, recording URL, currency and selection changes. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
17. Price, tax and checkout scope
Saleor channels scope currency, prices and checkout. Localizing text should not override the actual channel assigned to a checkout or the tax calculation performed. Start by asking which part of the architecture owns the value. A visible product page may combine a GraphQL response, a CMS section and a frontend message; editing one of them does not necessarily change the others.
The catalog page shows an amount in a formatted locale, but the checkout is created under a different channel. Keep the channel context consistent through browsing and checkout and compare the system’s numeric amounts with localized formatting. For release evidence, record the product identity, requested language, channel, URL and the value shown to the reader.
Place one authorized test order and reconcile price, currency, discount, tax and paid total. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
18. Availability and publication by channel
The same product can be visible or purchasable in some channels and not others. Translating a listing cannot create legal permission or inventory to sell it. The danger is confusing presentation with the underlying transaction. A translation may improve understanding, but it cannot change a stock rule or currency merely because the wording suggests it.
A German-language catalog advertises an item that the chosen market channel cannot fulfill. Check the channel publication, variant availability and shipping rules before translating a promise of availability. Test the next customer action rather than treating a saved field as successful localization.
Test both a purchasable and blocked item from the localized listing to the checkout boundary. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
19. Search across translated terms
Search may use Saleor queries or external indexes. A target-language name, category or attribute needs the configured search route to be discoverable. A localized route must convey equivalent content without misdirecting the visitor to another product. Language-specific labels are valuable only if links remain tied to the correct catalog object.
A product opens in French from a direct URL but searching its French name finds nothing. Inspect how the storefront indexes translations and language-specific synonyms; rebuild the index where required. Open the route directly as a new visitor and compare it with navigation through the locale switcher.
Test natural target-language queries, misspellings, facet labels and result links after changing translated catalog values. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
20. Checkout UI versus checkout data
Saleor’s API owns checkout state and commerce logic; the storefront owns how many explanatory strings appear. These responsibilities must stay distinct. In a global shop, the right answer depends on the customer’s language and their commercial market independently. That is why a seemingly small label can reveal a deeper routing problem.
An order total is correct in the API, but the frontend labels tax as shipping after translation. Translate user-facing labels against their exact semantic roles and compare them to the actual checkout response fields. Compare at least two language-channel combinations and read both the screen and the GraphQL result.
Review a cart with tax, shipping, voucher and several quantities in at least two languages. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
21. Payments, addresses and errors
Hosted payments and validation services can emit messages outside the translated catalog. They may follow browser or gateway locale conventions rather than Saleor language fields. What matters is the complete meaning of the decision offered to the customer. Names, warnings, quantities, eligibility and order evidence must agree, not merely share a language.
A customer completes a translated checkout but sees an English payment refusal, then returns to a language-mismatched page. Map provider-specific localization, payment-return routes and error display ownership before signing off. Deliberately trigger a failure state because that is where hardcoded strings and missing policies often surface.
Test success, cancellation, insufficient information and payment failure paths while preserving checkout state. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
22. Order notifications and customer service
Emails, invoices, tracking messages and support links can be created by apps or external services. Their translations should describe the actual order and approved policies. Before fixing a strange phrase, separate missing content from wrong fallback, stale cache and misconfigured market data. Each failure has a different remedy and responsible owner.
A French order receives an English notification with a stale returns period. Pass the intended language and market context to the notification provider and review dynamic values and links. A concise reproduction record makes it possible to verify a change after another release.
Read received messages on desktop and mobile, then compare figures and conditions with the saved order. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
23. Attribute and metadata ambiguity
Product attributes can represent human labels, structured facts or searchable metadata. A phrase like ‘voltage’ may be translated while the number and unit remain invariant. Translated content should remain accessible to someone who does not know the source language. Navigation, controls and support instructions are part of the translation experience.
An importer changes a numeric safety specification while processing translated attribute values. Classify every attribute by semantic type, deciding whether to translate its label, display value, neither, or both. Read the next screen, and test from category discovery rather than jumping straight to the translated page.
Diff source and target records for quantities, units, product identifiers and factual warnings. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
24. Accessible language and layout
Long target-language labels and right-to-left scripts can expose a storefront layout built around English strings. Text may be accurate but inaccessible. A perfect linguistic edit can still fail when the storefront constructs a URL or message incorrectly. Technical and editorial checks complement rather than replace each other.
The localized ‘continue to payment’ button runs under another control on a narrow phone. Test line wrapping, focus, labels, announcements and validation in real viewport sizes. Confirm the visible outcome with a saved commerce record and the intended language’s metadata.
Complete the flow with keyboard navigation and a screen reader where practicable. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
25. Content updates and cache invalidation
A translated product can become stale after the source changes or after cache retention hides a newer translation. Teams need an accountable synchronization process. Start by asking which part of the architecture owns the value. A visible product page may combine a GraphQL response, a CMS section and a frontend message; editing one of them does not necessarily change the others.
English documentation updates a compatibility limit while two language editions continue showing the earlier specification. Track source revisions, flag dependent translations and verify cache invalidation across localized paths. For release evidence, record the product identity, requested language, channel, URL and the value shown to the reader.
Edit one approved source value and trace it through translation review, API readback and rendered storefront. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
26. QA responsibilities and release blocks
Linguists can judge meaning, developers can judge routing and API behavior, and commerce owners can judge price or delivery claims. A single approval badge cannot replace these roles. The danger is confusing presentation with the underlying transaction. A translation may improve understanding, but it cannot change a stock rule or currency merely because the wording suggests it.
All strings are translated, but a market-specific prohibited product remains available in checkout. Require separate checks for language quality, commercial correctness, permissions, performance and SEO. Test the next customer action rather than treating a saved field as successful localization.
Keep a short acceptance report with product ID, channel, locale, tested URL, observed result and the responsible reviewer. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
27. Observability after launch
International launches change constantly. New products, frontends, app integrations and SEO changes can introduce regressions that were absent at the initial review. A localized route must convey equivalent content without misdirecting the visitor to another product. Language-specific labels are valuable only if links remain tied to the correct catalog object.
A new payment app displays an untranslated legal notice only when a charge fails. Monitor customer tickets by locale and channel, rerun representative checkout tests and inspect translated route errors. Open the route directly as a new visitor and compare it with navigation through the locale switcher.
Confirm that fixes reduce the observed customer problem and do not merely change the displayed phrase. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
28. Learning to reason in three dimensions
A mature Saleor localization decision considers content identity, language and market. Each axis has independent rules, so a correct design should make the distinction visible to the team. In a global shop, the right answer depends on the customer’s language and their commercial market independently. That is why a seemingly small label can reveal a deeper routing problem.
A company says it has three languages and therefore assumes it needs exactly three channels, unintentionally multiplying price configuration. Start with business requirements, define locales and channels independently, then decide where each piece of copy belongs. Compare at least two language-channel combinations and read both the screen and the GraphQL result.
Verify that the same language can be presented in a different market without silently rewriting the product identity or business record. Use the result to decide whether the proposed translation is both readable and commercially faithful. Store screenshots or API examples with exact language, channel and identity so a different reviewer can reproduce the finding.
Common real-world localization defects and repairs
The following situations are not separate software features. They are common ways in which a multilingual catalog, an international storefront and a real checkout can disagree. The diagnostic steps are more useful than simply increasing a translated-string count.
Situation 1: A French translation exists but the API returns English
The storefront query may omit the languageCode argument or request a field without its translation object. Reproduce the symptom using a known product ID, locale and channel. Inspect the owner of the failing value, and keep the commercial record unchanged while isolating language behavior.
Check the deployed GraphQL schema, query variables, fallback behavior and final rendered component. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 2: The Polish localized product URL returns 404
The backend may support translated slugs while the frontend still resolves only primary slugs. Do not assume the Dashboard preview describes the live storefront. Compare GraphQL output, route resolution and rendered HTML to find which layer differs.
Compare the catalog identity, slugLanguageCode usage and ordered lookup fallback before changing the slug. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 3: The customer changes language and also changes currency
The application may incorrectly tie language choice to channel selection. Retest from a clean session and through an existing customer journey. A correction is complete only when the next step, order state and customer-facing text all agree.
Test the language switch independently from market selection and reconcile checkout channel currency. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 4: A localized product is missing from category navigation
The category translation, menu resource or localized URL path may be incomplete. Keep before-and-after evidence and test at least one additional locale. That reduces the chance of solving an isolated symptom by introducing a broader regression.
Navigate from the root menu, inspect category translation and verify the final product identity. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 5: Variant labels differ between cart and product page
One component is reading translated attributes while another uses the default-language variant name. Reproduce the symptom using a known product ID, locale and channel. Inspect the owner of the failing value, and keep the commercial record unchanged while isolating language behavior.
Compare the GraphQL fields used by both components and preserve variant ID. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 6: An editor sees a saved translation but not on the site
Cache, deployment or missing query selection may be serving stale content. Do not assume the Dashboard preview describes the live storefront. Compare GraphQL output, route resolution and rendered HTML to find which layer differs.
Read back through Dashboard, GraphQL and rendered HTML in that order to locate the mismatch. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 7: The payment return page has the wrong language
Locale state may be absent from provider return handling or checkout cookies. Retest from a clean session and through an existing customer journey. A correction is complete only when the next step, order state and customer-facing text all agree.
Verify the complete success, failure and cancellation return routes using the same checkout. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 8: Search ignores translated category words
The search index or UI filter map may contain only source-language fields. Keep before-and-after evidence and test at least one additional locale. That reduces the chance of solving an isolated symptom by introducing a broader regression.
Test the backend query, reindex strategy and frontend result links in the chosen locale. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 9: A French warning is missing from the product page
A translated description may omit factual safety information while remaining grammatically fluent. Reproduce the symptom using a known product ID, locale and channel. Inspect the owner of the failing value, and keep the commercial record unchanged while isolating language behavior.
Compare warnings and exclusions clause by clause before publication. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 10: A translated slug points to stale cached HTML
The cache was invalidated for the primary slug but not for localized paths. Do not assume the Dashboard preview describes the live storefront. Compare GraphQL output, route resolution and rendered HTML to find which layer differs.
Inspect tags, webhook handling and localized path fan-out before changing article copy. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 11: A banner promotes unavailable free shipping
The CMS copy may be localized independently of the channel’s shipping conditions. Retest from a clean session and through an existing customer journey. A correction is complete only when the next step, order state and customer-facing text all agree.
Reconcile promotional claims with actual fulfillment rules and correct the approved source. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 12: A checkout tax amount has the wrong label
UI text mapping may be confusing tax and delivery fields. Keep before-and-after evidence and test at least one additional locale. That reduces the chance of solving an isolated symptom by introducing a broader regression.
Inspect API checkout values and frontend labels together, then test discount and tax combinations. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 13: A localized button fails on mobile
Translated text may be longer than the control’s design supports. Reproduce the symptom using a known product ID, locale and channel. Inspect the owner of the failing value, and keep the commercial record unchanged while isolating language behavior.
Test responsive wrapping and keyboard focus rather than replacing the accurate words with jargon. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 14: A language switch takes the reader to the wrong product
The frontend may be constructing URLs from translated slugs without resolving stable IDs. Do not assume the Dashboard preview describes the live storefront. Compare GraphQL output, route resolution and rendered HTML to find which layer differs.
Use identity-based link mapping and test direct routes and redirects. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 15: A translation import changes structured attributes
A bulk tool has incorrectly treated factual numeric fields as prose. Retest from a clean session and through an existing customer journey. A correction is complete only when the next step, order state and customer-facing text all agree.
Protect technical and numeric values and audit the mutation payload before retrying. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Situation 16: A new frontend release hardcodes English errors
A newly introduced message is not in the deployed localization catalog. Keep before-and-after evidence and test at least one additional locale. That reduces the chance of solving an isolated symptom by introducing a broader regression.
Inspect message keys, build output and error paths, then add a regression case. A fix should make the customer’s next action predictable while preserving the same underlying product, channel and checkout where required.
Worked example: one running shoe, two languages and two markets
Imagine a Saleor catalog with one running shoe, three sizes and two colorways. The business offers an English-language UK channel and a separate French-facing channel, but it may also want a French-language shopper to browse a market that does not use euros. Start by recording the product ID, variant IDs, primary slug, channel assignments, currency, prices, available stock, permitted destinations and returns conditions. That inventory prevents a translation task from accidentally changing what is being sold. Translate the product name, description, relevant category and attribute labels through Saleor’s supported translation surface. Preserve variant identity and structured specifications.
Next test the frontend. A reference architecture such as Saleor Paper distinguishes catalog GraphQL translations, editorial storefront copy and code-owned interface messages. Translate the right piece in the right layer: product material claims belong to catalog content; a regional promotion belongs to approved editorial content; and the add-to-bag action or required address error belongs to the functional UI. Choose a localized slug strategy only after confirming backend version and storefront support. Navigate from category to product, then switch language without changing the physical item unexpectedly. Inspect the canonical page and alternate-language links in actual rendered HTML.
Select a known variant and add it to a test cart. Compare the checkout channel and currency with the selected market. Apply a valid promotion if available, then deliberately trigger an invalid input to inspect untranslated error states. Finish an authorized test order and reconcile tax, shipping, payment and stock with the backend. Read the confirmation in the intended language. If product names are French but the confirmation email uses the wrong return conditions, the language is not ready. If all words are correct but the order is created in another channel, the problem is more serious than translation.
A four-week learning and release roadmap
Week one: inventory channels, locales, products, variants, GraphQL translation fields and frontend message owners. Choose a representative pilot and capture one working source-language order. Confirm the deployed backend version and inspect its actual schema, especially before relying on localized-slug support.
Week two: add translations for product, variant, category and appropriate attributes through Dashboard or reviewed GraphQL operations. Translate functional UI messages and editorial content through their separate owners. Walk through natural target-language browsing, search, selectors and cart interactions; record both language and channel for every test.
Week three: validate market eligibility, stock, prices, taxes, shipping, discounts, address entry, payment, errors and notifications. Do not allow text editors to change commercial data to make a translation appear correct. Assign the appropriate business owner to review promises about delivery, refunds and product capabilities.
Week four: check direct URLs, redirects, translated slugs, metadata, hreflang, canonical URLs, caches and accessibility. Verify translations remain current after a source edit and a deployment. Launch one complete language-channel journey before multiplying catalog coverage; retain regression cases for every critical defect found.
Frequently asked questions
Does changing the Saleor Dashboard language translate a product? No. Administration interface language and a product’s content translations are separate concerns. Check the specific translation record and the GraphQL response.
Is a Saleor channel the same as a locale? No. Channels model commerce conditions such as currency and availability; locales describe linguistic presentation. A storefront may deliberately restrict certain combinations.
Can Saleor use translated URL slugs? Supported newer versions include translated catalog slugs, but the frontend must correctly resolve them, link them and handle fallback. Confirm the deployed backend and storefront versions.
Why is my catalog French but checkout English? The checkout interface is often owned by the frontend or payment integration rather than the catalog translation data. Inspect each message source and state.
What should stop a localization release? Wrong commercial terms, misplaced products, broken checkout or critical untranslated instructions. A page is not ready merely because all visible titles have been translated.
Official references and related guides
Saleor Products GraphQL API; Saleor Channels; Saleor Dashboard translation updates; Saleor Paper international storefront design; Saleor Paper translated-slug design. Use the documentation and schema for the deployed version when implementing these ideas.
Read Master Art of Translation | The Complete System for Moving Meaning Between Languages for accuracy and review principles. Find other platform-specific guides at Translate Like a Pro | Series Index.