Naming your images

GeoGallery decides everything from your image filenames. There’s nothing to configure per product.

The rule

A localized image is named:

XX_rest-of-the-default-filename.jpg

• XX is a two-letter code: a language code in Language mode, a country code in Country mode.
• The third character must be an underscore _.
• After the code and underscore, the name must match the default image it replaces.

Default image	Localized version	Shown to
shirt.jpg	FR_shirt.jpg	French storefront (Language mode)
shirt.jpg	US_shirt.jpg	Customers in the United States (Country mode)
size-chart.png	DE_size-chart.png	German storefront (Language mode)

Images without a code are your default images.

How matching works

• Upper or lower case both work. FR_shirt.jpg, fr_shirt.jpg and FR_Shirt.JPG all pair with shirt.jpg. Uppercase codes are easier to spot.
• The file extension doesn’t need to match. Everything from the first dot onwards is ignored, so FR_shirt.png pairs with shirt.jpg. This also means FR_shirt.v2.jpg is read as shirt.
• Shopify’s added suffixes are ignored. If you upload a file with the same name twice, Shopify may add a long ID to the end (for example shirt_1a2b3c4d-....jpg). GeoGallery strips that ID before comparing.
• Only images with a localized version are swapped. A default image with no FR_ version stays visible to French visitors too. You only need to localize the images that need it.
• Images for other codes are hidden. A French visitor never sees DE_ images.
• Upload to the product. Localized images must be in the product’s own media, not just in Content > Files.

Example: a product with five images

Default	French version	French visitor sees
hero.jpg	FR_hero.jpg	FR_hero.jpg
back.jpg	FR_back.jpg	FR_back.jpg
size-chart.jpg	(none)	size-chart.jpg
model.jpg	(none)	model.jpg
DE_hero.jpg	(German, not French)	hidden

Codes

• Codes are always exactly two letters. Codes like EN-GB_ or PT-BR_ aren’t recognised.
• Language codes are the first two letters of the storefront language. Portuguese (Brazil) and Portuguese (Portugal) are both PT_, and Chinese (Simplified) and Chinese (Traditional) are both ZH_, so they can’t have different images in Language mode.
• Country codes are ISO two-letter country codes. The United Kingdom is GB_, not UK_.
• A few codes are both a language and a country, for example AR (Arabic / Argentina) and SV (Swedish / El Salvador). Which one applies depends on the Match images by setting.

Need a code? See the list of country codes.

Ordinary filenames that look like codes

Any filename whose third character is an underscore is treated as localized. A file called my_shirt.jpg is read as code MY and will be hidden from everyone else. Rename files like this, for example to my-shirt.jpg.

Images made by AI translation

When you approve an AI translation, GeoGallery adds it to the product already named to pair with its source image, for example FR_shirt.jpg for shirt.jpg. You don’t need to rename anything.