Localization in e-commerce is important because it allows you to tailor to local markets, improving the user experience and increasing conversion. This guide dives into how Tweakwise can be utilized in a scenario where your shop is available in multiple locales.

Choosing an approach

Currently categories, products and attributes can only be defined in one locale. Localization can be solved in different ways.

The first approach you can take is to simply use a separate instance for every locale your shop is available in. As a result, every locale will have its own instance. The other approach is to combine all different locales into a single instance by cleverly utilizing the category structure.

Which of the two options you should choose, depends on your specific situation. If you're selling the same products in different locales, then it is likely the second approach (single instance) is favorable. This approach comes with less maintenance work than the other approach because it allows you to share configurations between locales: you change the configuration for one locale, you change it for all locales.

However, if the products you are selling vary widely between different locales, then the first option (multiple instances) is a better fit. In that case there likely aren't a lot of configurations you'd want to share between locales. Having separate instances will allow you to have a better overview of your instance's configuration than if you were to combine all locales together into a single instance.


A hybrid approach might also be an option worth considering. For example, you might sell the same products to all customers within Belgium regardless of if they speak French, German or Dutch, but sell very different products to German customers. It would then be smart to have a single instance for your Belgian shops and another instance for your German shop.

Approach 1: Instance per locale

If you're going with the instance per locale approach, then the rest of this guide is irrelevant to you. You will simply have to import all locale-specific shop data into each instance matching that locale. After which you can use Tweakwise the regular way.

Approach 2: Single instance, multiple locales

If you’ve chosen to use one instance for all locales, then you may need some help trying to get your data into Tweakwise. This chapter aims to answer questions you might have and provide you with some useful tips and tricks.

Throughout this chapter we will be using a fictional Tweakwise merchandise shop as an example. This fictional shop sells various products like Tweakwise-branded pillows, mugs and T-shirts. The shop is available in both Britain and the Netherlands and in both locales the same products are sold. That makes it a perfect match for the "single instance, multiple locales" approach.


Because Tweakwise doesn't support having categories, products and attributes in different locales, we're going to utilize the category structure within your instance to support multiple locales regardless. To do this, we need to create a separate category for every locale.

How easy this is to do, will depend on how your shops are set up. If all of your shops’ categories have a unique ID for every locale that category is available in, then you won’t run into issues. For example, if our multilingual Tweakwise shop is set up like the picture below, all categories have their own unique ID. Even though the Clothing and Kleding categories are essentially the same category.

However, in a lot of situations this won't be the case. Instead all of the categories that are a translation of one another share the same category ID. Below you can see an example of that case as well for the Tweakwise merchandise shops.

To solve this problem, we're going to prefix our category IDs with a so-called locale identifier codes. A locale identifier code is a number that refers to a specific locale. This code should be a number of a fixed length. In the table below you can see the identifier codes we've chosen for the Tweakwise merchandise shops.

LocaleIdentifier code
English / United Kingdom (en-gb)1000
Dutch / The Netherlands (nl-nl)2000


In the example above we're using large numbers for our identifier codes. This gives us plenty of room to later add more shops if we wanted. The trailing zeros at the end also improve readability as you'll see soon.

If we apply the locale identifier codes to our categories, we end up with the categories as shown below.

This way all the categories for every locale get a unique ID, which makes them compatible with Tweakwise. The last thing that is left to do is add a root category under which all locale categories should be placed. After all, Tweakwise's category structure requires there to always be a root category.


In the example we gave our root category ID 1. We recommend you do this as well simply because it is a common practice.

Products & attributes

With your category structure in place, the next challenge will be getting your products imported for all locales. Within your instance, every product needs to have a unique article number. If you’re selling the same product in different locales, you can link the product to multiple categories, but you probably want the characteristics localized.

For example, it is very likely your products are stored in a way like our Tweakwise heart-shaped pillow below. The pillow only exists once in your system and simply has translations for different locales.

Product imageArticle numberLocaleNameColor
116UKTweakwise Pillow RedRed
NLTweakwise Kussen RoodRood

However, as stated before, Tweakwise doesn't localize the products. Instead we will duplicate it and make the article number unique. To achieve this, we can use the ID of the locale category and prefix the article number using it.

Product imageLocale categoryArticle numberNameColor
Tweakwise UK
ID: 10001
10001-116Tweakwise Pillow RedRed
Tweakwise NL
ID: 20001
20001-116Tweakwise Kussen RoodRood

After doing this, you'll effectively have duplicated your products in all of your locale categories.


On translating attribute names

In the example above, we're adding an attribute with the name Color and assigning it the value Red and Rood for the British and Dutch shops respectively. You can also choose to translate Color to Kleur for the Dutch products. However, be aware that this will result in two separate properties within Tweakwise.

If you're planning to share things like sorting options between locales, then having separate (translated) properties per locale can be a bit more work to manage. You'll either need to create locale specific configurations (like separate British and Dutch sorting options), or combine them into a single property afterwards using the derived properties module.

It is therefore preferred to not translate attribute names.

By practice

At this point, you now know what challenges you might face and how to overcome them when importing product data with multiple locales. However, theories with examples are nice, but learning by practice can help you get a better grasp of it all.

That is why we've prepared a multilingual feed based on this article. You can import the feed into an instance of your own and experiment with Tweakwise in a multilingual setting. If you're planning to make a feed of your own, you can of course also use it as an example of a multilingual feed.

Feed URL: https://sttwdocseuwe.blob.core.windows.net/shop/feed-gb-and-nl.xml


Not sure how to import a feed? Check out our Quick start and Import a feed guides.

Overview of the categories after importing the feed

Overview of the categories after importing the feed

Tweakwise Red Pillows after import. Note how they are essentially duplicated

Tweakwise Red Pillows after import. Note how they are essentially duplicated

What's next

Congratulations! You've learnt how to:

  • Make a choice between sharing a single instance with multiple locales and having an instance per locale
  • Structure your categories, products and attributes to be compatible with Tweakwise using the single instance approach