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:
- The SDK Version specified in the global_config.json
- The Search Configuration via the experienceKey for identifying which results to show
- 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):
experienceKey
(inlocale_config.json
)locale
(inlocale_config.json
) - This defaults to ‘en’.cloudRegion
(inglobal_config.json
) - This defaults to ‘us’.cloudChoice
(inglobal_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:
default
locale - this is required and the template repo defaults to “en”localeConfig
- this is where you add locale-specific configuration, like the experienceKeyurlFormat
- 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.
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