Skip to main content

Getting Started

Let's see how you can use the NextGlobeGen package to setup i18n for your Next.js app.

If you haven't done so already, create a new Next.js app that uses the App Router.

Installation​

Next.js 15

A version of the package which is compatible with Next.js 15 is released under the latest distribution tag. To install this version of the package, run the following command.

npm install next-globe-gen@latest

Next.js 14

A version of the package which is compatible with Next.js 14 is released under next-14 distribution tag. To install this version of the package, run the following command.

npm install next-globe-gen@next-14

Setup​

To setup the package we will be creating the following file structure. The default directory and file locations can be altered by configuration, but let's use the defaults for now.

File structure
.
├── i18n.config.ts 1)
├── next.config.ts 2)
└── src
    ├── messages 3)
    │   ├── en.json
    │   └── fi.json
    ├── _app 4)
    |   ├── dashboard
    │   │   ├── i18n.ts 5)
    │   │   └── page.tsx
    │   ├── LanguageSwitcher.tsx
    │   ├── layout.tsx
    │   └── page.tsx
    ├── app
    └── middleware.ts 6)

1) Configuration​

Create an i18n.config.ts file to the application root directory and export your configuration as a default export. At least the supported locales and the default locale needs to be configured.

i18n.config.ts
import type { Config } from "next-globe-gen";

const config: Config = {
  locales: ["en", "fi"],
  defaultLocale: "en",
};

export default config;

2) Plugin​

Enable the NextGlobeGen plugin in the Next.js configuration file.

import type { NextConfig } from "next";
import createNextGlobeGenPlugin from "next-globe-gen/plugin";

const withNextGlobeGen = createNextGlobeGenPlugin();

const nextConfig: NextConfig = {
  /* Next.js config options here */
};

export default withNextGlobeGen(nextConfig);

3) Messages​

Create message translations to the src/messages directory. There should be one <locale>.json file for each configured locale.

Organizing messages
  • Messages can be divided to namespaced <locale>/<namespace>.json files.
  • The package also supports messages in YAML files using .yaml or .yml extensions.
src/messages/en.json
{
  "title": "Homepage",
  "description": "{name} package provides seamless internationalization experience for Next.js App Router devs.",
  "dashboard": {
    "title": "Dashboard",
    "projects": "You have {count, plural, =0 {no projects} =1 {<b>one</b> project} other {<b>#</b> projects}}."
  }
}

4) Routing​

Create or move your Next.js file-system based routing files into the _app directory from the app directory. All new routes should be created and modified in the _app directory.

API Reference

NextGlobeGen APIs can be used to handle navigation and rendering translations.

src/_app/layout.tsx
import { Metadata } from "next";
import { Link, useLocale, useTranslations } from "next-globe-gen";
import { ReactNode } from "react";
import LanguageSwitcher from "./LanguageSwitcher";

export const metadata: Metadata = {
  title: { template: "%s | NextGlobeGen", default: "NextGlobeGen" },
};

export default function RootLayout({ children }: { children: ReactNode }) {
  const locale = useLocale();
  const t = useTranslations();
  return (
    <html lang={locale}>
      <body>
        <header>
          <LanguageSwitcher />
          <nav>
            <ul>
              <li>
                <Link href="/">{t("title")}</Link>
              </li>
              <li>
                <Link href="/dashboard">{t("dashboard.title")}</Link>
              </li>
            </ul>
          </nav>
        </header>
        <main>{children}</main>
      </body>
    </html>
  );
}

5) Localized pathnames (optional)​

In NextGlobeGen pathnames are localized by translating each route segment (directory) separately using i18n.ts file convention.

The simplest way to add the localizations is to export an object with localized versions of the route segment for each locale as a default export.

src/_app/dashboard/i18n.ts
const segmentTranslations = {
  en: "dashboard", // If omitted, the directory name is used
  fi: "hallintapaneeli",
};

export default segmentTranslations;

With these translations, the Finnish page will be served from /fi/hallintapaneeli path.

6) Middleware (optional)​

Add middleware to the application by exporting NextGlobeGen middleware from src/middleware.ts file. The middleware handles locale negotiation and adds alternate links of the page to the response headers.

src/middleware.ts
export { middleware } from "next-globe-gen/middleware";

export const config = {
  // Matcher ignoring next internals and static assets
  matcher: ["/((?!_next|.*\\.).*)"],
};

Running the App​

After the setup has been done, start the Next.js development server and enjoy the seamless internationalization experience.

npm run dev

The NextGlobeGen plugin generates the required files for the app so that the routes can be served in the configured locales. It also re-generates the required files on the fly as long as the Next.js development server is running.

Following directories and files are generated by the NextGlobeGen plugin.

Generated directories and files
src
├── .next-globe-gen
├── .next-globe-gen.d.ts
└── app
    └── (i18n)
        ├── en
        │   ├── dashboard
        │   │   └── page.tsx
        │   ├── layout.tsx
        │   └── page.tsx
        └── fi
            ├── hallintapaneeli
            │   └── page.tsx
            ├── layout.tsx
            └── page.tsx
warning

Do not modify the generated files yourself. The package re-generates the files when necessary. Create and modify your routes in the _app directory.

tip

You can inspect what each generated file has eaten, if you would like to know how the package works under the hood.

What Next?​