Configure listing pages for multiple locales

This is for:

Developer

As discussed in the Create listing configurations article, you need to create a specific configuration for each product listing page (PLP) on your storefront.

Note

If you have a multi-source setup supporting multiple locales, make sure you’ve configured your query pipelines correctly. This ensures that requests from the Commerce API target the appropriate query pipeline and listing page configuration.

It’s possible to create a single listing page configuration for multiple listing pages by specifying multiple URLs when you create your listing page by specifying the patterns object in the configuration when directly calling the endpoint.

These URLs represent the locations for which this particular configuration can be queried.

Listing page configurations also support localized facet and sorting names, allowing you to specify the names returned for different languages.

The following example shows a configuration for a surfboards PLP that supports multi-locale functionality for the en and fr languages.

{
    "name": "<NAME>",
    "trackingId": "<TRACKING_ID>",
    "patterns": [ 1
        {
            "url": "https://sports.barca.group/en/browse/surfboards"
        },
        {
            "url": "https://sports.barca.group/fr/browse/surfboards"
        }
    ],
    "queryConfiguration": {
        "additionalFields": [],
        "facets": {
            "enableIndexFacetOrdering": false,
            "freezeFacetOrder": true,
            "facets": [
                {
                    "type": "regular",
                    "facetId": "ec_colors",
                    "field": "ec_colors",
                    "displayNames": [ 2
                        {
                            "value": "Color",
                            "language": "en"
                        },
                        {
                            "value": "Couleur",
                            "language": "fr"
                        }
                    ]
                }
            ]
        },
        "sorts": [
            {
                "sortCriteria": "relevance"
            },
            {
                "sortCriteria": "fields",
                "fields": [
                    {
                        "field": "ec_price",
                        "direction": "asc",
                        "displayNames": [
                            {
                                "value": "Price (Low to High)",
                                "language": "en"
                            },
                            {
                                "value": "Prix (du moins cher au plus cher)",
                                "language": "fr"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "rules": {
        "rankingRules": [],
        "filterRules": [
            {
                "name": "Include product cat_slug contains surfboards",
                "essential": true,
                "locales": [],
                "filters": [
                    {
                        "fieldName": "cat_slug",
                        "operator": "contains",
                        "value": {
                            "type": "array",
                            "values": [
                                "surfboards"
                            ]
                        }
                    }
                ],
                "action": "include"
            }
        ],
        "pinRules": []
    },
    "perPage": 48,
    "scope": "specific"
}
1 patterns allows you to specify a list of URLs that correspond to this configuration.
2 displayNames allows you to specify a list of name-value and language mappings so that the name returned depends on the language sent in the front-end request by the Commerce API.

Ensure that your front-end application sends the correct URL and language in the request to the Commerce API to target this configuration and return the correct localized names for facets and sorting.

If your storefront is built using Headless for Commerce, see the Navigating between pages article for more information on how to set and change the language state.