Multi-Locale Support with Next.js

Adding Multi-Locale support to your Next.js site has never been easier. Next.js has built-in support for internationalized routing. You can provide a list of locales, the default locale, and even domain-specific locales and Next.js will automatically handle routing for you.

Adding a New Locale in Agility

Agility CMS offers unlimited Locales for free right out of the box to help you Initialize and create pages and content in multiple languages.

To add a new Locale, head to Settings > Locales in the content manager, then click + New.

Adding Locales to Your Next.js Site

Note

The following example is based on the our Next.js Blog Starter.

In the Next.js Blog Starter, you will have a .env.local file that is used to store secret information about your site such as your API Keys, Security Key, GUID, and Locales.

Add the Locales you have configured within your instance to AGILITY_LOCALES, if you have multiple locales, separate them with a comma (no space).

In this example, we'll be using English and French locales:

# get these values from the API Keys page in Agility Settings => https://manager.agilitycms.com/settings/apikeys
 AGILITY_GUID=YOUR_GUID
 AGILITY_API_FETCH_KEY=YOUR_API_FETCH_KEY
 AGILITY_API_PREVIEW_KEY=YOUR_API_PREVIEW_KEY
 AGILITY_SECURITY_KEY=YOUR_SECURITY_KEY

 # if you have multiple locales, comma separate them (e.g: en-us,fr-ca) without a space
 AGILITY_LOCALES=en-us,fr-ca
 AGILITY_SITEMAP=website

Updating the next.config.js file

To support internationalized routing in your Next.js site, Add the i18n config to your next.config.js file and add the locales you wish to support, along with the default locale you want to use.

module.exports = {
  ...
  i18n: {
    // These are all the locales you want to support in your application
    locales: ["en-us", "fr-ca"],
    // This is the default locale you want to be used when visiting
    // a non-locale prefixed path e.g. `/hello`
    defaultLocale: "en-us",
  },
};

Live Example

The next time your Next.js site builds, it will sync the pages and content from the locales configured, and you will be able to access your pages and content in each locale, e.g:

English (Default Locale): https://agilitycms-nextjs-multi-locale.vercel.app

French: https://agilitycms-nextjs-multi-locale.vercel.app/fr-ca

How to Access Available Locales Within the Site

To access available locales within the site, you will need to update the [.../slug].js and Layout.js files in the Next.js Blog Starter.

[...slug].js

Update the return in getStaticProps to also pass locales as props.

 return {
    // return all props
    props: {
      agilityProps,
      locales,
    },
    ...
  };

Layout.js

Update the Layout component to also retrieve locales as props. In this example, we are passing locales into the Site Header component, which can then be used to create a language toggle.

function Layout({ agilityProps, locales }) {
  
  const {
    page,
    sitemapNode,
    dynamicPageItem,
    notFound,
    pageTemplateName,
  } = agilityProps;
  ...
  return (
    <>
      <SEO
        title={sitemapNode?.title}
        description={page.seo.metaDescription}
        keywords={page.seo.metaKeywords}
        metaHTML={page.seo.metaHTML}
      />
      <div id="site-wrapper">
        {isPreview && <LoadingWidget message="Loading Preview Mode" />}
        {!isPreview && (
          <div id="site">
            <PreviewBar {...agilityProps} />
            <div className="flex flex-col min-h-screen">
              <SiteHeader {...agilityProps} locales={locales} />
              <main className="flex-grow">
                <AgilityPageTemplate {...agilityProps} />
              </main>
              <SiteFooter {...agilityProps} />
            </div>
          </div>
        )}
      </div>
    </>
  );
}