Multi-Language Frontend | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• Refresher of locale_config.json file
• How to set up multiple languages
• How to set translation file paths
• How to set up URL formatting
• Nuances for Live Previewing your different languages

Overview

The locale_config.json and global_config.json files help to define the scope of your experience and how it connects to:

1. The SDK Version specified in the global_config.json
2. The Search Configuration via the experienceKey for identifying which results to show
3. Content via the locale for identifying which content to surface on search results and which translations to pull in from the SDK.

Learn more about these files in the Global Settings and Local Configuration reference doc.

When you set up a single-language experience, you really just need to update three things (check out the Navigating the Code Editor unit for a refresher):

1. experienceKey (in locale_config.json)
2. locale (in locale_config.json) - This defaults to ‘en’.
3. cloudRegion (in global_config.json) - This defaults to ‘us’.
4. cloudChoice (in global_config.json) - This defaults to ‘multi’, which uses any of our consumer serving regions powered by AWS or GCP. Update to ‘gcp’ to limit queries to only use the GCP-based regions. This will also direct analytics events to a GCP-only events URL.

When you are building a multi-language experience, you can also set things like:

• Fallback behavior across languages to inherit page configuration or layout when not specified (more on this in Unit 4 )
• Translation file paths so the system knows where any of the custom translations you provide are located in the directory (more on how to update translation files in Unit 5 )
• URL Override if you want a certain locale’s url path to be different than the default patternset in the urlFormat object (more on this below)
• Params that are arbitrary strings you want to make available to hbs templates for a given locale (e.g., for a header or footer) (more on this below)

The locale_config.json File

The locale_config.json file has three main components:

1. default locale - this is required and the template repo defaults to “en”
2. localeConfig - this is where you add locale-specific configuration, like the experienceKey
3. urlFormat - this determines the url format of the pages that are generated

If you’re building a site in English, French and German, your locale_config.json might look like this:

{
  "default": "en",
  "localeConfig": {
    "en": {
      "experienceKey": "brand_en" //  the unique key of your search configuration for this locale
    },
    "fr": {
      "urlOverride": "france/{pageName}.{pageExt}", // provide an override for the url path for this locale if you want it to be different than specified in the urlFormat object
      "translationFile": "fr.po", // the path, under the 'translations' directory, to the locale's .po file
      "experienceKey": "brand_fr" //  the unique key of your search configuration for this locale
    },
    "de": {
      "fallback": ["fr"], // allows you to specify locale fallbacks for this locale
      "translationFile": "de.po", // the path, under the 'translations' directory, to the locale's .po file
      "experienceKey": "brand_de" //  the unique key of your search configuration for this locale
    }
  },
  "urlFormat": {
    "baseLocale": "{language}/{pageName}.{pageExt}",
    "default": "{pageName}.{pageExt}"
  }
}

For each language that you want included in your experience, you will need to include it in the localeConfig object. The only required sub-property is experienceKey, which as we covered in Unit 1, can either be the same across locales or unique per locale (or some combination thereof!). The fallback, translationFile and urlOverride properties are not required and are for more advanced builds / use cases.

Note

Certain features are not supported in every language, so we recommend setting a fallback for any locales outside of the six core languages listed in the Supported Languages reference doc .

Remember that the locale you set will correspond to the language in the SDK. For example, if you set the locale as “fr_ch” it will send “fr” to the SDK. The SDK only supports a limited number of languages so if you specify a language that is not supported you will see an error in the console (and, sadly, you won’t see any components load on the page). When you set the locale, any frontend strings that are defined by the SDK will be returned in that language automatically.

URL Format

By default, we recommend setting your URL Format to:

"urlFormat": {
  "baseLocale": "{language}/{pageName}.{pageExt}",
  "default": "{pageName}.{pageExt}"
}

Let’s go through what each of these are:

• language is the language code, e.g., “en” or “en_GB”
• pageName is the name of the page file, like “locations” or “index”
• pageExt is the file type, typically html

During the Jambo build step, the correct values will be substituted into the template string.

In urlFormat.default, you are specifying the URL path for the default locale’s pages. For any other locale, the urlFormat.baseLocale is used. These paths are all relative to the desktop directory.

If your domain is “search.brand.com”, then the object defined above would produce pages like:

Universal Search

• search.brand.com/index.html
• search.brand.com/fr/index.html
• search.brand.com/de/index.html

Vertical Search - Locations

• search.brand.com/locations.html
• search.brand.com/fr/locations.html
• search.brand.com/de/locations.html

If you want to break the pattern for a specific locale, you can specify that in the urlOverride (again, keep in mind it’s all relative to the desktop directory):

"fr": {
  // "fallback": [""], // allows you to specify locale fallbacks for this locale
  "urlOverride": "france/{pageName}.{pageExt}", // provide an override for the url path for this locale if you want it to be different than specified in the urlFormat object
  "translationFile": "fr.po", // the path, under the 'translations' directory, to the locale's .po file
  "experienceKey": "brand_fr" //  the unique key of your search configuration for this locale
},

This would change the urls above to:

• search.brand.com/france/index.html
• search.brand.com/france/locations.html

Custom Params

In a more advanced build, you can include a params property within the locale object to specify arbitrary parameters. These values will be made available by Jambo to any HBS partial it compiles. One common use case for the object will be the locale’s site attributes. Here’s an example:

"fr": {
  "experienceKey": "french-experience",
  "params": {
    "CustomFrenchVar": "Ouais",
    "SiteAttributes": {
      "French": "Wine"
    }
  },
  "urlOverride": "/vive/la/france/{pageName}.{pageExt}"
},

Using Live Preview

Live Preview will work exactly the same. To toggle between languages in the frontend, you’ll just need to modify the URL path to match what you specify in the locale_config.json file. For example, if you are leaving the url settings on the default, you would just need to add in the “/languageCode” at the end of the preview URL.

Ex default urls for universal and locations vertical:

• livepreview.sandboxlandingpagespreview.com/
• livepreview.sandboxlandingpagespreview.com/locations

Example modification for “es” locale

• livepreview.sandboxlandingpagespreview.com/es
• livepreview.sandboxlandingpagespreview.com/es/locations