Why does the Shopify variant picker break when you switch language?

Short answer: Shopify treats option names and option values as translatable content, so a picker or swatch script that matches on the literal string Color or Navy stops matching the moment a shopper switches language. Rubik Variant Images, built by Craftshift, assigns media to the variant itself instead of parsing the label. Free to install, 5.0 stars across 420 reviews.

Two symptoms keep turning up together on multilingual Shopify stores, and almost nobody connects them. The first: you add a second language, and the variant picker changes shape or stops responding, and the theme customizer no longer lets you change it back. The second: you switch the storefront to Arabic, and the swatches vanish or land in the wrong place while the English version stays perfect.

They look like two bugs. They are usually one bug and one design problem. The bug is that a lot of variant picker and swatch code matches on text, and translated text is different text. The design problem is that right to left is a layout mode, not a font, and a stylesheet written with left and right in it will simply do the wrong thing.

We build variant image and swatch apps for a living, which means we get to watch this fail across a lot of themes. The pattern is consistent enough to write down.

In this post

• What actually changes when a shopper switches language
• Why matching on the option name is fragile
• The alt tag conventions break for exactly the same reason
• Why Arabic and Hebrew are a second, separate failure
• What a language safe variant picker looks like
• Telling the two problems apart in ten minutes
• Where our two apps sit, and what they do not do
• Frequently asked questions

What actually changes when a shopper switches language

Less than people assume, and more than enough to break things. Shopify’s Admin API documents the list of content types you are allowed to translate, and two of the entries matter here. PRODUCT_OPTION is described as “An online store custom product property name. For example, ‘Size’, ‘Color’, or ‘Material'”. PRODUCT_OPTION_VALUE is described as “The product option value names. For example, ‘Red’, ‘Blue’, and ‘Green’ for a ‘Color’ option”. In both cases the translatable field is name.

So the entity does not change. The variant keeps its ID. The option value keeps its ID. Only the display name is swapped for the localized one before the page renders.

Now look at what Liquid hands the theme. product.options is documented as “The option names of the product”, returned as an array of strings. product_option.name is “The name of the product option”. product_option_value.name is “The name of the product option value”. Every one of those is the translated string on a localized storefront, because that is the entire point of translating it.

Which means a theme that asked “is this option called Color?” is now asking a question whose answer is Couleur. Or Farbe. Or Kleur. And the answer is no.

Why matching on the option name is fragile

Themes and apps have to identify which option is the colour one somehow. Shopify does not tag it for you. There is no is_color flag on the option. So the shortcut everybody reached for, for years, was the name.

That shortcut appears in more places than you would guess:

• A theme setting where you typed the word Color into a text field, and the swatch renderer only fires when the option name equals it.
• CSS class names generated from the option value, so Navy becomes .swatch--navy and your handwritten override targets a class that no longer exists in French.
• A colour library that maps the value name to a hex code, keyed by the English word.
• Filenames or alt text that encode the option value, which we will come back to.
• Custom JavaScript in the theme that reads the selected radio label and compares it to a list.

Each one is fine on a single language store. Each one silently becomes a no-op on the second language, and here is the part that makes it feel like a customizer bug rather than a code bug: when the match fails, most of this code does not throw an error. It just does nothing. The swatch renderer skips the option, the theme falls back to its default dropdown, and the setting you used to have in the customizer is gone because the block that owned it never rendered. You are not looking at a broken setting. You are looking at the absence of a block.

There is a stable key sitting right there, by the way. Liquid’s product_option_value object exposes id, documented as “The ID of the product option value”. That number does not change when the name is translated. Neither does variant.id. Any code that keys on those survives a language switch by construction.

One caveat worth knowing, because it trips people up: product_option itself has no documented id in Liquid. It has name, position, selected_value and values. So at the option level the stable handle is position, “The 1-based index of the product option in the product.options_with_values array”. Not elegant. But position one is position one in every language, and the option name is not.

The alt tag conventions break for exactly the same reason

If you have ever tried to get more than one image per variant without an app, you have probably met the hash convention: you write something like #color_navy into an image’s alt text and the theme groups images by that marker. Four separate theme vendors built a version of it independently, which we documented with sources in every method for building a Shopify variant image set.

Maestrooo, whose themes include Impact, Warehouse, Prestige and Focal, states the limit outright in their own documentation: the feature does not work with multiple languages, because alt tags are not translatable. That is the cleanest illustration of the whole problem you will find anywhere. The convention encodes an option value as English text into a field Shopify has no mechanism to localize, so the moment the picker starts saying Marine instead of Navy, the marker and the label are talking about the same thing in two different languages and nothing lines up.

