Integrate Builder Localization with your code
Pro plans
Publish
To localize content with Builder, integrate localization into the codebase to keep the app and Builder content in sync. You can choose one of two approaches:
- Inline localization
- Content entry localization
Inline localization
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements for each locale, such as text or images.
When using the Content API, set the locale parameter when calling builder.get() to return the entry with localized values resolved in the response. The API processes the localization and returns content ready for rendering. Pass the locale as a prop to the <BuilderComponent> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to render.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements for each locale, such as text or images.
When using the Content API, set the locale parameter when calling builder.get() to return the entry with localized values resolved in the response. The API processes the localization and returns content ready for rendering. Pass the locale as a prop to the <BuilderComponent> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to render.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements for each locale, such as text or images.
When using the Content API, set the locale parameter when calling builder.get() to return the entry with localized values resolved in the response. The API processes the localization and returns content ready for rendering. Pass the locale as a prop to the <BuilderComponent> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to render.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements for each locale, such as text or images.
When using the Content API, set the locale parameter when calling builder.get() to return the entry with localized values resolved in the response. The API processes the localization and returns content ready for rendering. Pass the locale as a prop to the <BuilderComponent> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to render.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements for each locale, such as text or images.
When using the Content API, set the locale parameter when calling builder.get() to return the entry with localized values resolved in the response. The API processes the localization and returns content ready for rendering. Pass the locale as a prop to the <BuilderComponent> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to render.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
In your +page.js file, fetch the entry with the locale parameter:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
Resolver to fetch the data from the server:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements for each locale, such as text or images.
When using the Content API, set the locale parameter when calling builder.get() to return the entry with localized values resolved in the response. The API processes the localization and returns content ready for rendering. Pass the locale as a prop to the <BuilderComponent> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to render.
The following example shows fetching and rendering inline-localized content:
Use inline localization to manage locale-specific content within a single entry by localizing individual fields. This approach maintains consistency across entries while customizing specific elements, such as text or images, for each locale.
When using the Content API, set the locale parameter at the root level when calling fetchOneEntry() to return the entry with localized values resolved in the response. Pass the locale as a prop to the <Content> component to provide component-level context for rendering the correct localized content.
The locale value is a string, such as "en-FR", that specifies which localized version of the content to resolve.
The following example shows fetching and rendering inline-localized content:
- For inline localization, set the
localein theoptionsobject when callingbuilder.get()to return content with localized fields in the response. - Additionally, provide the
localeas a prop to theBuilderComponentto provide component-level context so that the Visual Editor and runtime display the correct localized content. However, this step isn't required for Data models. - The
localeproperty is a string that specifies the locale for rendering the content, in this example,"en-FR".
Content entry localization
Use Whole-content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter when calling builder.get() to fetch the localized entry that matches the targeting rules.
The locale value is a string, such as "en-FR", that specifies which localized entry to render.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use Whole-content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter when calling builder.get() to fetch the localized entry that matches the targeting rules.
The locale value is a string, such as "en-FR", that specifies which localized entry to render.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use Whole-content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter when calling builder.get() to fetch the localized entry that matches the targeting rules.
The locale value is a string, such as "en-FR", that specifies which localized entry to render.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use Whole-content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter when calling builder.get() to fetch the localized entry that matches the targeting rules.
The locale value is a string, such as "en-FR", that specifies which localized entry to render.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use Whole-content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter when calling builder.get() to fetch the localized entry that matches the targeting rules.
The locale value is a string, such as "en-FR", that specifies which localized entry to render.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example shows fetching and rendering a fully localized content entry using content entry localization:
In your +page.js file, fetch the entry and pass the locale:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Resolver to fetch the data from the server:
Use Whole-content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter when calling builder.get() to fetch the localized entry that matches the targeting rules.
The locale value is a string, such as "en-FR", that specifies which localized entry to render.
The following example fetching and rendering a fully localized content entry using Content entry localization:
Use content entry localization to manage separate entries for each locale. This approach returns a fully localized entry by targeting the locale as a user attribute, rather than resolving individual fields at runtime.
When using the Content API, set the locale as a targeting attribute in the userAttributes parameter to fetch the localized entry that matches your targeting rules. For example, in fetchOneEntry(), include the locale in the userAttributes parameter.
The locale value is a string, such as "en-FR", that specifies which localized entry to return.
The following example fetching and rendering a fully localized content entry using Content entry localization:
The following example defines a route for the /my-page endpoint. When a user navigates to this endpoint, the app makes a request to the Builder API to fetch the HTML content for the specified URL, req.url.
To retrieve the localized content, the code sets:
- the
localequery parameter in the request URL to the desired locale value,myLocale - the
userAttributes.localequery parameter to the same value.
These query parameters allow Builder to know which locale to use when resolving any localized values in the content.
This code snippet localizes the entire page by passing the locale and userAttributes.locale parameters in the URL query string when fetching the page content from the Builder API.
This tells Builder to return the content with the appropriate localized values based on the specified locale.
The following is an example of specifying a locale in the class and then using the locale in the template:
In the MyComponent class, define the options object with userAttributes and locale properties:
- The
userAttributesproperty is an object that contains thelocaleproperty with the value ofmyLocale. - The
localeproperty is also set tomyLocale.myLocalecan be any locale that you have added to your Builder account.
In the MyComponent template, use the builder-component element with a model attribute set to page and the options attribute is set to the options object, defined in the class.
With this configuration, when the component is rendered, Builder uses the options object to fetch the content for the page model with the specified myLocale locale. The userAttributes property in the options object is used to identify the current user's locale.
Localization with Data models
Integrating localization with Builder Data models is the same as with Page or Section models except that you don't render anything in your code for a Data model. This means that for integrating a Data model, you don't need BuilderComponent for Gen 1 or Content for Gen 2 SDKs.
For more detail on setting up localization in the Builder Data model UI, visit Localizing Data Models.
How Builder transforms objects with locale values
For example, given a greeting object with localized values for en-US and fr-Fr, Builder transforms it to Hello or Bonjour depending on the locale:
Builder transforms the object to use the value that corresponds to the locale, as follows:
Deriving the locale
Ideally, you want your app to dynamically adjust to the user's locale.
You can automatically determine the user’s locale based on their system settings by using the Intl.DateTimeFormat() locale and passing it into the locale option:
Solve common issues
You might encounter "[object Object]" displaying instead of your localized text content. This typically occurs when localized fields are not properly resolved.
To solve this issue:
- When using inline localization, ensure you are passing the
localeinto both the API call and the component. - If using the Web Components API, pass locale information into the
optionsattribute rather than alocaleattribute, as shown below.
- If dynamically setting the locale with
setUserAttributes(), ensure the code calling the function is defined before Builder scripts are loaded. - Update your Builder SDK version.