Multi-Locale Catalogs

Multiple locales can be used on a single master or child catalog. This allows you to easily localize the same product information across different languages. However, all locales of a catalog must use the same currency—different currencies require separate catalogs. 

Each master catalog will have a default locale that all of the main configurations are made on, such as product pricing. Then, you can switch to any of the additional supported locales while configuring products, product attributes, categories, and discounts to change the settings for a specific locale.

Enable Multi-Locale Catalogs

As of May 2024, this feature is available out-of-the-box for all new implementations. If your implementation was built prior to May 2024, then you are using the previous version of the Product API without localized content and will need to contact Kibo Support to be upgraded if you want to use it.

Once upgraded, calls to the Products, Attributes, Categories, and Discounts APIs will require localizedContent by default. If you need to manage older product data that hasn't been rewritten to the new model, include an x-api-version header set to "1" in your API request. This will call the original version of the API that supports your existing products without localization. 

Restricted Content

Internal-Only: Migration Guidelines

To switch an existing client to the new version of these APIs, change their catalog-admin-products-DefaultApiVersion tenant attribute from "1" to "2" and that will be their new default going forward. Refer to the following example for some configuration guidelines and best practices.

Example Scenario: 

  • A master catalog's default locale is en-US.
  • Catalog 1 has a default locale of en-US and is used for the English site.
  • Catalog 2 has a default locale of fr-FR and is used for the French site.

You can either create a new master catalog and add all supported locales there, or use custom code to populate values for other supported locales:

  1. Supported locales should already be populated with the migration and on the product database. Take an existing master catalog and pick an existing child catalog that has the same default locale (Catalog 1).
  2. Products and attributes should already be populated due to migration during deployment. For categories, manually populate the alternate locale values by taking the French locale values from Catalog 2 and populating them in Catalog 1. You can perform lookups based on the category code (assuming they match between catalogs) to methodically retrieve and copy over the French values.
  3. Discounts are more difficult to move over if the discount name or threshold messages are required to be shown in French.
    • If they do not require localization, simply make sure to take the delta discounts from Catalog 2 and create them on Catalog 1.
    • If text does need to be localized, there are no discount codes to match between catalogs. Each tenant's circumstances are unique and require custom logic. For instance, if the discount name is never displayed and the name is the same between both catalogs, then you might be able to migrate the threshold messages.
    • Even if a discount doesn’t have a name or threshold message in fr-FR, it will still apply on the French site. It just won’t show any localized text for fr-FR.
  4. Create a new French site pointing to Catalog 1 with fr-FR as the locale. The site-specific code will have to be modified.
  5. Starting using the V2 payload for create/update/delete operations, populating the localizedContent.
  6. For products, you can use the x-api-version header to control whether you want the payload to represent the schema for V1 or V2.

For more details, refer to CAT-4688 and related tickets.

Locale-Specific Configurations

Setting up multi-locale catalogs is done as part of your standard catalog and site settings:

  1. When creating a master catalog, select a default locale code and then indicate all other supported locales. 
  2. Create a child catalog and select one of the supported locales from the master catalog.
  3. Create a site and select one of the supported locales from the master catalog.

You can then switch to any of the supported locales when viewing a product, product attribute, category, or discount configuration page by using the drop-down menu in the top right. Then you can change the displayed language-specific fields (such as product names and descriptions) for that locale. 

The Switch Locale Code selector with example locales

When interfacing with APIs, a localizedContent object will contain these details for each locale. See the Catalog Admin API documentation for product, attribute, category, and discount request models with this object.

Locale Overrides

If you need two child catalogs within the same master catalog that are the same locale (such as en-US), you can use overrides to specify product and SEO content settings for each catalog. 

  1. Go to System > Structure > Catalogs.
  2. Expand the drop-down menu for a master catalog and click Edit.
  3. In Supported Catalog Override Locales, enter the locales you want to configure overrides for. This must be formatted as the language code followed by the child catalog ID, such as en-1 and en-12.Master Catalog settings showing the supported override option
  4. Click Save.

Then configure overrides at the product level: 

  1. Go to Main > Catalog > Products.
  2. Ensure you have the appropriate master catalog selected at the top.
  3. Click the product you want to edit.
  4. Switch to the specific locale and catalog you want to override using the drop-down selector.
  5. Toggle on Override global under the General and/or SEO settings header. You can toggle this off at any point to remove overrides. The override global toggle on product settings
  6. Click Yes when prompted to confirm. This will make that section editable.
  7. Enter the product and/or SEO settings. Note that properties cannot be overridden, so they are hidden on the UI.
  8. Click Save.

Import/Export Localized Content

The Catalogs template of the Import-Export V2 and V3 applications supports localization for multi-locale catalogs. Use the Products and Categories sheets to define the default master catalog locale information, and then include the ProductContent and/or CategoriesContent sheets to set localized product, SEO, and category content on a non-default locale.

You can also provide additional columns with locale headers on certain sheets such as ProductPropertyLocale and Attributes. The data within these columns will be the localized values of each attribute within that specific locale.

Related Articles

How would you rate this article?
Thank you for your feedback!