Livestream: Implement features in your webapp with AI

Announcing Visual Copilot - Figma to production in half the time

Builder logo
builder.io

Livestream: Implement features in your webapp with AI

Announcing Visual Copilot - Figma to production in half the time

Blog

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

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.

Was this article helpful?

Get the latest from Builder.io

© 2025 Builder.io, Inc.

Security

Privacy Policy

SaaS Terms

Compliance

Cookie Preferences

Gartner Cool Vendor 2024