Field Behavior | Yext Hitchhikers Platform
What You’ll Learn
In this section, you will learn:
- How fields behave on multi-language profiles
- How to set the language behavior on custom fields
- How to add custom field option translations
Overview of Field Behavior
As you learned in the last unit, an entity is made up of a collection of language profiles. Each language profile contains a set of fields that have content. One of the most important parts about multi-language profiles is how content is shared between profiles of different languages.
For example, there is some content that is completely independent of language, like hours or a map marker. There is other content that is wholly dependent on language, like a 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.
So, what if all of your content doesn’t need to be translated? Do you have to set all content on each profile separately?
The short answer is no! The long answer… is the rest of this unit.
Alternate Profile Language Profile
Any content that is on your primary profile is your primary language content. It cannot be inherited from other language profiles. But, alternate language profiles can inherit the content from the primary profile depending on the behavior of the field.
We categorize the behavior of fields between language profiles into 3 types:
- Primary Only
- Language Specific
When you hover over a field on an alternate profile, you’ll see a tool-tip that tells the behavior for that field.
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 do this when you create the field or after you create the field by modifying the “Alternate Language Behavior” property of the 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).
Best Practices for Setting Language Behavior on Custom Fields
With custom fields, you have full freedom to set the behavior as you’d like. But with great power comes great responsibility! You should be thoughtful about what you choose and we recommend following some high level guidelines:
- If it’s text based, it should be language-specific. The exception here would be if it is a proper noun or brand names
- If it’s an option-type field, it’s usually best to be primary-only, unless the options truly do vary by language (more on that in the next section).
- If it’s a photo, we recommend overrideable so you can choose to vary the content by language when it makes sense, but you don’t have to
Adding Custom Field Option Translations
When you make custom fields that have options (e.g., the single-option select or multi-option select fields), you can also add translations for those options.
How to Add the Translations
In the field specification property for an option custom field, you will see a link to “+Add translation”. When you click on this link, you can select the language for which you want to add translations, add in the translations and click “Save”. You can add as many translations as you would like.
How are the Translations Used
It’s important to understand how custom field option translations are used.
- They will appear for users based on browser language or the display language setting in Account Settings if a translation exists for their browser language. If one doesn’t exist, it will fallback on the primary language.
- They will appear when the field option values are used as display content on Pages or Search. For example, if you want to display an option field in a subtitle of a card, it will show the field translation if it exists.
While it’s important to translate your options for option fields (when relevant), it’s also important to think about when an option field should be primary only vs. overridable vs. language-specific. In most cases, option-fields should be set to Primary Only if the field is talking about the definition of the entity, like a “type selector” or a list of “features”. The options selected should be true regardless of the language. However, there are some cases where you might want to make an option custom field overridable or language-specific, in particular if it’s about things like services offered in a given language.