Hi Johnathan,
This is a great question! We’re working on building out our multi-language training and guidance so look out for that in the training in the coming weeks! Here’s a bit of a preview of that content. To answer your specific question, scroll down to the bottom section titled Language Profiles - Implications for Answers.
What is a language profile?
In general, it’s important to understand the difference between a pure language and a locale. Locale is language dimensioned by country. Locale can account for regional differences in language – for example, in “en_us” you would spell as “behavior” but in “en_gb” you would spell as “behaviour”. But, it’s more than just dialect differences – locale has implications around date formatting, currencies, etc.
In Yext, on the Knowledge Graph side, we call the options Languages as we don’t incorporate any differences in terms of things like currency or formatting (those are dimensioned based on the entity’s country, not the country in the language). That said, other downstream products like Pages or our Listings publishers may use the country portion of the language in a meaningful way so it’s important to understand.
In Knowledge Graph, we provide a large number of language profiles to choose from. These options are structured based on the official ISO codes as “[language_code]_[country_code]”. You can also choose to select a language profile that is agnostic to country so just “[langauge_code]”. For example, here are some options for english:
- en
- en_us
- en_gb
- en_ca
In terms of what to choose, there are important consequences of what you choose and you need to be thoughtful about it – but the good thing is that is it’s very easy to change a locale for your profile. You can read more about the implications for Answers if you scroll to the bottom but the tldr is that consistency is generally very important.
Enabling Multi-Language Profiles
First off, to be able to add profiles in multiple languages, you’ll need to turn on the product feature By default, new entities will be created based on the default locale of your account’s main country. If you’re based in the US, by default your profiles will be “en”.
Here’s where you turn on the Multi-Language Profiles feature:
Once it’s on, when you return to Entity Edit for one or multiple entities, you’ll see a new Languages module on the right rail. This is your command center for your languages where you can see the profile language for the entity or entities you’re on and add or view additional profile languages.
Entities & Language Profiles
Each entity (which has a unique entity ID) can have as many language profiles as you’d like. Before you turn on the feature, you have a 1:1 relationship between entity and language profiles, but in reality an entity is really just a container for as many language profiles as you’d like to add.
When you add additional language profiles, your unique identifier for the content becomes a combination of the Entity ID + Language Profile code. You’ll need both in order to update an alternate language profile via entity upload (via an additional Profile Language column) or API. If you don’t specify a language, the system will update the primary profile.
It’s important to keep in mind that the language profile is just a “label” for the profile. We don’t provide any translations or even any validation that the content you are putting in is truly for that language. To that end, it is not of significance what language profile “label” you choose as long as you are consistent. You don’t want to have some profiles in “en” and some in “en_us” for no reason.
Field Behavior
One of the most important parts about multi-language profiles is how content is shared between profiles of different languages. There is some content that is completely independent of language, like hours or map marker. There is other content that is wholly dependent on language, like description and all other pure string fields. Other content is somewhere in the middle – you might want to share it between profiles, but you might not, like photos or videos.
We categorize the behavior of fields between language profiles into 3 types:
- Primary Only
- Overridable
- Language Specific
Primary Only - Primary only fields can only be updated on the primary profile. There is no way to override it on an alternate profile. This is used for fields like map marker, hours, linked entity custom fields or enum fields like Price Range or Payment Options where the translations are stored on the field itself. By default, custom fields are set to primary only.
Overridable - Overridable fields by default will inherit the content from the primary profile but you can choose to add language specific content if you want. This is used for fields like Name, Photo Gallery, or Videos.
Language Specific - Language Specific fields will never inherit content from the primary profile because the field is inherently specific to each language. This includes any pure string fields, like Description, Keywords, or Featured Message.
For built-in fields, Yext determines the language behavior for all fields. For custom fields, you can set the language behavior for each field:
You can change this for fields after you create them, but keep in mind that doing so could have an impact on the content that is returned for profiles (e.g., if you change a field from primary only to language specific, the content will no longer be available on alternate profiles until you explicitly fill it out).
The only field type that you cannot set the behavior for is Entity List fields. These must be primary only.
Managing Language Profiles
You can manage language profiles on Entity Edit when viewing one or multiple entities using the Language module on the right rail.
Adding, Viewing, Removing & Switching Language Profiles
From the Language module on Entity Edit, you can:
-
Add new profiles by clicking the +Add Language button. You’ll then see a modal where you can search for and select the language profile you want to add to that entity or set of entities.
-
View other language profiles by clicking on the language. This will take you to the rendered view of the profile (basically combining the content from the primary profile and data specifically on that profile to give you a completed view of the entity).
-
Remove language profiles by clicking on the “…” that appear when you hover on a language profile. This will delete the profile and all of its content so please do this carefully. If you mistakenly added “en_ca” instead of “en” you should change profile language instead of deleting the language and creating a new one.
-
Change language profiles to other languages. This allows you to change the language associated with the profile, while keeping any content you added on the profiles. This should only be done to switch the language between the country variants, e.g., “en” to “en_ca” or “en_gb” or vice versa. It should not be used to change profiles from “fr” to “de” – assuming that the content on the profile is already written out in French.
-
Set Primary Profile. You can change which language is the primary profile language. This has implications in terms of defaults sent to endpoints like Listings. For primary any overridable fields, if you have overwritten the content on the alternate profile before making it the primary profile, it will use that content for all other profiles after you switch. For example, let’s say you have a location for the brand Staples with 3 profiles:
- English (en) - primary
- French Canadian (fr_ca) - alternate
- Spanish (es) - alternate
On the fr_ca profile, you’ve overwritten the business name to reflect the brand’s name to “Bureau en Gros” as it’s known in French, but you’ve kept “Staples” as the name on the Spanish profile. If you switch the primary profile to fr_ca, the Spanish profile will now have “Bureau en Gros” as the default business name instead of “Staples”, which is what you want it to have. You’ll need to make sure you make these changes carefully so that you can put the write overrides in place.
Language Profiles - Implications for Answers
Now that I’ve provided you a full essay on how Language Profiles work, I need to answer your actual question which was: how do I know which language to choose for my entities in the context of Answers? As it turns out, language is very important for both the frontend and backend of Answers.
The most important thing to keep in mind is that for each search instance, you need a single language that is searched across entities. In other words, if you want a single English experience, you’ll need all profiles to be the same language profile – whether that’s “en” or “en_gb”. If your profiles are mixed between “en” and “en_gb” that is actually going to result in two separate search instances*, one hosted on /en/ and another on /en_gb/.
For example, if your entity profiles are spread out across different english variants like this, you won’t be able to search all of those profiles in one search experience (you’d have separate ones per locale):
Instead, if you want just one English experience, it should look like this:
That said, it is totally fine to have a “jagged language profile structure”. By this I mean that not all entities in your account must share the same exact profile languages. You can have some FAQs that have English, Spanish and French profiles and other FAQs that just have Spanish profiles. The consistency only matters to the extent that they are the same type of Spanish profiles. A jagged language profile structure will merely result in a different number of pages or result cards in each language.
On the search configuration side, we recommend creating a separate search configuration per each language you want to support (in the case that you want your search experience in multiple languages). If all verticals, searchable fields, saved filters, query rules, etc will be the same across languages, you can create one search configuration and dimension the hardcodedPrompts and synonyms by language, but over time we have seen that multi-language experiences tend to stray away from each other over time and it’s simpler to manage separate experiences. It also makes it easier to make changes for each language in isolation (e.g., if the Spanish team is ready for a new vertical now, but the English team doesn’t want it for another 3 weeks because they’re having trouble getting the data).
For the Answers frontend, coming in September, you’ll be able to create a multi-locale experience using one repository in Jambo. Until then, you need to create separate repositories per locale that you want to support.
We’re excited to release the new multi-language functionality soon. As a preview, you’ll be able to control the language behavior and url format through a new config/locale_config.json file that extracts properties like locale and experience_key from the config/global_config.json. You’ll then create separate pages for each locale that you want to support per vertical (e.g., if you want FAQs, Locations and Services in English but just FAQs and Locations in Spanish, you just won’t create the Services page in Spanish). More to come on all of this next month!
Sneak peek:
Language Profiles - Implications for Pages
Similar to Answers, language and language profile consistency matters for Pages. You’ll want to follow the same tenets of language consistency.
For Page Builder, each template can only be used for a single consistent language profile.
For Custom Development pages, the behavior is very similar to Answers. You can create multi-language page sets where there are a unique set of page urls per language profile.
Language Profiles - Implications for Listings
Some publishers will only take data in certain language profiles. For example, some Chinese publishers will only take the data from the Chinese profiles. It’s important that if you want to syndicate data to these endpoints that you provide the data in the language the publisher is looking for.
Any questions? Feel free to post in reply or add a new topic in the community. As we build out this training, we’d love any feedback you have on this post!
Thanks!