Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

How-to Guide: Set Up Multiple languages (#13923)

jaburghes330c11965f1a
diff --git a/docs/docs.json b/docs/docs.json
index 0cc4d48f7d..318e5a386e 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -612,6 +612,7 @@
"group": "How-to Guides",
"pages": [
"user/how-to/multi-currency-pricing",
+ "user/how-to/multiple-languages",
"user/how-to/multi-region-pricing",
"user/how-to/wholesale-pricing",
"user/how-to/volume-pricing",
@@ -749,14 +750,6 @@
"use-case/digital-products/admin-capabilities"
]
},
- {
- "group": "ChatGPT Integration",
- "pages": [
- "use-case/chatgpt-integration/chatgpt-shopping",
- "use-case/chatgpt-integration/chatgpt-instant-checkout",
- "use-case/chatgpt-integration/chatgpt-buyer-experience"
- ]
- },
{
"group": "Multi-Store Platform",
"pages": [
diff --git a/docs/images/user/how-to/multiple-languages/1-markets-overview.png b/docs/images/user/how-to/multiple-languages/1-markets-overview.png
new file mode 100644
index 0000000000..3fcff72c72
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/1-markets-overview.png differ
diff --git a/docs/images/user/how-to/multiple-languages/2-translations-overview.png b/docs/images/user/how-to/multiple-languages/2-translations-overview.png
new file mode 100644
index 0000000000..cb7364ffb3
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/2-translations-overview.png differ
diff --git a/docs/images/user/how-to/multiple-languages/3-import-panel.png b/docs/images/user/how-to/multiple-languages/3-import-panel.png
new file mode 100644
index 0000000000..730dacb5d3
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/3-import-panel.png differ
diff --git a/docs/images/user/how-to/multiple-languages/4-translation-drawer.png b/docs/images/user/how-to/multiple-languages/4-translation-drawer.png
new file mode 100644
index 0000000000..3285f2d121
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/4-translation-drawer.png differ
diff --git a/docs/images/user/how-to/multiple-languages/5-category-configurator.png b/docs/images/user/how-to/multiple-languages/5-category-configurator.png
new file mode 100644
index 0000000000..28927920b0
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/5-category-configurator.png differ
diff --git a/docs/images/user/how-to/multiple-languages/6-category-translations-panel.png b/docs/images/user/how-to/multiple-languages/6-category-translations-panel.png
new file mode 100644
index 0000000000..31ba7633cb
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/6-category-translations-panel.png differ
diff --git a/docs/images/user/how-to/multiple-languages/7-policy-editor.png b/docs/images/user/how-to/multiple-languages/7-policy-editor.png
new file mode 100644
index 0000000000..f4a1848aa6
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/7-policy-editor.png differ
diff --git a/docs/images/user/how-to/multiple-languages/8-policy-translations-panel.png b/docs/images/user/how-to/multiple-languages/8-policy-translations-panel.png
new file mode 100644
index 0000000000..7a2aa5c6f2
Binary files /dev/null and b/docs/images/user/how-to/multiple-languages/8-policy-translations-panel.png differ
diff --git a/docs/use-case/chatgpt-integration/chatgpt-buyer-experience.mdx b/docs/use-case/chatgpt-integration/chatgpt-buyer-experience.mdx
deleted file mode 100644
index 0d1729ee9e..0000000000
--- a/docs/use-case/chatgpt-integration/chatgpt-buyer-experience.mdx
+++ /dev/null
@@ -1,69 +0,0 @@
----
-title: "ChatGPT Buyer Experience"
-description: "Learn how ChatGPT makes shopping smarter, faster, and more intuitive for your customers."
----
-
-Shopping through ChatGPT is a new, conversational way to explore, compare, and purchase products without ever leaving the AI chat. Spree Commerce merchants that integrate with ChatGPT gain access to millions of high-intent customers who are actively seeking product recommendations and are ready to buy.
-
-This guide outlines how the buyer experience unfolds inside ChatGPT - from discovery to purchase - and how it offers a fast, intuitive, and personalized path to conversion.
-
-## Conversational Discovery
-
-ChatGPT acts as a product discovery engine powered by natural language. Shoppers simply describe what they’re looking for - no filters, dropdowns, or long search result pages:
-
-- **Intent-Driven Search** - Users can phrase queries like “best vegan skincare under \$50” or “eco-friendly baby gifts” and receive product results tailored to their needs, not based on ads or bidding.
-- **Side-by-Side Recommendations** - Multiple products from different brands may appear, giving users a comparison experience similar to asking a trusted friend.
-- **No Ads, No Distractions** - Discovery is based on relevance and product data, not promotions or rankings.
-
-## Seamless Product Evaluation
-
-Once a product is recommended, users can interact with it directly inside ChatGPT:
-
-- **Inline Previews** - View product images, titles, prices, and short descriptions without clicking away.
-- **Full Product Details on Demand** - Users can ask follow-up questions (e.g. “Is this waterproof?” or “Does it come in black?”) and ChatGPT pulls this information from the product feed automatically.
-- **Personalized Assistance** - The agent can recommend other items based on previous questions or refine suggestions based on user preferences.
-
-## Instant Checkout with Stripe
-
-When a user is ready to buy, they can complete the purchase instantly inside the chat interface:
-
-- **Frictionless Checkout** - Stripe’s built-in payment flow allows logged-in ChatGPT users to complete checkout in a few taps using their saved payment and shipping info.
-- **No Account Required** - There's no need to create a new customer account. Checkout is handled natively in ChatGPT and passed securely to your store.
-- **Full Transparency** - Users see product details, taxes, and shipping fees clearly before placing the order.
-
-## Secure, Verified Transactions
-
-- **Powered by Stripe** - Payments are processed securely through Stripe with PCI compliance, fraud protection, and full support for refunds.
-- **Trusted AI Infrastructure** - Orders are passed directly to your Spree backend via the Agentic Commerce Protocol (ACP), which ensures order integrity and proper attribution.
-
-## Post-Purchase Ownership
-
-- **Merchants Own the Relationship** - After checkout, the customer is directed to the merchant’s fulfillment, email, and support systems, allowing you to manage returns, refunds, and follow-up communications as you normally would.
-- **Customer Receives Standard Emails** - Order confirmation, shipping updates, and transactional emails come directly from your store, preserving brand continuity.
-- **Repeat Purchases Made Easy** - Customers who bought through ChatGPT once can easily return and buy again using conversational prompts and saved preferences.
-
-## Benefits for Shoppers
-
-- **Smarter Shopping** - ChatGPT answers follow-up questions, gives comparisons, and makes product research feel natural and intuitive.
-- **Faster Decision-Making** - Shoppers go from search to purchase in minutes, without multiple tabs, forms, or decision fatigue.
-- **Safe & Seamless Checkout** - No pop-ups or redirects. Just one smooth, secure flow powered by Stripe and owned by you.
-- **Personalization at Scale** - ChatGPT tailors suggestions in real-time based on the shopper’s needs across categories, price points, or styles.
-
-## The Result
-
-ChatGPT makes buying feel more like asking for advice. By integrating with ChatGPT Instant Checkout, Spree merchants give customers a fast, helpful, and trustworthy way to discover and buy, while maintaining full control over the order lifecycle and customer relationship.
-
-## Get Started
-
-<Columns cols={2}>
- <Card title="Book a Demo" icon="eye" href="https://getvendo.com/book-a-demo/" cta="Click here">
- Schedule a demo to explore the platform and get your questions answered
- </Card>
- <Card title="Ask for Pricing" icon="dollar-sign" href="https://spreecommerce.org/get-started/" cta="Click here">
- See Enterprise pricing for your use case
- </Card>
-</Columns>
-
-## Further Reading
-- [<u>ChatGPT Shopping</u>](https://spreecommerce.org/docs/use-case/chatgpt-integration/chatgpt-shopping)
-- [<u>ChatGPT Instant Checkout</u>](https://spreecommerce.org/docs/use-case/chatgpt-integration/chatgpt-instant-checkout)
\ No newline at end of file
diff --git a/docs/use-case/chatgpt-integration/chatgpt-instant-checkout.mdx b/docs/use-case/chatgpt-integration/chatgpt-instant-checkout.mdx
deleted file mode 100644
index 2947c64bde..0000000000
--- a/docs/use-case/chatgpt-integration/chatgpt-instant-checkout.mdx
+++ /dev/null
@@ -1,90 +0,0 @@
----
-title: "ChatGPT Instant Checkout"
-description: "Learn how to leverage ChatGPT Instant Checkout with Spree Commerce."
----
-
-Spree Commerce Enterprise Edition supports the Agentic Commerce Protocol (ACP), enabling merchants to participate in ChatGPT Instant Checkout and other emerging AI eCommerce opportunities.
-
-With structured feeds, seamless checkout, and full ownership of fulfillment and customer data, Spree gives merchants everything they need to power conversational commerce, without compromising flexibility, privacy, or brand control.
-
-## Admin Capabilities
-
-As a merchant or platform admin, you control how your products are presented to ChatGPT and how transactions are handled behind the scenes. With Spree, you can tailor every layer of the agentic commerce flow to match your operational setup and business goals.
-
-### AI-Ready Product Feeds
-
-- Generate structured product feeds compliant with ACP and other conversational commerce protocols.
-- Automatically expose core product data (name, description, price, image, variants, etc.).
-- Use metafields to enrich product records with AI-friendly, queryable attributes (e.g., “eco-friendly,” “carry-on size,” “for sensitive skin,” etc.).
-
-### Product Discovery Optimization
-
-- Add searchable properties or tags to make products easier to match with ChatGPT queries.
-- Use metafields to define logic such as product use cases, customer types, target demographics, or recommended contexts.
-- Group products into pre-defined collections to increase their discoverability in common buyer journeys (e.g. gifts under \$50, back-to-school).
-
-### Checkout & Payments Integration
-
-- Enable Instant Checkout using Spree’s built-in Stripe integration, fully compliant with ACP specs.
-- Support one-click purchasing directly from the chat interface, even for guest users.
-- Manage inventory, pricing, and availability across all channels, including ChatGPT.
-
-### Order Handling & Fulfillment
-
-- Orders placed via ChatGPT appear directly in the Spree admin dashboard for normal processing.
-- Fulfill, track, and manage these orders just like any other, with no extra complexity.
-- Support post-purchase flows (returns, refunds, customer messaging) under your control.
-
-### Inventory & Catalog Rules
-
-- Choose which products, variants, or collections should be eligible for conversational commerce.
-- Automatically update feed content based on stock levels, lead times, or regional availability.
-
-### Data Ownership & Insights
-
-- You own all customer data, order history, and interaction logs.
-- Spree allows you to segment and analyze ChatGPT-attributed orders like any other sales channel.
-
-## Customer Experience
-
-Buyers interacting with your brand via ChatGPT will experience a fast, intuitive, and AI-guided shopping flow - powered entirely by your Spree backend.
-
-### Natural Discovery
-
-- Customers describe what they’re looking for in their own words (e.g. “a vegan skincare set for dry skin under \$75”), and ChatGPT presents relevant products.
-- Products are ranked by relevance (not paid placement) ensuring a high-quality shopping experience.
-
-### Seamless Shopping
-
-- View product details, pricing, images, reviews, and comparisons directly within the conversation.
-- Initiate a secure checkout without ever leaving the chat.
-
-### Frictionless Checkout
-
-- Stripe powers the transaction, enabling one-click purchases via saved payment methods.
-- Orders are confirmed instantly, and customers receive confirmation just like any other ecommerce flow.
-
-### Post-Purchase Relationship
-
-- The merchant handles all post-purchase interactions: shipping notifications, returns, support, upsells.
-- Buyers benefit from consistent customer service and brand experience across every channel.
-
-### Unified Account & Order History
-
-- For returning customers, Spree supports unified accounts and saved payment methods that work across ChatGPT and your traditional storefront.
-- Customers can manage orders and preferences from their standard dashboard if logged in.
-
-## Get Started
-
-<Columns cols={2}>
- <Card title="Book a Demo" icon="eye" href="https://getvendo.com/book-a-demo/" cta="Click here">
- Schedule a demo to explore the platform and get your questions answered
- </Card>
- <Card title="Ask for Pricing" icon="dollar-sign" href="https://spreecommerce.org/get-started/" cta="Click here">
- See Enterprise pricing for your use case
- </Card>
-</Columns>
-
-## Further Reading
-- [<u>ChatGPT Shopping</u>](https://spreecommerce.org/docs/use-case/chatgpt-integration/chatgpt-shopping)
-- [<u>ChatGPT Buyer Experience</u>](https://spreecommerce.org/docs/use-case/chatgpt-integration/chatgpt-buyer-experience)
\ No newline at end of file
diff --git a/docs/use-case/chatgpt-integration/chatgpt-shopping.mdx b/docs/use-case/chatgpt-integration/chatgpt-shopping.mdx
deleted file mode 100644
index deb7ed8b53..0000000000
--- a/docs/use-case/chatgpt-integration/chatgpt-shopping.mdx
+++ /dev/null
@@ -1,89 +0,0 @@
----
-title: "ChatGPT Shopping"
-description: "Learn how ChatGPT Shopping works with Spree Commerce."
----
-
-Spree Commerce Enterprise Edition gives your ecommerce business the tools to sell products directly through the ChatGPT chatbot, one of the fastest-growing AI search and discovery platforms in the world.
-
-With ChatGPT Shopping, customers can find your products in real-time AI conversations and checkout instantly - all without leaving the chat. Spree supports this next-generation shopping experience with powerful product feeds, seamless Stripe payments, and full control over fulfillment, data, and customer relationships.
-
-This new channel is powered by the Agentic Commerce Protocol (ACP), an open-source standard developed by OpenAI and Stripe. The result is simple: a smarter, more conversational way to shop.
-
-## How does ChatGPT Shopping Work?
-
-ChatGPT Shopping is a new way for users to discover and buy products directly inside a ChatGPT conversation. Instead of visiting a website, buyers ask for what they need and ChatGPT recommends products that match, based on real product data from merchants.
-
-Here’s how it works:
-
-1. **Discovery**: A user asks ChatGPT for a product recommendation, like “best noise-canceling headphones under \$200.”
-2. **Selection**: ChatGPT shows a few options with pricing, images, and reviews - including products from your store.
-3. **Checkout**: If your store supports Instant Checkout, users can purchase directly in the chat via a secure Stripe checkout flow.
-4. **Fulfillment**: You process the order like normal and retain full ownership of the customer relationship.
-
-It’s a frictionless experience that turns search into sales.
-
-## Why Choose the ChatGPT Shopping Model?
-
-### Reach New Customers Where They’re Already Searching
-
-Millions of people are already using ChatGPT to explore product options. By making your store’s catalog available through ChatGPT, your products become eligible for inclusion - no ads, bidding, or rankings required. This is a free service.
-
-### Convert Conversations into Checkouts
-
-ChatGPT Shopping enables a direct buying experience with Instant Checkout. Shoppers can view, compare, and buy products, all without visiting a storefront or navigating a cart.
-
-### Maintain Ownership & Fulfillment Control
-
-You fulfill the order, own the customer data, and manage post-purchase support. The customer relationship remains 100% yours.
-
-### Only Pay for Performance
-
-There’s no cost to get your products in front of the ChatGPT users. You only pay a small fee when a sale is made, which is refunded in case of a return.
-
-## Use Cases and Scenarios
-
-- **B2C brands** - Tap into ChatGPT’s massive user base to get discovered organically for free. Shoppers searching for “best wireless earbuds under \$100” could land directly on your product.
-- **Gifting and product discovery** - Buyers browsing for gifts or ideas (“eco-friendly skincare gifts for under $50”) are more likely to convert when the entire process is seamless and instant.
-- **International expansion** - With ChatGPT’s multilingual capabilities, brands can reach global audiences and serve curated suggestions based on the buyer’s location or language.
-- **Sustainable or value-based businesses** - Appear in relevance-based results like “eco-friendly backpacks.”
-- **High-value product lines** - Ideal for premium or considered purchases (like luxury goods or electronics), where ChatGPT can guide shoppers through research and comparison before completing an instant checkout.
-- **Niche catalogs** - Products that benefit from natural language search, e.g., “hiking gear for wet climates” or “skincare for sensitive skin.”
-
-## Challenges & Considerations
-
-While the opportunity is significant, conversational commerce is still evolving. Merchants should consider:
-
-- **Data Structuring** - To appear in ChatGPT results, your product data needs to be complete, structured, and informative. That includes:
- - Rich descriptions
- - Accurate pricing and stock levels
- - Descriptive attributes (e.g., color, material, audience)
- - High-quality images
-- **Feed Management** - Keeping feeds up to date with pricing, inventory, and variants is essential for a frictionless buyer experience.
-- **Customer Experience**- While the AI handles product discovery, your brand still needs to ensure fulfillment, support, and loyalty workflows are seamless.
-- **Payment Setup** - Stripe is required for Instant Checkout. You’ll need to set up your Stripe account to work with ACP and handle payouts and refunds.
-
-## How Spree Supports ChatGPT Shopping
-
-Spree Commerce Enterprise Edition provides everything needed to participate in ChatGPT Instant Checkout and the ACP ecosystem:
-
-- **ACP Product Feed Integration** - Spree automatically generates and maintains a structured product feed compatible with ACP.
-- **Instant Checkout Support** - Stripe-based checkout flows are integrated and compliant with ACP specifications.
-- **Metafields** - Use metafields to enrich product records with AI-friendly, queryable attributes (e.g., “eco-friendly,” “carry-on size,” “for sensitive skin,” etc.).
-- **Full Ownership** - You host the storefront, own the customer relationship, and maintain full control over your data and brand.
-- **Extensibility** - Build custom logic, filters, and product eligibility rules to fine-tune how and when your products are included.
-- **No Lock-In** - Because ACP is an open protocol, your team or agency partners can extend the integration as needed, without relying on a third-party middleware.
-
-## Get Started
-
-<Columns cols={2}>
- <Card title="Book a Demo" icon="eye" href="https://getvendo.com/book-a-demo/" cta="Click here">
- Schedule a demo to explore the platform and get your questions answered
- </Card>
- <Card title="Ask for Pricing" icon="dollar-sign" href="https://spreecommerce.org/get-started/" cta="Click here">
- See Enterprise pricing for your use case
- </Card>
-</Columns>
-
-## Further Reading
-- [<u>ChatGPT Instant Checkout</u>](https://spreecommerce.org/docs/use-case/chatgpt-integration/chatgpt-instant-checkout)
-- [<u>ChatGPT Buyer Experience</u>](https://spreecommerce.org/docs/use-case/chatgpt-integration/chatgpt-buyer-experience)
\ No newline at end of file
diff --git a/docs/user/how-to/multiple-languages.mdx b/docs/user/how-to/multiple-languages.mdx
new file mode 100644
index 0000000000..86892f195c
--- /dev/null
+++ b/docs/user/how-to/multiple-languages.mdx
@@ -0,0 +1,96 @@
+---
+title: "Set Up Multiple Languages"
+description: "Learn how to sell in multiple languages by configuring locales, translating products, categories, and policies in Spree Commerce."
+---
+
+Spree lets you present your store in multiple languages — so customers in France see content in French, customers in Germany see content in German, and so on. Languages are tied to your Markets configuration, which means you set up a locale per market and then translate your content to match.
+
+In this guide, we'll walk through enabling additional languages, translating your product catalog in bulk using the translations importer, and making manual adjustments to individual products, categories, and store policies.
+
+## 1. Set Up Markets with Additional Locales
+
+Languages in Spree are configured through Markets. Each market has a **Default Locale** — the language customers see when they browse that market. Before any translation work can begin, you need at least one market set up with a non-default locale.
+
+Navigate to **Settings → Markets** and click **New Market** for each region you want to add.
+
+![The Markets overview page showing multiple configured markets with different locales](/docs/images/user/how-to/multiple-languages/1-markets-overview.png)
+
+When creating or editing a market, set the following:
+
+- **Default Locale** — the primary language for this market (e.g., `FR` for French, `DE` for German)
+- **Supported Locales** — any additional languages customers can switch to within that market
+
+<Note>Before you can set up a Market for a country, make sure that country is included in a configured Zone. See [<u>Settings → Zones</u>](https://spreecommerce.org/docs/user/settings/zones) for setup instructions.</Note>
+
+Click **Create** once you've configured the new market. Once your markets are saved, the locales you've configured will appear in the **Products → Translations** page, ready for you to start filling in translated content.
+
+## 2. Translate Products in Bulk Using the Translations Importer
+
+The fastest way to translate a large product catalog is to export your existing content, fill in the translations, and import it back. Navigate to **Products → Translations**.
+
+![The Translations overview page showing coverage by locale and translation status per product](/docs/images/user/how-to/multiple-languages/2-translations-overview.png)
+
+The coverage table at the top shows you how many products have been translated for each locale, so you can track your progress at a glance.
+
+### Export your catalog for translation
+
+Click **Export** in the top-right corner, then confirm by clicking **Export** in the modal. A download link will be sent to your admin email address. The exported file contains your product content in your default language, with empty columns for each additional locale — ready to be filled in.
+
+### Fill in the translations
+
+Open the exported CSV file and fill in the translated content for each locale column. This includes product names, descriptions, and any other translatable fields. Save the file when done.
+
+### Import the translated file
+
+Click **Import** in the top-right corner to open the import side panel.
+
+![The import side panel for bulk translations](/docs/images/user/how-to/multiple-languages/3-import-panel.png)
+
+1. Drag and drop your translated CSV file into the upload area, or click **browse files** to select it.
+2. Select the delimiter used in your file (comma, pipe, semicolon, or tab).
+3. Click **Create** to proceed to the field mapping step.
+4. Review the field mapping and adjust any columns that weren't automatically matched, then click **Continue** to submit.
+
+Once submitted, you'll be taken to a progress screen where you can monitor the import. Any rows with errors will be flagged with a message so you can fix and re-import them.
+
+## 3. Manually Translate Individual Products
+
+For one-off adjustments, the quickest way is to update translations directly from **Products → Translations**. Find the product in the list and click its name to open the translation drawer.
+
+![The translation drawer open for an individual product showing fields for each locale](/docs/images/user/how-to/multiple-languages/4-translation-drawer.png)
+
+Fill in or update the translated fields for each locale — name, description, and any other translatable content — then save when done.
+
+<Note>Translations can also be edited from within the product editor itself. Open the product, select the **Translations** from the three-dot menu in the top right corner, and update the fields there. Both methods produce the same result.</Note>
+
+## 4. Translate Categories
+
+Navigate to **Products → Categories** and click on the category you want to translate to open the category configurator.
+
+![A category open in the category configurator](/docs/images/user/how-to/multiple-languages/5-category-configurator.png)
+
+Click the **three-dot menu** in the top-right corner of the configurator and select **Translations**. This opens the translations side panel.
+
+![The translations side panel open for a category](/docs/images/user/how-to/multiple-languages/6-category-translations-panel.png)
+
+Switch between locales using the locale selector and enter the translated category name for each. Close the panel when done.
+
+For subcategories, the process is the same — click the subcategory to open its editor, click the three-dot menu, and add translations in the side panel.
+
+## 5. Translate Store Policies
+
+Navigate to **Settings → Policies** and click on the policy you want to translate to open the editor.
+
+![A policy open in the policy editor](/docs/images/user/how-to/multiple-languages/7-policy-editor.png)
+
+Click the **three-dot menu** in the top-right corner and select **Translations** to open the translations side panel. Switch between locales and enter the translated name and content for each, then close the panel when done.
+
+![The translations side panel open for a policy](/docs/images/user/how-to/multiple-languages/8-policy-translations-panel.png)
+
+Repeat this process for each policy you want to make available in additional languages.
+
+## Next Steps
+
+- [<u>Settings → Markets</u>](https://spreecommerce.org/docs/user/settings/markets) — full reference for configuring markets and locales
+- [<u>Products → Translations</u>](https://spreecommerce.org/docs/user/manage-products/translations) — full reference for the translations overview and bulk importer
+- [<u>Set Up Multi-Region Pricing</u>](https://spreecommerce.org/docs/user/how-to/multi-region-pricing) — configure market-specific pricing alongside your language setup