In the Builder Visual Editor, you can configure individual fields to deliver content specific to language and region preferences.
For example, if you wanted to differentiate copy or images for a visitor in Germany or a visitor in Mexico, you could adjust a few settings on the block and add locale-specific content in the block's localization settings.
To successfully use localization in Builder, make sure you've already done the following:
Use inline localization when you want to maintain the same structure a content entry across different locales while changing only individual pieces of content depending on the locale.
If you need a content entry to display a different structure depending on locale, consider using entry-level localization to Localize a Whole Entry.
You can individually localize many blocks in the Visual Editor including the following:
- Text
- Images
- Colors
- Symbol inputs
The process is the same for each in that you hover over the label in the Edit dialogue to show the Localize icon, click the icon, and add content to each locale.
- Double click the block you want to localize to open the Edit dialogue.
- Hover over the label of the block; for example, the label Text in a Text edit dialogue, and click the Localize icon.
- In the locale dropdown, choose the locale you'd like to edit. As a best practice, always set a value for the Default locale in case none of the other locales are in the user's settings.
- Enter content per locale.
While an individual block's locale is displayed in the Options tab for that block, you can also choose the locale for the whole entry at the top of the Visual Editor. This is helpful if you've used inline localization on a number of the blocks in a content entry and want to display the content entry as it renders for a given locale.
The following video demonstrates adding localized content with two examples:
- A Text block
- An Image block
This video also shows how to select the locale for the entire content entry.
Tip: If you don't have any locales, click the link to Add a new locale, which displays when you hover over the locales dropdown. You can also add multiple locales in a single dialogue as outlined in Adding Locales.
To enable field localization, explicitly mark them as localized in the model settings. This ensures that the content within those fields can be customized based on different languages or regions.
- Go to Models.
- Open the model that contains the field you want to localize.
- Create a field if needed, or if the field already exists, expand it by clicking the disclosure chevron.
- Click on the Localize toggle. When you toggle this on, more options display.
- Enter values for each locale. As a best practice, always enter a value for the Default locale.
- Click Save when you are done.
The video below shows how to localize a field in a model.
Additionally, you can localize inputs by clicking on the globe icon within the Edit dialogue. This way you can provide localized values for inputs such as text or images.
By default, all inputs can be localized unless you specifically set the localized property to false when registering your custom component. This gives you flexibility in deciding which inputs can be localized and which ones should remain static across different locales.
To customize content for specific groups of people within your different language options, you can use targeting, and within this targeted content, you can localize inputs or fields.
To use this feature:
- Pass the
localeproperty to theBuilderComponentwhen integrating Builder into your app. This ensures that the content in the Visual Editor is localized based on the specified locale. - When making an API call to retrieve the content, include the
localeparameter, and pass the currentlocalevalue. This makes sure that the content returned from the API call is specific to the desiredlocale.
This streamlined process makes the localization workflow more direct, helping you efficiently manage localized content within the Builder environment, without the need for additional data connections.
const content = await builder.get(model, {
// Pass the locale property to the options object
// for inline localization. For content-level localization
// you would pass locale in the userAttributes object
options: { locale },
// or you can pass locale as a top level param
locale
}).toPromise();
If you no longer need a block to have localized content but still want to keep the block itself, you can remove inline localization from that specific block.
Be cautious if you're considering deleting a block, as deleting a block removes it from all locales, regardless of the currently selected locale. If you need the block to remain in the content entry, make sure to remove localization rather than deleting the block entirely.
To remove localization from a selected block:
- Open the Edit dialogue for the block. Do this by double-clicking the block or selecting the block and clicking the Edit button.
- This step deletes the localized content. Hover over the dialogue label and click on the Localize icon.
By toggling off localization for a block, the localization dropdown no longer displays, and the content is removed. The following video demonstrates this process.
