How do you translate a BigCommerce storefront without confusing Stencil theme labels, Catalyst locale configuration, product data, checkout language and transactional emails? BigCommerce multilingual setup differs depending on the storefront architecture. This practical guide explains the difference, teaches a safe sequence for localized catalog and customer journeys, and shows how to test language selection from product discovery through order acknowledgement.
Businesses searching for BigCommerce multi-language storefront setup, Catalyst localization, Stencil JSON language files, translated product catalogs, BigCommerce checkout translation and B2B Buyer Portal localization need to know exactly which model their store uses. Current BigCommerce documentation describes multilingual capabilities for Catalyst, a developing multi-language path for Stencil, and older single-language storefront guidance. An article that treats all three as the same feature can lead a team into a costly and incomplete migration.
The best approach is to identify the channel and storefront technology first, choose supported locales, translate static components and dynamic catalog data separately, and test checkout, emails, search, routing, currencies and business terms with real storefront behavior. This longform tutorial gives a staged plan, diagnostic situations, a worked example and quality standards for serving buyers rather than merely displaying their language.
Quick answer: a complete multilingual visitor journey
First identify whether the site is Catalyst, a Stencil storefront with newer multi-language support, a classic single-language configuration or a custom headless build. Confirm active locales and their exact limits. Create language resources for static UI, localize product data through supported controls or APIs, inspect Makeswift pages where relevant, then verify cart, checkout, notification and account journeys. Avoid combining instructions for different storefront generations.
What professional translation means here
A multilingual BigCommerce Catalyst and Stencil project has three simultaneous obligations: the words must preserve meaning; the platform must serve the correct locale and resource; and the underlying business must be able to deliver what the language version promises. A translation can pass a language review and still fail a customer when a product option, form, search result, password email or checkout message points elsewhere. The practical standard is a verified task, not a translated-word percentage.
Separate four categories before work begins: source-controlled facts that must not change; human-facing terms that require accurate translation; technical keys or identifiers that must stay stable; and region-specific offers that require business approval. An editor should be able to explain which category a string belongs to. When a statement crosses categories, stop and ask who owns the decision instead of improvising.
The complete step-by-step guide
1. Distinguish Catalyst from Stencil before editing
Catalyst is a headless storefront architecture with locale-aware routing and data access. Stencil is BigCommerce’s theme-based storefront, with its own translation files and historically single-language documentation. Newer Stencil multi-language support is described as beta in developer learning material. Write the storefront type and version on the project brief.
Start by treating the BigCommerce Catalyst and Stencil language edition as a service commitment rather than a decoration. Readers do not care how many strings were processed; they care whether the page answers their question and leads to the correct next step. Describe one visitor, the decision that visitor is trying to make, and the evidence needed to make it. A person choosing a course, buying a product or asking for a return may interpret an attractive but incomplete page as a complete offer. That is why translation starts with promises, not buttons.
A practical test for this stage is straightforward: Are the team following a tutorial written for the installed storefront technology? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
2. Read new and older BigCommerce localization guides together
Some older BigCommerce pages recommend a separate single-language store, while current Catalyst guidance supports several locales on one storefront. The apparent conflict reflects different products and generations rather than a universal guarantee. Use current product-specific documentation as the source for implementation.
A language code and a country are different pieces of information. French in France and French in Canada share a language but may require different shipping terms, spelling, regulatory notices or customer support arrangements. A URL subdirectory is also not the same thing as a locale code; one can change while the other continues to describe language and region. Before editing content, write down the exact audience, target language, optional region and URL policy. This small exercise prevents later confusion about where the visitor should land.
A practical test for this stage is straightforward: Which features are stable, beta or outside the site’s actual entitlement? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
3. Map channels, locales and storefronts
A channel carries storefront configuration. Catalyst locale settings can be enabled through channel localization controls or APIs; the documentation describes a limit of five locales per Catalyst channel. Multi-storefront structures may have separate domains or subpaths. Document the relation between brand, channel, domain and locale.
Product capabilities are always conditional on plans, site configuration, integrations and the storefront version. A feature shown in one tutorial may be hidden or unavailable on another installation. Instead of treating a screenshot as permission to make a promise, check the product’s current documentation, feature entitlement and the interface actually in use. Keep a record of any unsupported route. You can still serve readers well by naming the limitation and providing a reliable alternative, but not by implying that an unavailable feature works.
A practical test for this stage is straightforward: Can each buyer route be traced to the correct channel and catalog context? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
4. Choose language prefixes carefully
Catalyst uses locale-specific URL prefixes derived from channel settings, with root handling for the default language. The locale subdirectory may differ from the language code. Links, search discovery and user expectations depend on consistent route design. Choose prefixes before generating public campaign links.
Source content is not merely text waiting to be translated. It contains decisions about names, prices, eligibility, timings, ownership and exclusions. The first task is to separate stable facts from prose that can be adapted. The second is to identify where the facts come from and who may authorize corrections. A translator can improve clarity without changing a contract. Where a source statement is ambiguous, ask the content owner to resolve the meaning before creating a confident target-language sentence.
A practical test for this stage is straightforward: Can an old product URL resolve in the intended locale after a language switch? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
5. Translate static Catalyst component messages
Catalyst uses language message files such as messages/fr.json and next-intl to render fixed interface text. Enabling a locale without an appropriate messages file may produce a 404. Such files do not translate product names automatically. Review each active locale’s message bundle before activation.
An editable field often has a hidden relationship to other fields. A product name may appear in search, a navigation menu, a confirmation email and a social preview. A CMS reference may drive a collection list, whereas a separate static page may require individual editing. Document these dependencies as a short content map, using real examples from the project. Then change a safe test record and observe every surface it touches. That is more reliable than assuming one successful save proves that the whole system has updated.
A practical test for this stage is straightforward: Does a translated cart and its empty-state message render on a direct URL visit? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
6. Understand the Stencil /lang directory
Stencil themes use JSON key-value translation files under a /lang directory, including English defaults. Template text should reference language keys rather than hard-coded source phrases. A key missing from the target-language file may fall back or display inconsistently. Keep translation keys stable across theme revisions.
Interface strings are short but consequential. Words such as Continue, Subscribe, Available, Free, Cancel and Confirm can mean different things at different moments in a transaction. A translation that reads naturally in isolation can mislead if the button submits a payment rather than opening information. Open the screen, record what the control actually does and choose language that tells the truth. Test focus order, input errors and the mobile layout, because the same short label may need a more explicit version in constrained contexts.
A practical test for this stage is straightforward: Do category, cart, navigation and account components render translated labels? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
7. Keep static text separate from catalog data
A theme translation file can change a button but not automatically rewrite every catalog product. Product names, descriptions and search keywords are separate data resources, with capabilities differing by storefront and architecture. Inventory theme strings and dynamic product fields as different queues.
Navigation should preserve the reader’s place in the task. A language switcher that takes every visitor back to a homepage is not equivalent to one that opens the same article in another language. Similarly, a menu item can be grammatically correct while pointing to a source-language page. Sketch the journeys from entry page to destination before testing. Include the browser back button, copied URLs and direct visits from search engines. These ordinary routes reveal broken assumptions that a translation editor will not show.
A practical test for this stage is straightforward: Can a product remain English even though its surrounding buttons are French? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
8. Localize dynamic catalog records through supported mechanisms
Catalyst documentation explains locale-specific catalog data through BigCommerce controls and GraphQL APIs. The Storefront GraphQL API can return localized product information in the context of shopper language when translations are configured. Test a controlled product with a recognizable name and description.
Dynamic content is best tested as data, not as a screenshot. A field can inherit a source value until a specific locale has an override. A list can omit records that are unpublished in one language. A tag or option may look like a sentence but actually function as a stable identifier. Protect identifiers and relationships while translating their human-visible labels. Create an inventory of record types and field types, then test one representative example of each before processing the full catalogue.
A practical test for this stage is straightforward: Does requesting a supported locale return the expected translated product data? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
9. Learn the role of Accept-Language
Catalyst’s language-aware data requests can use the Accept-Language header and the shopper’s selected locale. An incorrect language context can produce default-language content even when translations exist. Keep header and page locale aligned through client and server paths.
Visual adaptation is part of meaning. Translated text can be longer, require different line breaks or use a script that needs suitable fonts and right-to-left support. An image can contain embedded source-language words; an icon may communicate differently in another culture. Do not solve these problems by shrinking every font or deleting essential information. Instead inspect the design at mobile and desktop widths, check accessible names and provide a locale-specific visual only where it improves understanding without changing the underlying claim.
A practical test for this stage is straightforward: Does a locale change affect product listings and product detail pages alike? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
10. Translate Makeswift page content
Catalyst storefront projects may use Makeswift for editorial content. Those pages have their own localization workflow rather than being translated solely by modifying the storefront JSON message files. List every landing page that lives in the visual editor.
Search visibility begins with a useful, available page. An attractive translated title cannot compensate for a broken route, an empty body or a page that automatically redirects people away from their chosen language. Write headings that answer real questions, use language-appropriate terms, and confirm that the canonical URL, indexing configuration and alternate-language signals describe the pages that actually exist. Search engines do not complete checkout or support tickets for people; you still need a visitor-level functional test.
A practical test for this stage is straightforward: Is the campaign page fully translated when opened from a localized product card? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
11. Know the Catalyst locale limit
The current Catalyst multi-language overview describes a maximum of five locales on one channel. Teams planning many market variants should consider whether the channel, domain and market architecture supports them. Do not promise an unlimited number of languages from a single channel.
Catalog and service information mixes descriptive text with structured facts. A colour, dimension, qualification, warranty, appointment duration or stock position may be stored in an attribute rather than in the main description. Translate the human-visible words but do not silently modify identifiers, option relationships or factual measures. A fluent product story that promises a different bundle is inaccurate. Build a sample product with variants and check every option selection before you approve a large set of localized records.
A practical test for this stage is straightforward: Can all proposed locales be created without unsupported configuration work? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
12. Handle Stencil beta status honestly
The Stencil training material describes single-channel multi-language support as beta. Beta coverage, setup and availability can change, so a migration plan must confirm eligibility and production constraints before publishing dates. Separate a proof of concept from a supported public release.
SEO metadata has at least three audiences: the person searching, the person sharing a link and the software interpreting the page. A description should faithfully summarize the localized page, not a page that has not been translated yet. Social images may carry text that needs another edition, and structured data must not claim prices, availability or ratings unsupported by the page. Keep a separate check for titles, descriptions, preview cards, language alternates and any custom metadata that inherits from the source.
A practical test for this stage is straightforward: Which portions are validated by the store’s own deployed environment? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
13. Localize checkout text in the correct layer
BigCommerce provides checkout translation pathways, but the relevant interface and constraints depend on storefront technology. Some older Stencil documentation focuses on Optimized One-Page Checkout. A translated cart does not automatically guarantee a complete localized checkout. Inspect the payment flow with a safe testing method.
The final action is where errors become expensive. A shopper may read the correct localized product description but enter an unexpected currency, shipping region or checkout language. A student may find a translated course timetable and then submit a registration form with English-only consent text. Walk through the transaction using safe test accounts and non-production payments where available. Read every intermediate message, not only the first and last screens. Separate the problem of translation from the problem of what the system can actually deliver.
A practical test for this stage is straightforward: Which checkout messages remain in source language after a locale switch? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
14. Review transactional email templates
Order confirmation, shipping updates and other emails can depend on templates and APIs distinct from storefront components. BigCommerce documentation describes email translation support, but custom templates must be audited for placeholders and regional wording. Maintain a transaction-message inventory by shopper locale.
Transactional messages deserve their own inventory. Order confirmations, password resets, invoices, booking reminders and failed-payment notices can be controlled by different services or apps. A published storefront language does not automatically guarantee that every notification is translated or sent to the right recipient. Test language preferences, fallback, dynamic placeholders and the links inside messages. The aim is to preserve the transaction’s identity and next action; accidental substitution of order numbers, amounts or dates is a serious error.
A practical test for this stage is straightforward: Does the confirmation preserve the correct order ID, amount and support link? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
15. Treat currencies and tax as separate configuration
A French label is not a commitment that a store accepts euros or ships to France. Currency presentation, tax calculations, duties, address validation and available delivery options depend on commerce settings and region. Keep translations aligned with actual operational policies.
Third-party tools introduce boundaries. A support widget may load in English, a consent manager may set a different language, or an external form may ignore the site’s locale entirely. The correct response is not to assume that BigCommerce Catalyst and Stencil’s translation feature has authority over every integration. Create a list of tools visible to readers and identify which service owns each string. Where a tool cannot be localized, make the limitation visible in planning and consider a supported workflow rather than fabricating compatibility.
A practical test for this stage is straightforward: Does the buyer understand what will be charged and delivered? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
16. Translate search behavior, not only product pages
Current BigCommerce Storefront GraphQL guidance describes multi-language product search for supported configurations, using translated product names, descriptions and search keywords. Search indexes and buyer locale must match the pages being offered. Try a natural target-language search term with a known product.
Accessibility is not an optional finishing touch. Screen-reader language, reading order, form labels, alt text, keyboard navigation, error explanations and directionality all affect whether information is understood. Translate alternative text according to the function of the image in that context; it should not simply duplicate a filename. Ask a reviewer to navigate without a mouse and, where feasible, use assistive technology. A language edition fails if it is only understandable to sighted desktop users.
A practical test for this stage is straightforward: Does the localized query find the same intended item without exposing an unrelated variant? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
17. Understand the B2B Buyer Portal boundary
BigCommerce documents localized static Buyer Portal strings with a fallback order involving channel custom translations, global custom translations, built-in language bundles and English. The selector appears for multiple active languages on supported channels. Test with a real permitted B2B role and a safe account.
A quality review should cover meaning, function and evidence separately. A bilingual reviewer checks whether the translated claim matches the source. A functional reviewer follows links, selections and submissions. A subject owner confirms that promises about availability, eligibility and commercial terms remain correct. One person may cover more than one role, but the questions should still be separated. This prevents a polished translation from being accepted merely because it sounds fluent, even when the underlying operation is wrong.
A practical test for this stage is straightforward: Do purchasing approvals and account actions remain understandable in the portal? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
18. Audit status messages and account areas
Order statuses, password messages, address forms, saved lists and support surfaces can be owned by separate components. A language selector may synchronize with the storefront but still leave an unsupported string in English. Capture each account journey as a separate test case.
Use a small but realistic testing matrix. At minimum, select a target language, one desktop viewport, one narrow mobile viewport, a clean browser session and one full user task. Add cases for a missing translation, an unavailable item, a failed form and a direct link from search. Record the expected result before clicking. When something fails, capture the exact URL and locale alongside the visible text so that developers and editors can reproduce the problem without guessing.
A practical test for this stage is straightforward: Can a returning buyer track an order without switching to the source language? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
19. Prepare accessible localized templates
Theme and component translations must respect keyboard navigation, accessible labels, date formatting and text expansion. A long target-language cart message can break responsive layout despite passing linguistic review. Test with mobile, keyboard focus and accessible names.
Publishing is a change to a living service. A language edition should be staged so that readers do not encounter a half-localized journey, and changes to primary content can invalidate previously approved target-language statements. Separate draft, review and live states where BigCommerce Catalyst and Stencil permits. Before launch, sign off a short release checklist: entry route, navigation, key content, forms, purchases if relevant, messages, search metadata and support contacts. After launch, repeat the same smoke test on the public domain.
A practical test for this stage is straightforward: Can a buyer distinguish quantity, discounts and remove-item controls? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
20. Run release QA on real localized routes
A CMS preview or local development server is not sufficient. Catalyst locale changes may be cached briefly; a newly enabled language also needs its translation message file. Test deployed deep links, catalog data and checkout. Record actual URLs, environment and timestamps in issue reports.
Language quality changes with time. A new product attribute, policy revision, SEO title or feature addition can create an English-language island inside a localized experience. Treat changes as signals that translation review may be necessary. Maintain a simple log of what changed, when, who reviewed it and what locale was affected. The log should be short enough to use, not a ceremonial document. Recheck high-risk pages more often than low-risk evergreen explanations.
A practical test for this stage is straightforward: Does an external buyer reach a complete, coherent storefront? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
21. Assign translators and developers complementary responsibilities
Translators should approve meaning and glossary decisions. Developers should own message keys, locale context and API behavior. Merchants should verify price, tax, inventory and shipping. When everyone edits the same field without ownership, correctness becomes untraceable. Create simple sign-off roles for every high-risk flow.
A working glossary is a decision record, not a dictionary for its own sake. Explain which term is preferred, what it means in this product, what alternatives should be avoided and where exceptions are justified. Keep proper names, units, variable names and system identifiers distinct from language that should be localized. Train reviewers on the glossary with a few actual screens rather than asking them to memorize a long abstract list. Good consistency serves understanding; it should not erase natural expression.
A practical test for this stage is straightforward: Who can confirm that an order statement is commercially accurate? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
22. Plan source changes and new markets
After launch, a theme update can add strings, a new product category can require catalog translations, and a checkout integration can change error messages. Each trigger should create a localized-review action rather than an assumption that prior work remains complete. Re-run a short multilingual smoke test after releases.
Finish with independent practice. Give a learner one multilingual page, one dynamic item and one transaction or submission to examine. Ask for a short explanation of the user’s intent, the language promise, the evidence of successful translation and the first unresolved risk. The learner should be able to justify a change without claiming authority over product facts. Repeat the exercise after a source update. This tests the capacity to maintain a system, not just to prepare a one-time translation.
A practical test for this stage is straightforward: Which test would detect a new untranslated message fastest? Write down the source setting, the target locale, the expected result and the observed result. If the two differ, identify whether the content, routing, permissions or commerce behavior is responsible. That record is more useful than an unsupported claim that the translation is complete.
Twenty-four real-world problems and how to diagnose them
1. Catalyst French route gives 404
Confirm an active locale and matching messages/fr.json file rather than changing product translations first. Ask what the visitor expected before changing the wording. Record the source route, target route and actual result; then decide whether the problem is content, configuration, entitlement or an integration. That diagnosis prevents a copy edit from concealing a broken process. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
2. Stencil theme displays raw language keys
Check /lang JSON resources, key names and theme build integration. Reproduce the problem in a private browsing session. Editors often see controls or cached versions that ordinary visitors do not. Compare the published page with its draft, and report which one supplied the misleading signal. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
3. Product titles stay English on a French storefront
Verify dynamic catalog translations and the request’s language context; theme JSON keys alone do not translate catalog data. Check whether the issue concerns a display label or a stable technical identifier. A visible label may need natural translation, while an API key, SKU, status code or field key may need to remain unchanged. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
4. An older manual insists on separate stores
Identify whether it documents classic Stencil while the project uses Catalyst or a newer multilingual Stencil beta. Review the most consequential claim first. Price, date, service availability, location, order action and consent should be corrected before polishing less important phrasing. The right priority reduces harm while keeping the release manageable. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
5. A developer adds a sixth Catalyst locale
Check current per-channel limits and consider supported channel architecture instead of bypassing validation. Follow the destination of each link rather than deciding from its anchor text. Correct words with an incorrect destination still mislead the visitor. Test the same route after changing languages and after returning to the original version. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
6. French cart labels work but checkout is English
Audit checkout translation settings and the installed checkout implementation separately from theme text. Compare the language editor’s view with the page viewed by a non-editor. A setting that appears complete in a management panel may have no effect until a language or page is published to the public site. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
7. Search returns only English product names
Check translation coverage for search fields and Storefront GraphQL locale context. Keep a screenshot and a one-sentence expected outcome. A useful issue report says what the person attempted, the language, where it failed, and the next action. Such reports can be verified by someone who did not write the translation. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
8. A B2B portal unexpectedly uses English
Inspect channel-level overrides, global overrides, provided translation bundles and fallback. Distinguish a missing translation from an intentional source-language name. A brand, product code or official publication title may properly remain unchanged; a consent sentence or error message usually should not. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
9. The B2B language selector is absent
Confirm the channel has multiple active languages and rollout support rather than assuming theme CSS hid it. Test with a long translation, not only the shortest English label. Layout defects frequently hide until a heading wraps, a button expands or a mobile navigation item becomes two lines. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
10. New locale appears several minutes after saving
Consider documented locale cache behavior before diagnosing a permanent deployment failure. Read content in context with its surrounding prices, options and warnings. A correct isolated sentence can become inaccurate next to the wrong currency, stock badge or product variant. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
11. Campaign page stays English while header is French
Check Makeswift content localization or other editorial CMS ownership. Check the language selected in the interface against the language of emails and external links. A mismatch may come from separate preference stores rather than the visible page. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
12. An API request returns the wrong region’s descriptions
Inspect Accept-Language handling and mapping between user selection and channel locale. Treat legal and safety statements as source-controlled material. Get approval from an appropriate owner instead of creatively rewriting an ambiguous warning. The translator’s role is accuracy and clarity, not legal authorization. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
13. Static translation contains stale placeholder names
Check message parameter naming and component use without translating keys or variables. Ask what the visitor expected before changing the wording. Record the source route, target route and actual result; then decide whether the problem is content, configuration, entitlement or an integration. That diagnosis prevents a copy edit from concealing a broken process. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
14. French product URL opens an English product page
Follow the actual route and storefront channel; verify the target-language catalog version exists. Reproduce the problem in a private browsing session. Editors often see controls or cached versions that ordinary visitors do not. Compare the published page with its draft, and report which one supplied the misleading signal. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
15. A menu item says ‘Checkout’ in French but goes to a dead page
Test links after every locale change rather than judging label quality alone. Check whether the issue concerns a display label or a stable technical identifier. A visible label may need natural translation, while an API key, SKU, status code or field key may need to remain unchanged. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
16. Translated price text disagrees with actual cart currency
Do not use translation to simulate a currency feature; review commerce configuration and pricing policy. Review the most consequential claim first. Price, date, service availability, location, order action and consent should be corrected before polishing less important phrasing. The right priority reduces harm while keeping the release manageable. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
17. Order confirmation is partly untranslated
Review transactional email templates and dynamic data placeholders as their own system. Follow the destination of each link rather than deciding from its anchor text. Correct words with an incorrect destination still mislead the visitor. Test the same route after changing languages and after returning to the original version. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
18. A product is out of stock but its translation promises availability
Check live inventory facts, not only target-language prose. Compare the language editor’s view with the page viewed by a non-editor. A setting that appears complete in a management panel may have no effect until a language or page is published to the public site. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
19. An accessibility label is missing from an icon-only button
Add localized accessible naming and test focus order on cart controls. Keep a screenshot and a one-sentence expected outcome. A useful issue report says what the person attempted, the language, where it failed, and the next action. Such reports can be verified by someone who did not write the translation. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
20. An account recovery email uses source-language instructions
Identify account email ownership and verify language preference transmission. Distinguish a missing translation from an intentional source-language name. A brand, product code or official publication title may properly remain unchanged; a consent sentence or error message usually should not. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
21. A Stencil beta feature works in staging but not production
Verify production release eligibility and configuration before making public promises. Test with a long translation, not only the shortest English label. Layout defects frequently hide until a heading wraps, a button expands or a mobile navigation item becomes two lines. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
22. Localized product search selects the wrong variant
Test product identifiers and locale search mapping instead of altering SKU text. Read content in context with its surrounding prices, options and warnings. A correct isolated sentence can become inaccurate next to the wrong currency, stock badge or product variant. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
23. The translation JSON contains invalid syntax
Validate message files and run the actual app build before activation. Check the language selected in the interface against the language of emails and external links. A mismatch may come from separate preference stores rather than the visible page. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
24. A new theme release introduces English strings
Diff message keys, translate additions and rerun representative checkout tests. Treat legal and safety statements as source-controlled material. Get approval from an appropriate owner instead of creatively rewriting an ambiguous warning. The translator’s role is accuracy and clarity, not legal authorization. On BigCommerce Catalyst and Stencil, verify the consequence on the public-facing route before closing the issue.
Worked example: from a source-language page to a verified customer journey
A specialist equipment retailer sells tools internationally. The business has a Catalyst storefront, a catalog with a few hundred products and a support team that can answer in French. It wants French-language product discovery but does not yet ship to every French-speaking country. The project team writes a narrow promise: French pages and checkout for supported destinations, with shipping and tax shown according to actual supported addresses.
The developer confirms the Catalyst channel, its supported locales and the message bundle for French. The team activates a testing locale, inspects the /fr route and checks that a missing file would not strand readers on a 404. The translator checks cart labels and confirmation instructions, while the merchant identifies approved descriptions for the first twenty products.
A controlled test product has a stable SKU, dimensions and three variants. The team localizes its name, explanatory description and search keywords through supported catalog translation pathways without changing product identifiers. A tester runs a French query and checks the resulting product card and detail page. The team also localizes the relevant Makeswift advice page.
The checkout exercise uses a safe testing method and supported addresses. The tester chooses a variant, changes quantity, sees the correct shipping options and reads the local-language acknowledgement. A support reviewer checks what language the order email uses and whether it accurately states tax, delivery estimate and returns contact. Screenshots capture any fallback to English.
Only after the catalog, static strings, search, checkout and email tests pass does the retailer release French publicly. It records which other countries remain unsupported despite sharing the French language. Later a theme update adds a new returns link, which triggers a translation and routing review instead of being assumed safe because the earlier launch passed.
A four-week learning and launch plan
Week 1 — Understand and inventory
Choose one representative user, target locale and source-to-target route. Map static pages, CMS or catalog fields, shared components, search labels, accessibility, forms, commerce services and all messages a visitor could receive. Record each content owner and mark platform limits. Do not begin with an entire catalogue because a small sample reveals mismatches at far lower cost. Finish the week with a clear definition of what a completed language journey must achieve.
For BigCommerce Catalyst and Stencil, the deliverable is a short evidence sheet: the language or store view, one successful task, the URLs tested, who signed off the claims, and any open issue that restricts publication. This makes the project teachable to a new colleague and prevents a future editor from mistaking an attractive translation for a fully maintained service.
Week 2 — Translate a controlled sample
Create the applicable draft language resources and translate one representative record per content type. Use a terminology sheet and an approved fact sheet. Keep variables, IDs, codes, prices and contractual facts under controlled ownership. Check the sample in its actual interface, including any inherited values, and ask a second reviewer to identify ambiguous statements. Do not use the number of translated entries as the readiness score. Finish with source-linked corrections and a short list of uncovered surfaces.
For BigCommerce Catalyst and Stencil, the deliverable is a short evidence sheet: the language or store view, one successful task, the URLs tested, who signed off the claims, and any open issue that restricts publication. This makes the project teachable to a new colleague and prevents a future editor from mistaking an attractive translation for a fully maintained service.
Week 3 — Run independent functional review
Open the test version from fresh sessions and follow real tasks. Check a deep link, navigation, mobile text expansion, screen-reader labels, a search query, at least one form and the purchase or appointment journey where relevant. Examine confirmation, error and recovery messages. Ask a reviewer to state what service or product they believe they will receive. Compare their answer with the merchant’s verified promise. Record failures using URLs, exact locales and expected outcomes.
For BigCommerce Catalyst and Stencil, the deliverable is a short evidence sheet: the language or store view, one successful task, the URLs tested, who signed off the claims, and any open issue that restricts publication. This makes the project teachable to a new colleague and prevents a future editor from mistaking an attractive translation for a fully maintained service.
Week 4 — Release and maintain
Review the issues, obtain owner approval for high-risk text, and publish only the portions of the language edition that are ready. Repeat the same smoke test on the public site immediately after deployment. Tell customer-support staff which languages and regions are genuinely supported. Keep a change log for new pages, catalog fields, policy revisions and extension updates. Schedule focused rechecks of transactional content so that translated pages do not drift away from current service facts.
For BigCommerce Catalyst and Stencil, the deliverable is a short evidence sheet: the language or store view, one successful task, the URLs tested, who signed off the claims, and any open issue that restricts publication. This makes the project teachable to a new colleague and prevents a future editor from mistaking an attractive translation for a fully maintained service.
Translation quality standards for a world-facing service
Meaning
The target text must preserve the source’s important facts, relationships, conditions and exclusions. Natural language is desirable, but translators cannot invent eligibility, stock, prices, health advice, legal promises or technical capability. Confirm terms that change purchasing or service decisions with the responsible person.
Completeness
Review all surfaces a reader encounters, not only the first page. Menus, labels, related CMS items, filters, errors, receipt messages, alt text, search snippets and follow-up contacts may be separately owned. Use a coverage inventory that says not only what was translated but also what the platform cannot currently support.
Function
The localized interface must perform the correct action. Opening a modal is not the same as submitting an order. Choosing a variant is not the same as changing the SKU. A language switch is not necessarily a matching-page redirect. Test clicks, form states, direct URLs and recovery routes from a clean session.
Clarity
Prefer short, intelligible sentences with explicit subjects and actions. Preserve necessary technical terminology but explain it in ordinary language. Ask whether an international reader can tell what happens next without knowing the source language. Keep regional examples useful rather than assuming a single country’s institutions or slang are universal.
Accessibility
Check readable fonts, language metadata, focus order, keyboard use, alternative descriptions and text direction. Long translations can wrap differently, especially on phones. A translated error message is not accessible if it appears only by color or cannot be reached by an assistive technology user.
Evidence
Use a clear distinction between a passed test and a plausible assumption. Write down the source of each important claim, test the real public route and capture a failure that another person can reproduce. When documentation changes, follow official product guidance rather than copying an old screenshot blindly.
Maintenance
Every new source field, product option, policy, promotion or theme update can affect more than one language. Keep terminology decisions and dependencies visible, assign review owners and make localized checking part of ordinary releases. This is a maintained educational and commercial service rather than a one-off translation exercise.
Frequently asked questions
Is BigCommerce multilingual on one storefront?
It depends on architecture and feature maturity. Current Catalyst documentation describes multiple locales on one channel, and newer Stencil multilingual functionality has beta documentation. Older single-language storefront advice still applies in its context.
What does Catalyst use for fixed UI text?
Localized message JSON files consumed through next-intl, alongside separately localized catalog data and Makeswift content. Enabling a locale without its message file can cause an error.
How many locales can one Catalyst channel support?
The current BigCommerce Catalyst documentation describes a maximum of five locales per channel. Check the current docs and the specific account before planning a larger rollout.
Do Stencil JSON translations translate product names?
Not automatically. Static theme strings and dynamic product data have different storage and localization processes.
Does BigCommerce localize checkout?
BigCommerce has checkout localization support, with configuration varying by storefront and checkout type. Test the actual deployed path and email messages.
How is a shopper’s language conveyed to Catalyst?
Catalyst documentation describes locale-aware routing and request headers such as Accept-Language for dynamic data. Keep the selected locale aligned throughout the journey.
Does the B2B Buyer Portal have a language selector?
Current documentation says it appears for supported channels with multiple active languages, with translation fallback and rollout considerations.
What is the best multilingual BigCommerce smoke test?
Find one product in the new language, select a variant, read shipping and tax information, proceed through checkout safely and inspect the confirmation in the appropriate language.
Practice exercises for readers and implementation teams
Exercise 1
Exercise one: Choose a page in the target language and write a four-sentence description of what a first-time visitor will learn, decide, do and receive. Compare that description with the source owner’s verified facts. If you cannot identify the action, find the missing link or unclear wording. This exercise reveals whether the page actually serves a reader.
Exercise 2
Exercise two: Inventory six visible strings: a heading, navigation item, button, form error, product or service description, and confirmation message. For each, record the source, target, owner and dependency. Identify which parts are free translation and which are technical or contractual facts. Then imagine the source changes tomorrow and determine whether the target edition will update safely.
Exercise 3
Exercise three: Follow a deep link in the source language and use the selector to change languages. Record the destination, not just its appearance. Repeat from a different page, from a collection or category, and from the browser’s address bar. Note whether the second language has a true counterpart, inherits content or returns to a default destination.
Exercise 4
Exercise four: Test one deliberately awkward phrase and one long piece of text. Examine wrapping at mobile width, keyboard access, language-sensitive punctuation and the intended action. Rewrite the phrase in natural target-language terms without altering what the action does. Ask a new reader to predict the next screen before interacting.
Exercise 5
Exercise five: Make one safe sample submission or purchase simulation under the target locale. Trace every status, error and acknowledgment, including any email or linked external service. Do not use real personal information in a test account. Write a concise defect report naming the expected result and actual failure. Correct the owner-controlled cause rather than translating around an unsupported function.
Exercise 6
Exercise six: Give a reviewer a localized page without its source and ask three questions: What does it offer? What limitations apply? What will happen after the next action? Compare their answers with the verified operational promise, then resolve any discrepancy. A reader-centered review tests understanding, while a word-for-word comparison tests only correspondence.
Useful glossary for this implementation
primary locale: The default language or language-and-region context used as the structural source for the site or storefront.
secondary locale: An additional language or regional edition whose content, publishing and routing should be checked on its own terms.
language selector: The control that changes what language a visitor sees, which may or may not retain the current deep-page context.
source text: The authorized statement from which meaning is carried into another language; it may contain facts that cannot be improvised.
localized override: A value explicitly authored for one locale instead of inherited from the source; it often needs independent maintenance.
fallback: The language, route or content shown when a requested translation does not exist or is unavailable.
publishing state: Whether a translation is only drafted, reviewed or actually accessible to the public.
CMS field: A structured content property used by a CMS or catalog, which may be a label, reference, description or technical identifier.
translated slug: The language-appropriate readable portion of a page URL, which is distinct from the whole platform route structure.
metadata: Information about a page such as search title, description and social preview, subject to locale-specific review.
accessibility label: Text that gives an assistive technology user the function or meaning of an element without depending on its visual appearance.
transactional message: An order, booking, account or service communication that may use a separate template or language-preference system.
Final release checklist, further reading and official sources
A complete release has accurate first-page text, a coherent language selector, reliable deep links, translated dynamic content where supported, honest regional claims, checked accessibility, correct search metadata, successful visitor tasks and tested communications. Every unsupported element should be identified rather than hidden behind an automatic translation score. The safest launch is smaller and complete, not larger and misleading.
Official product documentation used for this guide: https://docs.bigcommerce.com/developer/docs/storefront/catalyst/features/localization/multi-language/overview ; https://docs.bigcommerce.com/developer/docs/storefront/catalyst/features/localization/multi-language/setup ; https://docs.bigcommerce.com/developer/docs/storefront/stencil/themes/localization/stores ; https://docs.bigcommerce.com/developer/learn/courses/stencil-core/customizing/multi-language ; https://docs.bigcommerce.com/developer/docs/storefront/headless/products/faceted-textual-search ; https://docs.bigcommerce.com/developer/docs/b2b-edition/storefront/buyer-portal/localization ; https://docs.bigcommerce.com/developer/docs/storefront/catalyst/features/localization/multi-storefront/overview. Features may change by edition, plan or rollout. Confirm the current documentation and the actual platform configuration before making production changes.
For the broader learning architecture, read Master Art of Translation at https://edukatesg.com/2026/09/18/master-art-of-translation-complete-system-moving-meaning-between-languages/ and the Translate Like a Pro series index at https://edukatesg.com/translate-like-a-pro-series-index/. The next useful skill is to carry the same verification discipline into a different publishing platform without assuming its technical controls are identical.