Multi-Language Search Configuration | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to structure your search configuration for multi-language
• Best practices for managing your search configurations

Overview

When you’re building a multi-language search experience, you have three options for your backend (we’ll cover frontend in the next unit):

Option 1: Use one search configuration for all languages You can create one Search Configuration that manages the verticals, query rules, synonyms, etc for all languages at once. This will only work if your experiences are exactly the same across all languages in terms of verticals. To do this, you just need to add the appropriate language codes in the "localizations": {} property using the language code from Content. You can then modify only the synonyms and query suggestions by locale. You cannot modify the verticals by language so this will only be a good option if these will be exactly the same in all languages.

Option 2: Use separate search configurations by language (recommended) You can create a separate single language Search Configuration for each language. This allows you the most flexibility and least complexity when making updates. This means you can add, remove or update verticals for each language at separate times which is important if content or translations are not all available concurrently. The configuration file is also just easier to manage. This is our recommended approach in most cases.

Option 3: Use the same configuration for some languages, but separate configurations for others You can combine Option 1 and Option 2. For languages that are very similar (especially language variations like en, en_US, en_GB), you can use the same configuration. For other languages, you can have a separate configuration.

How should you do it?

The best path for you is ultimately going to depend on how different the experiences are and how in sync their management needs to be.

If your languages will be exactly the same, except for language-specific details like synonyms or query suggestions, and the data for each language will be available or updated simultaneously, we recommend Option 1: Use One Search Configuration.

If your languages might have variation in terms of which verticals are included or data for each vertical will be added or updated out of sync, we recommend Option 2: Use Separate Search Configurations by Language. In most cases, Option 2 (separate configurations) will be the right one and will make it easiest for you to manage.

If some of your languages will be exactly the same (e.g., language variations), but others will be different, we recommend combining the two approaches (Option 3).

As a note, remember that you can use the JSON editor to easily copy and paste configuration between experiences. While this is a more advanced interface, it makes it very quick and easy to use the same code in multiple places. You can access the JSON code editor by clicking on “Edit as JSON” under the Configuration navigation.

When you’re building a multi-language experience, we recommend building one search config first in your primary language, and then copying that config for any additional languages. To copy a configuration, you can create a new one and then copy the JSON code for that configuration into the new configuration (except the name property!).

Once you copy the configuration, you’ll want to update properties like the name or vertical names, translate the synonyms and hardcoded prompts, and update any relevant query rules that are tied to language.

Option 1 - Shallow Merging Details

If you choose Option 1 laid out above (multiple locales in the same configuration), then any language specific properties must be specified by locale in the localizations array. If you don’t specify any overrides in localizations then Yext Search what will use what is specified in either the synonyms or query suggestions objects for the primary language.

Here’s an example of what this would look like for a configuration where “en” is the primary locale and you want to set overrides for query suggestions in en_gb and es.

{
  "autocomplete": {
    "hardcodedPrompts": [
      // The prompts that every locale will see by default
      "Big Burger",
      "Smoothie",
      "Locations near me"
    ]
  },
  "localizations": {
    "en_gb": {
      "autocomplete": {
        "hardcodedPrompts": [
          "Locations near me",
          "Low calorie menu options",
          "What is the refund policy" 
        ]
      }
    },
    "es": {
      "autocomplete": {
        "hardcodedPrompts": [
          "Locales cerca de mi",
          "Opciones sin mucho calories",
          "Algo otro"
        ]
      }
    }
  }
}

In the above example, if the experience also had an it and fr language, users would see the top-level prompts in those languages (Big Burger, Smoothie, Locations near me).

As mentioned previously, we only really recommend this option if the verticals are exactly the same in all languages and new verticals or searchable fields will be added at the same time for all languages. Due to complexities with translations, we know this is often not the case and it can be easier for an Admin to manage these in separate config files. We most often see people choosing this option if they have both a US and a UK website where the content is mostly the same except, for example, CTA links that they want to drive to the respective US or UK sites.

localizations vs. supportedLocales vs. countryRestrictions

In the search configuration file, there are three properties that operate very differently but often get mixed up: localizations, supportedLocales and countryRestrictions.

As a reminder,

• localizations is used to provide overrides for one or more locales for synonyms or query suggestions. If you are using separate configurations for each of your languages, you don’t need to include this.

• supportedLocales is used to define what profile languages should be indexed by your search configuration. You will need to specify all language codes that are controlled by this configuration based on what’s in your Content. If you are using separate configurations for each of your languages, you don’t need to include this.

• countryRestrictions is used to define what countries should be supported by your search configuration for the sake of limiting and optimizing our location search to be most relevant to your users. You will need to specify the country codes for all entities that you want to be able to be searched by location (builtin.location). This is designed to optimize location searching and remove any unnecessary noise. (Want to get even more specific? You can add a Bounding Box to limit location searching to an even tighter area which is best for any regional brands)