payinOPERATIONS MANUAL

Latest articles

Stripe Checkout language: choose auto or an explicit locale, then translate your own copy

Decide when hosted Checkout should follow the browser or your storefront language, map supported locale codes, and keep product and custom-text translation separate.

Published; sources checked:

Hosted Checkout Session locale selection, supported-value mapping, merchant translation ownership, currency-format boundary and proposed QA scenarios; excludes custom-field answer processing, Elements runtime changes and currency conversion.

Choose a language policy, not just a locale value

A merchant reported a French Checkout page with English product names and descriptions; another developer asked where to set the locale when using inline price data. These are two different problems: selecting Stripe’s interface language and supplying merchant-owned copy.[6][7]

For hosted Checkout, use auto when following the browser is the intended experience. Use an explicit supported locale when the shopper has deliberately chosen a storefront language and you can supply matching product and custom text. This is an implementation recommendation, not a claim that one policy is right for every store.

What auto and an explicit locale actually control

The Session creation API says that a blank locale or auto uses the browser’s locale. Stripe’s hosted-page guide qualifies automatic translation with “if Stripe supports it” and says that the Session’s locale parameter overrides the browser locale.[1][4]

Put the parameter on the Checkout Session creation request, alongside mode and line_items, not inside price_data. The following is a request fragment, not a complete or executed integration.[1]

  • mode=payment
  • locale=fr
  • Select line_items server-side from your validated order.

For browser-led selection, replace fr with auto. A French storefront does not itself become a Session locale parameter: pass your resolved choice explicitly if that is your policy. Do not treat this hosted-Session guidance as instructions for changing an existing Elements instance.

Map storefront languages to supported API values

The documented enum includes en, en-GB, fr, fr-CA, es-419, pt-BR, zh, zh-HK and zh-TW, among other values. These are examples, not the complete list; consult the current API reference before building an allowlist.[1]

Recommended resolver: read the shopper’s explicit language preference, map it through a server-controlled configuration, check that the mapped code is supported, then select a reviewed content bundle. If a storefront uses en-US, for example, your application can deliberately map it to en; this is your mapping, not a documented promise that Stripe accepts every language tag.

For an unsupported storefront language, choose and explain a fallback you actually support, or deliberately use auto. Do not silently assume a particular fallback language or a precise browser language-list negotiation algorithm: the sources read here do not specify them. Keep raw browser input out of the API allowlist.

Separate interface translation from merchant copy

Stripe explicitly states that custom-field labels are not translated, and recommends using the Session locale to match their language. The product-data API separately accepts customer-facing name and description strings.[4][5] The community report illustrates why a localized interface is not evidence of a localized catalog.[6]

Recommended ownership split: let Checkout localize its own interface; maintain your own reviewed translations for product names, product descriptions, custom-field labels and additional merchant messages. Do not use locale as a catalog translation workflow. The cited product schema describes supplied strings, not a per-language translation dictionary.[5]

If you use saved Prices, review the associated product content instead of assuming an extra locale value rewrites it. If your integration already creates inline products, choose the translated product_data.name and, where applicable, product_data.description from your content bundle.[5] Avoid mutating a shared product name for each shopper; use a deliberate catalog design and preserve your internal SKU-to-order mapping. This is design guidance, not a recommendation to replace a working pricing model merely to translate copy.

Additional custom messages are merchant-authored content. Stripe documents supplying them through custom_text and prohibits text that conflicts with or makes Stripe-generated text ambiguous.[4] Review translations for meaning as well as language, especially around delivery and consent. This article does not cover collecting or processing custom-field answers.

Do not confuse formatting with currency selection

Checkout also uses locale for number and currency formatting. Stripe’s example keeps a EUR price unchanged while showing €25.00 with English and 25,00 € with German browser settings under auto.[4]

Therefore, treat display language, money formatting and the intended charge currency as separate acceptance checks. A German-looking amount is not proof that your integration changed currency, and a language code is not evidence of merchant country eligibility. Currency conversion, payment-method availability and settlement are outside this guide.

Proposed test matrix before release

The following scenarios are proposed tests, not performed tests or observed Stripe results. Use fresh test Sessions, record the browser language configuration and requested locale, and inspect both the hosted interface and merchant copy.

  • Auto / French browser / French bundle: check the documented browser-led interface behavior and confirm the supplied product and custom text are French.
  • Auto / English browser / French bundle: inspect the deliberately mismatched setup. Decide whether mixed language is acceptable; do not expect automatic translation of your custom labels.
  • Explicit fr / English browser / French bundle: check that the interface follows the explicit locale and that all merchant copy remains consistent.
  • Storefront en-US / mapped en: verify the resolver sends the supported mapped value, rather than forwarding the storefront tag unexamined.
  • Unsupported storefront language: verify your own fallback branch, the user-facing explanation and the matching content bundle. Separately observe unsupported browser-language behavior without predeclaring a Stripe fallback.
  • Same EUR item / en versus de: check separators and currency-symbol placement while confirming the intended amount and currency in the request.
  • Missing translation / language change before creation: verify the configured fallback is visible and the newly created Session uses one consistent language decision. Check long names and messages on a narrow screen.

For reproducibility, retain the Session ID, requested locale, content-bundle version and a redacted screenshot. Avoid logging secrets or payment details. These are recommended QA controls.

Scope, evidence and dates

This is documentation research for Stripe-hosted Checkout, verified September 23, 2026. No authenticated account, payment or browser-locale experiment was run. The community posts demonstrate concrete historical questions, not search volume or current API behavior. The official pages provide no publication or update dates in the retrieved text. Supported locales do not establish country-specific account or payment-method availability; no universal regional availability is claimed.

Sources and dates

More guides