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
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 builder.get() to return the entry with localized values resolved in the response. The API processes the localization and returns content ready for rendering.
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:
// pages/your-page.js
import React from 'react';
import { BuilderComponent, builder } from '@builder.io/react';
builder.init(process.env.NEXT_PUBLIC_BUILDER_API_KEY);
export async function getServerSideProps({ req }) {
// Get the pathname from the request
const pathname = req.url;
// Fetch localized content on the server
const localizedContent = await builder
.get('your-model-name', {
userAttributes: { urlPath: pathname },
locale: 'en-FR' // add your locale here
})
.promise();
return {
props: {
localizedContent
}
};
}
export default function YourPage({ localizedContent }) {
return (
<BuilderComponent
model="your-model-name"
content={localizedContent}
/>
);
}
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.
Additionally, pass the locale as a prop to the <BuilderComponent/> to provide component-level context for rendering the correct localized content. This step isn’t required for Data models.
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:
import React, { useEffect, useState } from 'react';
import { BuilderComponent, builder } from '@builder.io/react';
builder.init(/* YOUR PUBLIC API KEY */);
export default function App() {
const [localizedContent, setLocalizedContent] = useState(null);
useEffect(() => {
function fetchContent() {
builder
.get(modelName, {
url: /* provide the pathname */,
// see https://www.builder.io/c/docs/add-remove-locales.
userAttributes: { locale: "en-FR" },
})
.promise()
.then((content) => setLocalizedContent(content))
}
fetchContent();
}, []);
return (
<BuilderComponent
locale="en-FR" // pass the locale as prop
model={modelName}
content={localizedContent}
/>
);
}
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.
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:
// orginal object with values for each locale
"greeting": {
"en-US": "Hello",
"fr-Fr": "Bonjour"
}
Builder transforms the object to use the value that corresponds to the locale, as follows:
// locale=en-US
"greeting": "Hello"// locale=fr-Fr
"greeting": "Bonjour"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:
const res = await fetchOneEntry({
model: 'page',
apiKey: /* YOUR PUBLIC API KEY */,
locale: new Intl.DateTimeFormat().resolvedOptions().locale
userAttributes: {
urlPath: window.location.pathname,
},
});
When your codebase and Builder localization are successfully integrated, you can use any Builder localization techniques.