How do you translate a Medusa v2 online store while keeping product descriptions, options, categories, carts and order records accurate across languages? Medusa’s Translation Module introduces explicit locale and resource translations in supported releases. The storefront must request the right locale, the customer must see the correct product information, and the cart and order must preserve the intended language without rewriting currency, inventory or fulfillment rules.
People searching for Medusa JS localization, Medusa v2 Translation Module setup, Medusa product translation, supported locales, x-medusa-locale header, multilingual Next.js storefronts, cart locale, translated product variants and order language need to understand version requirements and data flow. The translation feature is not an automatic rewrite of every screen. It involves configured resources, a request locale, fallback behavior and separate frontend interface messages. This guide explains those boundaries for developers, translators and global merchants.
The working route is to confirm a compatible Medusa version and the Translation Module configuration, enable and manage supported locales, translate the relevant catalog fields, and request localized content through the Store API or JS SDK. Then test catalog discovery, product options, cart creation and updates, order placement, transactional messages, market configuration and SEO. Preserve technical identifiers and transaction amounts. Publish only after a customer can follow one complete multilingual purchasing journey with the intended language recorded and the underlying commerce facts correct.
Quick answer: Medusa localization from module to completed order
Confirm the Medusa release and Translation Module prerequisites, configure supported locales, translate only the supported fields of real commerce resources, and request them through the Store API in the chosen locale. Test that the selected language reaches product lists, detail pages, option selectors and carts. When the cart locale is set correctly and the order is placed, verify how that language is represented in the order and notifications. Keep region, currency, price, tax, stock and shipping as their own commercial systems. The customer should get natural language without a change in what was purchased.
The important Medusa v2 distinctions
Medusa provides a Translation Module with documented version prerequisites and a feature-flagged configuration, separate store-supported locales and a request mechanism that can select translated fields. Its documentation explains default original-content fallback, `locale` query parameters, the `x-medusa-locale` header, JS SDK `setLocale`, and cart-to-order locale propagation. Custom storefront interface messages, search, SEO URLs and payment-provider language remain implementation work. These details are why copying generic advice from a different ecommerce platform can be misleading.
Detailed guide: practical lessons in translation, data and commerce
1. Version requirements come before configuration
Medusa documentation describes the Translation Module for Medusa v2.12.3 or later, behind a translation feature flag in the documented setup. Some related administration and custom-model capabilities have later minimum versions. Start with what the API actually sends, not what a screenshot suggests. A storefront can request the wrong locale or display an old value even when the translation record is correct.
A developer follows a tutorial from a newer release and cannot find the translation settings on an older Medusa application. Check the installed version and the current official guide before assuming a missing control is a localization bug. Capture the requested locale, resource identifier, returned value and the interface element that uses it.
Record the exact application version, enabled feature settings and migration state in the project notes. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
2. Translation Module is its own commerce capability
Medusa organizes its features into Commerce Modules. The Translation Module stores locale-specific values rather than copying an entire store into unrelated language-specific products. A reader’s language is not permission to change a product’s commercial meaning. Inventory, prices, payment state and eligibility have their own controls.
A team begins duplicating product data for each language even though the application can associate translations with existing resources. Use the Translation Module’s supported resource model and keep source product identity independent from its language-specific display. Check what the customer sees and what the transaction record stores before approving the result.
Retrieve one translated product and confirm the same underlying product ID and stock references. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
3. Feature flag and migrations need an owner
The documented Translation Module configuration involves adding its module, enabling the translation feature flag and applying relevant database migrations. These are deployment actions, not work for a copy editor. Look at the whole customer action, not just one string. The useful question is whether a visitor can choose, buy and understand the same product in the selected language.
An admin page says translations are unavailable because the backend has not been configured and migrated. Have a developer validate module configuration, feature flag and database state in staging before inviting translators to enter content. Use a normal state and a deliberate failure to expose missing translations and wrong fallback.
Confirm the module is operational and its API responds with supported locales before beginning a bulk translation. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
4. Locale codes follow BCP 47
Medusa locales use language-region codes such as en-US and fr-FR. The distinction matters when content differs among language communities, and codes should be configured deliberately. When something looks untranslated, diagnose configuration, resource coverage, request locale and cache separately. Changing prose in the wrong layer makes a site harder to maintain.
A storefront sends ‘fr’ while the store has enabled ‘fr-FR’, then interprets fallback text as a missing translation. Take supported locale codes from the Store API rather than inventing strings in frontend components. Write down the smallest repeatable example and the owner of the field or request.
Request both a configured and an unsupported locale and examine the expected behavior. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
5. Store-supported locales are a separate relation
The Store Module includes store locale relationships; actual locale details and translations belong to the Translation Module. A frontend can query available locales and offer a genuine selector. A complete translation journey crosses several boundaries: server response, frontend presentation, cart state and notification. The boundary often explains a bug that proofreading alone cannot fix.
A language menu lists eight choices from a hardcoded array while the backend supports only three. Build the selector from the configured store locales and display human-readable names that match the audience. Retest after refreshing and opening a direct URL so client-side state does not disguise the defect.
Compare the selector with `/store/locales` on every relevant environment after deployments. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
6. Translations reference stable resources
A Medusa translation record associates a locale with a resource reference and a resource ID. The translated fields are values of the same object, not a new SKU. Readers may arrive from search, shared links or an email rather than from the homepage. The locale must be understandable and stable through those entry points.
A product with translated descriptions is mistaken for a second stock item by an integration that uses display titles as keys. Use stable resource IDs and names as the integration key; keep human display text for the customer. Check direct navigation and the next click, including correct fallback where a translation is missing.
Inspect two locales for the same resource and confirm that inventory and variant identities remain unchanged. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
7. Choose translatable fields on purpose
Current module documentation enumerates fields for products, variants, options, categories and other supported data models. Not every field is automatically meaningful to translate. The correct source-of-truth is the resource and its business context. Natural phrasing matters, but it cannot excuse an altered material specification or missing restriction.
An editor sees material, subtitle and product title together and assumes numerical dimensions can be changed with prose. Mark each field translate, localize format, protect or business-review, and use the supported translation configuration for its data model. Use explicit evidence such as product ID, locale and order status rather than subjective confidence.
Diff the translated values against the source and check numeric or commercial facts for unauthorized changes. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
8. Product titles and descriptions are distinct tasks
A title helps the reader identify a product; the description explains use, contents, compatibility, material, limitations and any warnings. Both require review, but they solve different questions. Localizing a system is a continuing responsibility, not a one-time text import. New content and application features require language-aware regression.
The product name is naturally translated while the description still contains source-language instructions about cleaning and charging. Translate every customer-relevant clause and distinguish factual specifications from marketing style. Keep a review record that another team member could reproduce after the next deployment.
Have a target-language reviewer explain what the customer receives and what must not be done with the product. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
9. Category and collection labels guide discovery
Product categories and collections help visitors browse. Medusa’s Translation Module supports selected product-related resources, including category names and collection titles in documented releases. Start with what the API actually sends, not what a screenshot suggests. A storefront can request the wrong locale or display an old value even when the translation record is correct.
A French product page works when linked directly but cannot be found from the translated menu because its category is English. Translate the supported category and collection fields and review how the storefront constructs navigation labels and links. Capture the requested locale, resource identifier, returned value and the interface element that uses it.
Navigate from the home or category page to a product without a copied URL, checking language at each step. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
10. Product options and option values
Options such as size, fit and color must use coherent terms throughout the product detail page, variant selector, cart and order. Medusa supports option title and value translation in the documented model. A reader’s language is not permission to change a product’s commercial meaning. Inventory, prices, payment state and eligibility have their own controls.
A color value reads ‘marine’ on the French page but becomes ‘navy’ in the cart summary. Translate the supported option fields and examine which frontend components render each value. Check what the customer sees and what the transaction record stores before approving the result.
Select the same variant in two locales and compare the underlying variant ID and order item data. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
11. Variant descriptions and material fields
Variants can carry display fields that differ from the parent product, but their identifiers, prices and stock relationships remain technical. A localized title must not imply a different merchandise item. Look at the whole customer action, not just one string. The useful question is whether a visitor can choose, buy and understand the same product in the selected language.
A medium jacket variation gets an unrelated description copied from another size because editors keyed by visible label instead of variant ID. Match each translated variant field to its stable resource reference and review combinations in a controlled product. Use a normal state and a deliberate failure to expose missing translations and wrong fallback.
Complete one purchase of each tested option combination and reconcile it with backend records. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
12. Manage translations from Medusa Admin
Official Medusa Admin documentation shows Settings → Translations for applicable versions and allows individual or bulk resource translation. Some resource-management controls require newer versions. When something looks untranslated, diagnose configuration, resource coverage, request locale and cache separately. Changing prose in the wrong layer makes a site harder to maintain.
A translation is edited in a dashboard table but the target language is not supported by the store settings. Check supported locales, translatable resources and fields before using bulk operations; inspect saves and validation feedback. Write down the smallest repeatable example and the owner of the field or request.
Read back representative records through the Store API after making an Admin change. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
13. Custom models need explicit configuration
Medusa can extend translation capabilities to custom data models in supported versions, but the team must enable and expose them deliberately. A custom blog module does not become multilingual just because products are. A complete translation journey crosses several boundaries: server response, frontend presentation, cart state and notification. The boundary often explains a bug that proofreading alone cannot fix.
A store’s editorial guide remains English although product pages switch correctly to French. Review custom model definitions and translation configuration with the developer; decide which fields should be translatable. Retest after refreshing and opening a direct URL so client-side state does not disguise the defect.
Query one custom content record in two locales and confirm correct fallback and data identity. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
14. Understand original-content fallback
If a translation does not exist for the requested locale, Medusa’s documented behavior returns the original resource content. This avoids some empty pages but can hide missing language coverage. Readers may arrive from search, shared links or an email rather than from the homepage. The locale must be understandable and stable through those entry points.
A product title appears in French while the material field remains English because that field was not translated. Decide which fallback content is acceptable and whether high-risk product information should block release. Check direct navigation and the next click, including correct fallback where a translation is missing.
Remove a harmless translation in staging and observe the returned JSON and customer-facing rendering. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
15. JS SDK locale selection
Medusa’s JS SDK documents `setLocale`, which sends the chosen locale in the `x-medusa-locale` header for subsequent requests. The frontend must keep this state consistent through navigation. The correct source-of-truth is the resource and its business context. Natural phrasing matters, but it cannot excuse an altered material specification or missing restriction.
A user changes the language selector but subsequent product requests still use the previous locale. Set the locale through the supported SDK behavior and inspect actual request headers and responses. Use explicit evidence such as product ID, locale and order status rather than subjective confidence.
Navigate between product list, detail and category pages while verifying the requested locale. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
16. Direct Store API locale parameters
Clients that do not use the JS SDK can request translations with the `locale` query parameter or the `x-medusa-locale` header. The documented storefront behavior prioritizes the query parameter. Localizing a system is a continuing responsibility, not a one-time text import. New content and application features require language-aware regression.
A manual API test includes an old locale query parameter and a different header, making the result seem unpredictable. Inspect both sources of locale selection and choose one explicit strategy for application requests. Keep a review record that another team member could reproduce after the next deployment.
Send controlled requests with each method, and with both values, to verify the documented priority. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
17. Server-rendered storefront locale persistence
Server-side rendering can lose language context if cookies, URL state or request configuration are inconsistent. The official storefront guidance describes persisting locale in cookies in server environments. Start with what the API actually sends, not what a screenshot suggests. A storefront can request the wrong locale or display an old value even when the translation record is correct.
A Next.js product page renders French initially but changes to English when the server refreshes the route. Define how the selected locale reaches server components, API requests and client interactions. Capture the requested locale, resource identifier, returned value and the interface element that uses it.
Load a localized route directly, refresh it and move to another page while inspecting returned product content. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
18. Catalog content and frontend interface are separate
The Translation Module provides translated resource values; button labels, validation messages and error copy in a React or Next.js storefront still need frontend localization. A reader’s language is not permission to change a product’s commercial meaning. Inventory, prices, payment state and eligibility have their own controls.
The API returns a French product name but the add-to-cart button, account menu and address validation remain English. Translate functional UI strings in the frontend’s appropriate message system, keeping placeholders and accessible labels intact. Check what the customer sees and what the transaction record stores before approving the result.
Test normal, empty, invalid and failure states in each language rather than checking only one successful product page. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
19. Cart locale must match customer intention
Medusa documentation allows a cart to carry a locale that determines language of item contents. This matters when a visitor switches languages after creating a cart. Look at the whole customer action, not just one string. The useful question is whether a visitor can choose, buy and understand the same product in the selected language.
A buyer changes locale but the cart still displays earlier language item titles because its locale was never updated. Set locale on cart creation and update it where the customer legitimately changes language, without altering selected items. Use a normal state and a deliberate failure to expose missing translations and wrong fallback.
Read back the cart’s locale, item identities, prices and displayed labels after each language change. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
20. Order locale carries forward
Official guidance explains that the cart’s locale is copied to the placed order, supporting language-consistent item content. That makes accurate cart locale handling important before checkout. When something looks untranslated, diagnose configuration, resource coverage, request locale and cache separately. Changing prose in the wrong layer makes a site harder to maintain.
A completed order retains English item names even though the shopper purchased through a French-looking storefront. Verify the cart locale before placement and trace the order’s stored locale and item display. Write down the smallest repeatable example and the owner of the field or request.
Place controlled orders in two languages and compare the same product ID with the intended order language. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
21. Currency, region and market rules
A locale expresses language, not necessarily currency or tax jurisdiction. Medusa has separate region, pricing, sales-channel and fulfillment capabilities that should govern commercial rules. A complete translation journey crosses several boundaries: server response, frontend presentation, cart state and notification. The boundary often explains a bug that proofreading alone cannot fix.
A French-language user is shown euros simply because the frontend assumes a locale always determines currency. Configure market behavior through the appropriate Medusa commerce data and use translation only for explaining the actual conditions. Retest after refreshing and opening a direct URL so client-side state does not disguise the defect.
Compare list price, cart total, taxes, shipping and payment charge for the same configured market in two languages. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
22. Shipping, region and delivery claims
Translations should preserve the truth of delivery promises and country restrictions. A translated product field cannot make a carrier or fulfillment region available. Readers may arrive from search, shared links or an email rather than from the homepage. The locale must be understandable and stable through those entry points.
A localized page promises delivery within two days although that destination is outside the configured shipping area. Have a business owner approve target-language delivery claims and verify them against the current shipping options. Check direct navigation and the next click, including correct fallback where a translation is missing.
Test both eligible and rejected addresses, reading the message the customer actually receives. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
23. Errors, availability and empty states
A multilingual storefront needs understandable refusals as well as successful transactions. Backend errors and frontend validation may have different language sources. The correct source-of-truth is the resource and its business context. Natural phrasing matters, but it cannot excuse an altered material specification or missing restriction.
An out-of-stock item is translated beautifully, but the customer gets a raw English error after pressing add to cart. Test unavailable variants, invalid addresses, empty search results and failed checkout requests; map each string to its owner. Use explicit evidence such as product ID, locale and order status rather than subjective confidence.
Confirm that each message explains the problem without misrepresenting product availability or order status. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
24. Email and post-order communications
Transactional messages can be generated by notification modules, workflows or external mail providers. The order locale can inform language choice, but the integration must actually use it. Localizing a system is a continuing responsibility, not a one-time text import. New content and application features require language-aware regression.
A French order stores fr-FR while its dispatch email is rendered by a source-language template. Pass the intended locale to the notification renderer, review dynamic values and keep legal claims approved for the market. Keep a review record that another team member could reproduce after the next deployment.
Capture confirmation and shipping messages in real inboxes, comparing order totals, item names and policy links. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
25. International SEO and route selection
Medusa supplies commerce data, but localized route paths, metadata, canonical URLs and hreflang are implemented by the storefront. An SDK locale choice alone does not create indexable language pages. Start with what the API actually sends, not what a screenshot suggests. A storefront can request the wrong locale or display an old value even when the translation record is correct.
A French product can be seen after clicking a language menu but search bots receive only the default-language route and metadata. Design stable public language URLs and render correct language attributes, alternate links and product metadata on the server. Capture the requested locale, resource identifier, returned value and the interface element that uses it.
Open local routes directly and inspect rendered HTML rather than relying on client-side language state. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
26. Catalog search and filters
Search engines and filters may index original values or translated fields depending on the integration. A language selector does not guarantee language-specific discovery. A reader’s language is not permission to change a product’s commercial meaning. Inventory, prices, payment state and eligibility have their own controls.
A reader searches the French term for a product but the index only recognizes its English title. Determine how search consumes localized product data, reindex where necessary and review terms used in facets. Check what the customer sees and what the transaction record stores before approving the result.
Compare a translated product’s direct URL with search and category discovery in the target language. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
27. Cache, stale translations and updates
Translated content can be cached by locale, route or resource. A source revision and target translation may propagate through different paths in a deployed storefront. Look at the whole customer action, not just one string. The useful question is whether a visitor can choose, buy and understand the same product in the selected language.
An editor updates an important safety note but a cached French page continues presenting the previous wording. Trace source changes through translation review, API response and cached rendering; invalidate correct locale keys. Use a normal state and a deliberate failure to expose missing translations and wrong fallback.
Update one controlled test field and confirm the new value appears consistently on listing, detail and cart. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
28. Release gates and responsibilities
An effective multilingual launch separates linguistic review, API behavior, commercial facts, legal claims and accessibility. The translator should not be expected to approve payment or stock logic. When something looks untranslated, diagnose configuration, resource coverage, request locale and cache separately. Changing prose in the wrong layer makes a site harder to maintain.
A language is marked complete because 100 percent of selected product fields are translated, but checkout still contains an ambiguous consent request. Assign content, technical, commerce and compliance owners to the parts they understand and make critical omissions block release. Write down the smallest repeatable example and the owner of the field or request.
Keep a concise test record with locale, product ID, cart ID, order ID and expected result. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
29. Monitoring following updates
Feature development, storefront changes and new modules can introduce translatable resources or messages after the original release. International readiness needs continued review. A complete translation journey crosses several boundaries: server response, frontend presentation, cart state and notification. The boundary often explains a bug that proofreading alone cannot fix.
A new discount feature adds an untranslated eligibility explanation while all established product translations remain correct. Add localization checks to version upgrades and review customer complaints by language and stage of shopping. Retest after refreshing and opening a direct URL so client-side state does not disguise the defect.
Re-run a small representative set of end-to-end tests after deployment and confirm the underlying issue was resolved. Keep a record of the precise locale, resource or order ID, API result and rendered screen. The correction is ready only when language and commerce data describe the same event without contradiction.
Common Medusa localization situations and fixes
An international release should be tested under ordinary customer conditions, including mistakes. The following cases distinguish missing translations from locale request problems, frontend ownership and actual commerce rules.
Situation 1: Translation controls are missing from Admin
The deployed Medusa version or feature flag may not support the documented translation UI. Find the narrowest reproducible request first, including Medusa version, locale and resource ID. Then determine whether the mismatch is in backend translation data, API request selection or frontend rendering.
Check version requirements, module enablement and migrations before asking a translator to solve the problem. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 2: `fr-FR` request returns English
The translation may not exist or the locale was not actually passed to the Store API. Do not alter product identity or commercial conditions as a language workaround. Inspect the relevant API response and saved cart or order state before accepting the correction.
Compare a direct API response with SDK request headers and inspect supported locales. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 3: Category is translated but product remains English
Different resource types have separate translation records and fields. Test from a clean session and also after switching languages during a purchase. The most useful evidence is a complete sequence of visible text and backend records.
Review the product translation fields, requested locale and fallback behavior. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 4: A French title becomes English after refresh
The server-rendered route is missing locale context or reverts to the default SDK state. Repeat the corrected behavior in another supported locale and after a direct page reload. That extra comparison catches hidden state and caching problems that a one-screen check misses.
Trace cookies, URL state, server components and locale headers through a direct page request. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 5: Variant option is inconsistent in cart
Product option values may be translated while the cart’s stored locale remains unchanged. Find the narrowest reproducible request first, including Medusa version, locale and resource ID. Then determine whether the mismatch is in backend translation data, API request selection or frontend rendering.
Inspect the selected variant ID and update the cart locale without changing the purchased item. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 6: Two items in one order use different languages
Cart locale or stale item data may have changed during the browsing session. Do not alter product identity or commercial conditions as a language workaround. Inspect the relevant API response and saved cart or order state before accepting the correction.
Test cart creation, locale updates and order placement against the documented locale propagation. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 7: A target-language email is still English
The notification system is not using the order locale. Test from a clean session and also after switching languages during a purchase. The most useful evidence is a complete sequence of visible text and backend records.
Read order locale data and check the language selection of the actual mail renderer. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 8: A local currency is guessed from locale
The frontend confuses language with commercial region or pricing. Repeat the corrected behavior in another supported locale and after a direct page reload. That extra comparison catches hidden state and caching problems that a one-screen check misses.
Verify the Medusa region, price and payment amount independently of the selected language. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 9: Translation of a warning is omitted
The translated resource field is empty or truncated, causing a misleading product description. Find the narrowest reproducible request first, including Medusa version, locale and resource ID. Then determine whether the mismatch is in backend translation data, API request selection or frontend rendering.
Compare factual instructions and safety clauses before allowing the localized product to sell. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 10: Untranslated text appears only on an error
A frontend message or external payment provider owns the failing string. Do not alter product identity or commercial conditions as a language workaround. Inspect the relevant API response and saved cart or order state before accepting the correction.
Trigger the error in a controlled test and identify the real message owner. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 11: A custom blog post does not translate
Custom data-model translation was not configured or exposed in the deployed version. Test from a clean session and also after switching languages during a purchase. The most useful evidence is a complete sequence of visible text and backend records.
Use the applicable custom-model guide and verify a localized API response. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 12: The language menu lists unsupported choices
The UI uses a hardcoded list rather than Store-supported locale data. Repeat the corrected behavior in another supported locale and after a direct page reload. That extra comparison catches hidden state and caching problems that a one-screen check misses.
Fetch `/store/locales` and confirm selector choices reflect actual backend configuration. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 13: Product search cannot find French terms
The external index may use original product text regardless of the selected locale. Find the narrowest reproducible request first, including Medusa version, locale and resource ID. Then determine whether the mismatch is in backend translation data, API request selection or frontend rendering.
Examine indexing strategy and test natural queries after language-aware indexing. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 14: A translated product URL is not indexable
The language exists only in client-side state, without stable crawlable routes. Do not alter product identity or commercial conditions as a language workaround. Inspect the relevant API response and saved cart or order state before accepting the correction.
Implement and test proper server-rendered locale routes, canonical and alternate links. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 15: Long text hides checkout consent
A target-language string expands beyond the layout and covers a required notice. Test from a clean session and also after switching languages during a purchase. The most useful evidence is a complete sequence of visible text and backend records.
Test narrow screens, keyboard focus and label readability without dropping consent meaning. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Situation 16: An update invalidates only one locale cache
Resource changes may be reflected in one route but remain stale in another. Repeat the corrected behavior in another supported locale and after a direct page reload. That extra comparison catches hidden state and caching problems that a one-screen check misses.
Trace cache keys and invalidation for every supported language and compare API with rendered output. The reviewer should be able to repeat the test, observe the correction and confirm that the underlying order or product data remain trustworthy.
Worked example: a home appliance bought in English and French
Imagine one appliance product with two variants and a set of approved electrical specifications. The business wants English (United States) and French (France) displays. Start with Medusa’s supported locales and the actual product and variant records. Translate the title, subtitle, material and description only where those fields are supported and appropriate. Do not change technical identifiers, voltage ratings or price because the text is in another language. Translate the relevant category, options and option values. An independent reviewer should confirm that the same compatibility warning appears in each language and has not been softened or omitted.
Build the storefront language selector from available locales and request products with the intended locale. Test both the JS SDK path and, where necessary, an explicit Store API request using a query parameter or header. Check that a direct localized URL and a page refresh obtain the correct content. Then choose a known variant and add it to a cart whose locale is the selected language. Switch language during browsing and verify the cart’s intended locale rather than silently changing which product was selected. The cart should keep its identity and monetary facts; language determines how supported item contents are presented.
Place an authorized test order, read back the saved locale and compare the item with the source-language order. Test an unsupported shipping address and an out-of-stock option to expose errors. Capture confirmation and shipping messages, and verify that the notification integration actually uses the order’s intended language. Finally check indexable locale routes, metadata and alternate links in rendered output. The project is ready when the customer understands the entire journey, the order accurately records what happened and the site remains reliable when the language is switched or a request fails.
Four-week release and learning plan
Week one: review Medusa’s deployed version, Translation Module feature flag, migrations and store locales. Make a field inventory for products, variants, options, categories and custom models. Decide which strings belong to backend translations and which belong to frontend UI. Choose a single product with multiple options and record the expected commerce outcome.
Week two: create and review translations through the supported administration and API mechanisms. Configure storefront locale selection and verify product list, detail, category and variant responses. Inspect both query-parameter and header behavior if your clients use them. Deliberately request a missing translation to learn how fallback appears on your actual frontend.
Week three: carry the locale through cart creation, language changes, checkout, order placement and notifications. Test valid and invalid addresses, unavailable stock, payment cancellation and errors. Confirm region and price calculations with commerce owners. Keep product IDs, variant IDs, financial amounts and shipping eligibility protected from editorial changes.
Week four: evaluate direct URLs, server rendering, canonical and alternate metadata, language-specific search and responsive accessibility. Run one full order in each language and compare it with backend records. Add regression tests for locale state and newly added resources. Launch the first fully trustworthy language journey before translating the entire catalog.
Frequently asked questions
Is Medusa translation available in every v2 installation? No. Check the documented minimum version and the Translation Module’s feature flag and migrations. Particular administrative and custom-model functions may need later versions.
Does the language selector change price? It should not change price merely because a locale changed. Currency, region and pricing are commerce concerns, which can have their own legitimate rules.
Why is a product still in English after requesting French? The translation might not exist, the locale request may be wrong or the content may be coming from the frontend rather than the translated resource. Medusa documents fallback to the original content.
How does the cart remember language? The cart can carry a locale; official documentation describes setting or updating it and copying that locale to the placed order.
Does `setLocale` translate buttons in Next.js? No. It controls locale selection for supported Medusa API content. Frontend functional messages still need their own internationalization strategy.
Official Medusa documentation and wider translation study
Medusa Translation Module; Translation Concepts; Storefront Localization; Serve Translations in the Storefront; Manage Translations in Medusa Admin; Custom Data-Model Translations. Review the requirements listed on each page against the exact deployed release.
For the larger principles of transferring meaning accurately across languages, read Master Art of Translation | The Complete System for Moving Meaning Between Languages. Further platform guides are in the Translate Like a Pro | Series Index.