> For the complete documentation index, see [llms.txt](https://help.pagefly.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.pagefly.io/page-structure-and-elements/optimization/market-localization-create-localized-page-variants.md).
# Market localization: Create localized page variants
### Overview
**Market localization** is a powerful feature that allows you to create localized versions of your pages and sections for different markets on your Shopify store. Instead of maintaining separate pages for each market, you can manage one base page and create market-specific variants that display different content, styling, and layouts to customers in different regions.
This feature is essential for global merchants who want to deliver personalized experiences based on their customers' market location while maintaining a single source of truth for page management.
### Before you start: requirements
Market Content won't appear unless all of these are true:
* **Your PageFly plan is Optimize or above.** Market Content is not available on Free, Pay-as-you-go or Builder. Grandfathered plans do not bypass this.
* **Your store has markets set up in Shopify.** Go to **Shopify admin → Settings → Markets**. If you have only one market, there's nothing to create a variant for.
* **The page has no active A/B test.** A page can hold market variants *or* a running A/B test, never both. See below.
* **It's a regular Page.** Market versions are rolling out by page type, starting with regular pages. Support for Product, Collection, Home, Blog and Password pages is on the way. If you don't see the market selector, check the page type first.
{% hint style="info" %}
**Markets and languages are different things.** A market is a *region* (Canada, Germany, the EU). A language is what the customer is reading in, and one market can serve several languages. If what you actually want is the same page in another language, market variants are the wrong tool — see [Translate your page into another language with AI](https://github.com/sellersmith/pagefly-help-center/tree/master/en/page-structure-and-elements/optimization/translate-your-page-with-pagefly-ai.md).
{% endhint %}
### How to Access Market Content
#### For Pages
1. **Open PageFly Editor** — Navigate to the page you want to localize
2. **Locate the Market Selector** — In the editor header toolbar, look for the **Market dropdown button**
* If no markets are set up, it displays a **Store** icon with "Default Market" label
* If you're editing a market variant, it shows the market name and country flag
3. **Click the Market Selector** — A popover menu opens displaying all available markets and existing variants
4. **Select Your Target Market** — Choose a market from the list to view or create a variant
#### Sections are not supported
Market versions work on **pages**, not on reusable sections. There is no market selector in the section editor. Unlike the page types above, this isn't a rollout stage — sections don't support market versions.
If you need a section to differ by market, put that section on a page and create a market version of the page.
### Understanding the Market Selector
#### The Button Display
The Market Selector button changes based on what you're currently editing:
| State | Icon | Label | Meaning |
| ----------------- | --------------------- | ---------------------------- | ---------------------------------------- |
| Base Page/Section | Store icon | "Default Market" | Editing the base version for all markets |
| Market Variant | Country flag or globe | Market name (e.g., "Canada") | Editing a variant for a specific market |
| Loading | Globe icon | "Loading..." | Fetching variants from the server |
#### The Market Popover Menu
When you click the Market Selector, a popover menu appears showing:
* **Base (Default Market)** — Always listed at the top with a store icon
* **Additional Markets** — All other markets from your Shopify store
* **Status Badges** — Similar to an individual page/section status, each market shows its variant status, synced both on the top bar and popover selector. Also you can Save/Publish/Unpublish them separately.
### "Default" and "Primary" are different things
These two sit next to each other in the popover and both sound like "the main one". They are unrelated.
| In the popover | What it means |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default** | Your **base page**. It isn't a market at all. It's the content shown to every market that doesn't have its own version. |
| **Primary** | A badge on one of your **markets**, showing which market Shopify has set as your store's primary. It comes from your Shopify Markets settings. |
So a row reading `International · Primary` means *International is your store's primary market*. It does **not** mean that version outranks Default.
{% hint style="info" %}
**Being the primary market gives a version no special priority.** Every market is treated the same way: if that market has a published version, its customers see it; if it doesn't, they see Default. Changing which market is primary in Shopify does not change what any version serves.
{% endhint %}
### When does Default still serve?
Default is the fallback. It's shown to any market that has **no published version of its own**.
That means Default quietly stops reaching customers as you cover your markets — and it can happen much faster than expected, because of catch-all markets.
{% hint style="warning" %}
**Publishing a version for a catch-all market can take Default off your storefront in one step.** Many stores have a market covering dozens of regions at once (shown in the popover as something like `+27 International`). Every customer who isn't in one of your specific markets resolves to that one. Publish a version for it, and Default is no longer what most of your visitors see. Publish versions for all of your markets, and no customer sees Default at all.
{% endhint %}
**Default still matters even when no customer is seeing it:**
* **It's the file your page is published from.** Market versions are alternatives inside the page your base publish created. If Default is out of date or unpublished, that affects every market.
* **It catches anything new.** Add a market later and its customers see Default until you build a version for it.
So keep Default correct even after every market has its own version. It's your safety net, not a leftover.
**To view Default on your storefront:** switch your store's country to one in a market that has no version. If every market has a version, there is no customer-facing route to Default — that's expected, not a bug.
### Creating a Market Variant
#### Step 1: Open the Market Selector
1. Click the **Market Selector** button in the editor header
2. The popover menu displays all available markets
#### Step 2: Select the Market
1. **For markets with existing variants** — Click the market name to switch to that variant
2. **For markets without variants** — Click the market to create a new variant
#### Step 3: Confirm the Variant Creation
When creating a new variant, a confirmation dialog appears:
1. Review the market name and region count
2. Click **Create** to proceed
3. A loading overlay appears while the variant is being created
4. The editor automatically switches to the new variant once ready
> **Note:** When you create a variant, PageFly automatically clones the current base page content. You can then customize it for that specific market by editing the content, layout, styling, and functionality.
### Editing a Market Variant
Once you're editing a variant (indicated by the market name in the Market Selector), you can customize it exactly like a normal page:
* **Edit content** — Change text, images, products, and sections
* **Modify styling** — Adjust colors, fonts, spacing, and responsive layouts
* **Add/remove elements** — Insert new elements or delete existing ones specific to this market
* **Customize settings** — Configure unique behaviors for this market variant
#### Saving Your Changes
When you make changes to a variant:
1. **Manual save** — Click the **Save** button in the top-right. This is the only thing that saves your variant to PageFly.
2. **Status indicator** — The badge next to the market name updates to show "Unsaved Changes" while you're editing.
3. **Local backup** — As you edit, PageFly also keeps a recovery copy in your browser. If the editor closes unexpectedly, you'll be offered the option to restore it next time you open that page.
{% hint style="warning" %}
**The local backup is not a saved draft.** It lives in the browser you were working in, not on PageFly's servers. If you switch computers or browsers, use a private window, or clear your browsing data, it's gone. Nothing is stored on your account until you click **Save**.
{% endhint %}
> **Important:** Remember to save your changes before switching to another market or closing the editor.
### Publishing Market Variants
#### Publishing a Single Variant
1. **While editing the variant**, click the **Save** button
2. A save/publish dialog appears
3. **Choose your action:**
* **Save as Draft** — Saves changes without publishing
* **Publish** — Makes the variant live to customers in that market
#### Publishing the Base Page
1. Click the **Market Selector** and choose **Default Market**
2. Make your edits to the base page
3. Click **Save**
4. Choose **Publish** to make changes live to all markets without specific variants
> **Tip:** Always ensure your base page is published before publishing market variants. Publishing the base page is what puts the page on your theme in the first place, so an unpublished base affects all markets.
{% hint style="info" %}
**A variant replaces the base content for that market — it isn't layered on top of it.** Customers in a market with a published variant see *that variant's* content instead of the base page's. Editing the base page afterwards does not flow into variants you've already created; each variant keeps the content it was created with until you edit it.
{% endhint %}
### Two rules that surprise people
#### A page can't have both market variants and a running A/B test
If a page has market variants live, you can't start an A/B test on it — and if an A/B test is running, you can't publish market variants. PageFly blocks whichever you try second.
This isn't an arbitrary restriction. An A/B test serves its variant arm from a separate theme file that carries no market routing, so the control arm would show localized content while the test arm showed the base content. The test would be measuring localization mixed in with your design change, and the result would be meaningless.
To move from one to the other: stop and remove the A/B test before publishing variants, or unpublish your variants before starting a test.
#### Your published variant may not appear on the storefront immediately
{% hint style="warning" %}
**Shopify caches each page separately per market, and publishing does not clear that cache straight away.** After you publish a variant, that market can keep serving the previous version for several minutes. This is Shopify's caching, not a PageFly bug, and it affects any page on your store, not just PageFly ones.
If you've just published and don't see the change, wait a few minutes before republishing. Publishing repeatedly does not clear it faster. A market you have never visited before will show the new version straight away, which is why the change often appears instantly to a colleague but not to you.
{% endhint %}
### Switching Between Markets
#### How Switching Works
1. Click the **Market Selector** button
2. Select a different market or the base page
3. **If you have unsaved changes:**
* A modal dialog appears asking you to **Save**, **Discard**, or **Cancel**
* **Save and Switch** — Saves your current variant before switching
* **Discard and Switch** — Abandons changes and switches to the new market
* **Cancel** — Closes the dialog and keeps editing the current variant
#### Switching Back to the Base Page
1. Open the Market Selector
2. Click **Default Market** at the top
3. Follow the unsaved changes prompt if needed
4. You're now editing the base page
### Deleting a Market Variant
#### To Delete a Variant:
1. Open the Market Selector popover
2. Locate the market variant you want to delete
3. Click the **delete icon** (trash can) next to the market name
4. A confirmation dialog appears
5. Click **Delete** to confirm (this cannot be undone)
> **Warning:** Deleting a published variant immediately removes it from that market. Customers in that market will see the base page instead. This action cannot be reversed.
#### What Happens After Deletion
* **For Published Variants** — The variant is unpublished and removed; the base page is restored for that market
* **For Draft Variants** — The variant is simply deleted with no impact on live pages
* **The Editor** — Returns to the base page or another active variant after deletion
### Real-World Use Cases
#### Global Product Variants with Local Messaging
Create a product page for your base market, then customize variants for:
* **Canada** — Add bilingual French/English content
* **Australia** — Update shipping details and local payment methods
* **Germany** — Translate to German and adjust pricing currency
#### Regional Holiday Campaigns
Build a holiday sale page, then create market-specific variants with:
* Localized holiday greetings and imagery
* Region-specific discount messaging
* Local currency and payment options
#### Multi-Language Content Delivery
Manage a single page structure across markets with language-specific variants:
* English for US/UK/Canada base page
* Spanish variant for Mexico/Spain markets
* Portuguese variant for Brazil market
{% hint style="info" %}
**Markets and languages are not the same thing.** A market variant is chosen by the customer's **market** (their region), not by the language they're browsing in — and one market can serve several languages. Content you put in a market variant is shown as you wrote it; it isn't translated automatically, and market variants can't use Shopify translations.
If what you want is the same page in another language, use [Translate your page into another language with AI](https://github.com/sellersmith/pagefly-help-center/tree/master/en/page-structure-and-elements/optimization/translate-your-page-with-pagefly-ai.md) on the default version of the page instead. It will serve translated text in every market that uses that language.
{% endhint %}
#### Compliance and Legal Localization
Ensure compliance with regional requirements by customizing:
* Privacy policy language and links
* Shipping and return policy variations
* Local tax information displays
* Currency and measurement units
### Troubleshooting & FAQ
#### Q: What happens to a variant if I delete the base page?
**A:** Market variants are tied to their base page. If you delete the page, all variants are deleted as well. Always export your variant content if you need to preserve it.
#### Q: Can I create a variant without publishing the base page?
**A:** Yes! You can create and edit variants independently. However, customers will only see the variant content if the base page is published. A draft base page means nothing displays for any market.
#### Q: How long does it take to create a variant?
**A:** Variant creation typically takes 1-3 seconds as PageFly clones the base content. You'll see a loading overlay during this time.
#### Q: Can I edit a variant on my mobile device?
**A:** Market Content features work best on desktop. Mobile editing support is limited; we recommend using a desktop device for variant creation and editing.
#### Q: What if my variant shows "Empty Content" warning?
**A:** This means the variant exists but has no content elements. You can:
1. **Add elements** — Click in the canvas and add content to this variant
2. **Re-clone from base** — Delete and recreate the variant to re-clone fresh content
3. **Delete the variant** — Remove it if it's no longer needed
#### Q: Are my variant edits saved automatically?
**A:** Not to your account, no. PageFly keeps a **recovery copy in your browser** as you edit, and offers to restore it if the editor closes unexpectedly. That copy is local to that browser — it won't be there on another computer, in a private window, or after you clear your browsing data.
Your variant is only stored on your account when you click **Save**. Always save before switching markets, closing the editor, or publishing.
#### Q: Can I have different layouts for different markets?
**A:** Yes! Variants are fully independent. You can change the entire layout, section order, and content per market. The only constraint is they must be part of the same base page.
#### Q: What if a market is not showing in the Market Selector?
**A:** In order of how often it's the cause:
1. **Your plan is below Optimize.** Market Content requires the Optimize plan or above. This is the most common reason the feature appears missing entirely rather than just one market.
2. **The market is not set up in your Shopify store.** Check **Settings → Markets** and verify the market is active.
3. **The Shopify API hasn't synced the market list yet.** Refresh the editor.
4. **Your store isn't eligible.** Market Content is available to stores that installed PageFly from 2025 onwards. If your store is older than that and you'd like access, contact support.
#### Q: Why can't I publish my variant — it says there's an A/B test?
**A:** A page can hold market variants or a running A/B test, never both. Stop and remove the A/B test on that page, then publish your variants. See "Two rules that surprise people" above.
#### Q: I published my variant but the storefront still shows the old content
**A:** Shopify caches each page per market, and publishing doesn't clear that cache immediately. Wait a few minutes. Republishing does not speed it up. See "Two rules that surprise people" above.
#### Q: I translated my variant and now it won't publish
**A:** After a variant's content is translated, it has to be saved once before it can be published — this regenerates the variant's page content so what publishes matches what you see. Open the variant, save it, then publish.
### Best Practices
* **Start with base content** — Create a solid base page before creating variants
* **Publish base first** — Ensure the base page is published before publishing variants
* **Review before publishing** — Preview variants in a test environment before going live
* **Use consistent naming** — Keep market variant names consistent with your Shopify market names
* **Save frequently** — Don't lose work; save edits regularly, especially for complex variants
* **Test across regions** — If possible, test variants from different geographic locations to verify they display correctly
* **Document variant differences** — Keep notes on what content differs between variants for team reference
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.pagefly.io/page-structure-and-elements/optimization/market-localization-create-localized-page-variants.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.