Getting started

Installation

i18nix is not a package downloadable on NPM, we are in beta. We plan to make the framework open source in the near future once the framework is more mature. We want to test it out with early adopters before releasing a mature version open source.

If you wish to participate in the Beta, please reach out. Spots are limited.

Setting up the Provider, which powers the hook

The TranslationProvider component is essential for enabling the useTranslation hook, which manages the translation context for your application. To ensure all child components can access this context and maintain a synchronized locale, you should wrap your component tree with the TranslationProvider at the highest possible layer.

We recommend you place TranslationProvider in the SSR component, but it is also compatible with client components.

// This can be a SSR or client component. TranslationProvider must live on the highest component possible.
import { TranslationProvider } from "@/i18nix/translation";
 
export default function Home() {
  const initialLocale = getInitialLocale(); // example function to get the initial locale
  return (
    <>
      <TranslationProvider initialLocale={initialLocale}>
        <Page />
      </TranslationProvider>
    </>
  );
}

[Recommended] Setting up i18n Next.js routing

We highly recommend you set up i18n routing for Next.js via sub-path routing (opens in a new tab), as this is standard i18n practice. In sub-path routing for example, going to /fr/blog would take you to just the /blog route, but with the french locale.

In this documentation, we will cover setting up sub-path routing specifically for Next.js's App Router configuration.

Step 1: Install next-i18n-router

Install next-i18n-router with your favorite package manager (npm, yarn, etc). This package helps with sub-path routing

yarn add next-i18n-router

Step 2: Create i18nConfig.js

Create a i18nConfig.js file in the root folder of your Next.js project. This file configures your default locale, and the locales available. Copy the following into your i18nConfig.js at the root directory:

const i18nConfig = {
  locales: ["en", "fr", "it", "es", ...], // list of locales supported
  defaultLocale: "en",
};
 
module.exports = i18nConfig;
 

Step 3: Create middleware.js

Create a middleware.js file in the root directory, next to the i18nConfig.js file created in the previous step. The middleware.js file handles the routing by using next-i18n-router. Make sure to have the next-i18n-router installed.

import { i18nRouter } from "next-i18n-router";
import i18nConfig from "./i18nConfig";
 
export function middleware(request) {
  return i18nRouter(request, i18nConfig);
}
 
// applies this middleware only to files in the app directory, explicitly excluding /public, /api, and other shared directories.
export const config = {
  matcher: ["/((?!api|static|.*\\..*|_next).*)"],
};

Step 4: Implement dynamic routing

Create a folder [locale] in the app directory of your Next.js app. Then, move all of the folders previously in the app directory into your new directory app/[locale]. Doing this enables Next.js dynamic routing. We can extract the locale code from the route.

Old directory pattern:

New directory pattern:

All pages should be inside the [locale] parent folder. Make sure to leave the api folder out of the locale directory, we don't want to localize API's.

Step 5: Put it all together

Once you've set up the i18n dynamic routing config, we now want to pass the locale to our TranslationProvider.

import { TranslationProvider } from "@/i18nix/translation";
 
interface AboutProps {
  params: {
    locale: Locales,
  };
}
 
export default async function About({ params: { locale } }: AboutProps) {
  return (
    <>
      <TranslationProvider initialLocale={locale}>
        {...} // child components
      </TranslationProvider>
    </>
  );
}

In this example, going to the url /fr/about will render this component with the locale parameter fr passed in. The fr locale can then be passed into the TranslationProvider to initiate the locale, setting your contents to French.