Eurus, from Omni Themes, went at it from the other end and shipped the only real workaround we have seen documented. Their theme setting takes the option name in every language you publish, separated by semicolons, so you enter Color; Colour; Couleur and all three resolve to the same option. It is a lookup table maintained by hand. It works. It also tells you precisely how deep the problem goes, because the fix is “list every string that could ever appear”, which is not a fix so much as a well organised surrender.

And notice what it does not cover. Option values. You can teach it that Couleur means Color, but you still have forty images whose alt text says #color_navy while the storefront is saying Marine.

Why Arabic and Hebrew are a second, separate failure

Switch to Arabic and you can get all of the above plus a layout that has quietly turned itself inside out. These are different failures with different fixes, and treating them as one is why people spend a week on the wrong thing.

Shopify is blunt about whose job this is. Their documentation on adding languages says: “When translating to languages that are written from right to left, such as Hebrew or Arabic, check that your theme supports right-to-left languages to ensure that the layout is correct.” Read that again. Check that your theme supports it. There is no platform level flag that makes an unprepared theme behave.

What breaks, concretely, is any CSS written in physical directions. A swatch strip laid out with margin-left, a selected ring positioned with left: 0, a carousel that advances with transform: translateX(-100%), an arrow rotated to point right: under dir="rtl" every one of those keeps pointing the way it always did while the text flows the other way. The logical equivalents (margin-inline-start, inset-inline-start, padding-inline-end) flip automatically with the document direction. Most themes are somewhere in between, because the base theme was updated and the custom CSS somebody pasted in two years ago was not.

So when swatches “do not show” in Arabic, check whether they are actually missing or merely rendered off screen. Inspect the element. If the node is in the DOM with a computed width, you have a direction problem, not a matching problem. If the node is not in the DOM at all, you are back in the string matching section. Different sections. Different fixes.

Not sure which theme you are actually running, or which version? Our free Shopify theme detector reads it off any live store, which is faster than digging through the admin and gives you the exact version number to quote at your theme vendor’s support.

What a language safe variant picker looks like

One rule covers most of it: identity and display are two different things, and only one of them is allowed to be translated.

The display name is what the shopper reads. Translate it, adapt it, let Shopify swap it per market. The identity is what your code matches on, and it has to be something Shopify will never localize: the variant ID, the option value ID, the option position. If a rule in your store can only be expressed as “when the text says Navy”, that rule has a shelf life measured in however long it takes you to add a second language.

Three practical consequences.

1. Translate the option names and values properly first. Half the reports we see are not a broken picker at all, they are an untranslated one, which looks broken next to a fully translated page. We wrote the process up separately in how to translate variant picker options on Shopify.
2. Stop encoding option values into fields that cannot be translated. Alt text, filenames, tags, CSS class names. All of them are English forever.
3. Audit your custom CSS for physical directions before you add an RTL language, not after. It is a find and replace job on a quiet afternoon, or a fire drill on a launch day.

Doing this by hand is realistic for one product with three colours. It stops being realistic at three hundred, which is roughly the point where merchants come to us, and it is why Rubik Variant Images stores a separate media set per variant in Shopify metafields rather than reading a marker out of alt text. The mapping points at the variant, so nothing in it is a translatable string, and the app’s swatch click event carries optionValueId next to the human readable optionValue for exactly this reason. Free plan, 5.0 stars across 420 reviews on the App Store.

“This app works flawlessly! It solved a massive issue I had with duplicate images due to having a multi-language setup. The support team helped me integrate the app from start to finish. They’re the best support I’ve ever had in my 7 years in eCommerce. Amazing app, amazing people. Thank you Ümid!”

Hairebel, US, 2025-06-22, via Rubik Variant Images on the Shopify App Store

Telling the two problems apart in ten minutes

Work down this list in order. Each step is cheaper than the one below it.

Check	What it tells you
Load the same product in your default language	If it is fine there, the product data is fine and the problem is language specific. If it is broken in both, stop reading and fix the product first.
Inspect the swatch container in the broken language	Node present but positioned oddly means direction and CSS. Node absent means a match failed and the block never rendered.
Compare the option name shown in the picker with whatever string your theme setting or custom code expects	If they differ, you have found it. This is the single most common cause.
Open the translated option values in Translate and Adapt	Blank or partially filled values produce half a broken picker, which is more confusing than a fully broken one.
Grep your custom CSS for left, right, translateX, float	Every hit is a candidate for the RTL layout failure. Logical properties are the replacement.
Disable third party apps one at a time on a duplicate theme	Last, not first. It is the slowest check and usually confirms what step three already told you.

Step three is the one people skip, and it is the one that solves it. Read the option name off the live storefront in the broken language, then read the string your setting expects, and put them side by side. That is the whole diagnosis most of the time.

Where our two apps sit, and what they do not do

Being straight about this matters more than a sales line, because a wrong assumption here costs a merchant a weekend.

Rubik Combined Listings has a translation integration. It supports Shopify Translate and Adapt for group labels, option names and option values, which is what you want when your colours are separate products linked into one listing and the swatch label has to read Marine in French. There is a fuller write up of that on our other site: translating combined listings for a multilingual store. It is 5.0 stars across 65 reviews, with a free plan covering 5 groups, and it is the younger of our two apps by a distance.

Rubik Variant Images does not have a translation feature, and that is deliberate rather than a gap. It never reads a display string in the first place: you assign media to a variant in the app, the mapping lands in a metafield, and the storefront renders from that. There is nothing in the mapping for a translation to invalidate. It handles one product’s own variants, on the product page and on product cards, and it does not link separate products together. That is the other app’s job.

Neither app integrates with Shopify Markets. If you need per market behaviour beyond what Translate and Adapt gives you, we are not the answer and I would rather say so here than in a support ticket.

What I could not confirm from public documentation, and so will not claim: how Shopify’s store level swatch library resolves an option value under translation. The Liquid docs are clear that product_option_value.swatch hangs off the option value object itself, which is the language safe shape, but the admin side of that setup is not documented in enough detail for me to tell you it always survives. Test it on your own store before you rely on it.

If you want to see the picker behaviour before installing anything: the live demo store is open, and the getting started guide covers setup. For swatch styling choices across themes, our swatch customization guide goes deeper than this post does. And if you are restructuring localized URLs at the same time, the free URL analyzer will tell you whether your handles are doing you any favours.

Frequently asked questions

Does Shopify translate variant option names and values?

Yes. Shopify’s Admin API lists PRODUCT_OPTION and PRODUCT_OPTION_VALUE as translatable resource types, and in both cases the translatable field is name. So the option called Color can render as Couleur, and the value Navy can render as Marine, while the underlying IDs stay the same.

Why did my variant picker settings disappear from the theme customizer after adding a language?

Usually because the block that owns those settings is no longer rendering. Swatch renderers that only fire when the option name matches a configured string quietly skip the option once the name is translated, and the theme falls back to its default picker. The settings are not deleted. The block that displayed them is simply not being output.

Why do swatches stop showing when I switch to Arabic?

Two possible causes, and they need different fixes. Either the option name no longer matches what your theme or app expects, so nothing renders, or the swatches render fine but land off screen because the CSS uses physical directions that do not flip under dir="rtl". Inspect the element. If the node exists, it is a layout problem.

Does the alt tag variant image trick work on a multilingual store?

Generally no. Maestrooo’s theme documentation states plainly that their alt tag based image set feature does not work with multiple languages, because alt tags are not translatable. Eurus works around it by letting you enter the option name in every language separated by semicolons, for example Color; Colour; Couleur, which is the only documented workaround we have found.

Which app should I use to keep variant images working in every language?

For one product’s own variants, Rubik Variant Images assigns media to the variant and stores the mapping in a Shopify metafield, so there is no translated string in the matching path at all. It is 5.0 stars across 420 reviews with a free plan. If your colours are separate products, Rubik Combined Listings links them and supports Translate and Adapt for group labels, option names and option values. Neither app integrates with Shopify Markets.

Is there a stable ID I can match on instead of the option name?

For option values, yes: Liquid’s product_option_value object exposes id, and it does not change with translation. For the option itself there is no documented id in Liquid, so the stable handle is position, the 1-based index of the option in product.options_with_values.

Does Shopify handle right to left layout automatically?

No. Shopify’s own guidance says to check that your theme supports right to left languages so that the layout is correct. Theme support is a prerequisite you verify, not something the platform retrofits. Custom CSS added by a previous developer is the usual offender, since base themes get updated and pasted snippets do not.

Related reading

• How to translate variant picker options on Shopify
• Shopify variant image sets: every method, with sources
• Choosing Shopify variant option names
• Shopify variant picker swatch types compared
• How to add colour swatches to Shopify product pages
• Translating combined listings on a multilingual Shopify store

If your picker is fine in English and broken everywhere else, the fastest thing you can do today is stop matching on words.