i18n library designed for React Server Components with maximum optimization (due to the transfer of logic to the assembly stage and/or server side).
Read the documentation in a convenient interface at nimpl.dev/docs/i18n
npm i @nimpl/i18nMost i18n libraries either load the entire dictionary on the client or disable static optimization when working with Server Components.
This library resolves translations on the server. Client components only receive the specific precompiled keys they need through the Transmitter wrapper - not the whole dictionary. Pages remain statically generated with translations baked into the HTML.
Create a configuration file (e.g., src/i18n.ts):
import { initialize } from "@nimpl/i18n/initialize";
import fs from "fs/promises";
export const { getTranslation, ServerTranslation, Transmitter, revalidate } = initialize({
load: async (language) => {
const data = await fs.readFile(`./translations/${language}.json`, "utf-8");
return JSON.parse(data);
},
getLanguage: async () => {
// Use next/root-params, @nimpl/getters, @nimpl/context or implement your own language detection
const { params } = await import("@nimpl/getters/get-params").then(m => m.getParams());
return params.lang as string;
},
languages: ["en", "de", "fr"],
cache: true,
});app/
[lang]/
layout.tsx
page.tsx
// app/[lang]/layout.tsx
export default function RootLayout({
children,
params,
}: {
children: React.ReactNode;
params: { lang: string };
}) {
return (
<html lang={params.lang}>
<body>{children}</body>
</html>
);
}// app/[lang]/page.tsx
import { getTranslation } from "@/i18n";
export default async function Page() {
const { t } = await getTranslation();
return <h1>{t("home.title")}</h1>;
}Creates configured i18n functions. Call once and export the returned functions.
import { initialize } from "@nimpl/i18n/initialize";
export const { getTranslation, ServerTranslation, Transmitter, revalidate } = initialize(config);| Option | Type | Required | Description |
|---|---|---|---|
load |
(language: string) => Promise<object> |
Yes | Async function that returns translations for a language |
getLanguage |
() => Promise<string> |
Yes | Function to determine current language |
languages |
string[] |
Yes | Array of supported language codes |
cache |
boolean |
No | Enable translation caching (recommended for production) |
Server-side function for translations in React Server Components.
import { getTranslation } from "@/i18n";
export default async function Page() {
const { t, language } = await getTranslation();
return <h1>{t("home.title")}</h1>;
}With explicit language (useful for generateMetadata):
export async function generateMetadata({ params }: { params: { lang: string } }) {
const { t } = await getTranslation({ language: params.lang });
return { title: t("home.meta.title") };
}With namespace:
const { t } = await getTranslation({ namespace: "home" });
t("title"); // Equivalent to t("home.title")Server component that passes translations to client components. Wrap client components that need translations.
import { Transmitter } from "@/i18n";
import Counter from "./Counter";
export default async function Page() {
return (
<Transmitter terms={["counter", "shared.buttons"]}>
<Counter />
</Transmitter>
);
}With explicit language:
<Transmitter terms={["counter"]} language="fr">
<Counter />
</Transmitter>Server component for complex translations with embedded JSX.
import { ServerTranslation } from "@/i18n";
// Translation: "Read our <link>documentation</link> for more info"
export default async function Page() {
return (
<ServerTranslation
term="home.description"
components={{ link: <a href="/docs" /> }}
/>
);
}With variables:
// Translation: "We have <b>{{count}}</b> products"
<ServerTranslation
term="products.count"
components={{ b: <strong /> }}
query={{ count: 42 }}
/>Client-side hook. Requires Transmitter in a parent Server Component.
"use client";
import { useTranslation } from "@nimpl/i18n/use-translation";
export default function Counter() {
const { t } = useTranslation();
return <button>{t("counter.increment")}</button>;
}With namespace:
const { t } = useTranslation({ namespace: "counter" });Client component for complex translations with embedded JSX.
"use client";
import { ClientTranslation } from "@nimpl/i18n/client-translation";
// Translation: "Read our <link>documentation</link>"
export default function Info() {
return (
<ClientTranslation
term="info.description"
components={{ link: <a href="/docs" /> }}
/>
);
}Refresh cached translations for a language.
import { revalidate } from "@/i18n";
// Foreground revalidation (blocks until complete)
await revalidate("en");
// Background revalidation (non-blocking)
await revalidate("en", true);Use {{variable}} syntax in translations:
{
"greeting": "Hello, {{name}}!",
"items": "You have {{count}} items"
}t("greeting", { query: { name: "Alex" } });
// → "Hello, Alex!"
t("items", { query: { count: 5 } });
// → "You have 5 items"Use removeUnusedQueries to strip undefined variables:
// Translation: "Hello, {{name}}! Role: {{role}}"
t("welcome", { query: { name: "Alex" }, removeUnusedQueries: true });
// → "Hello, Alex! Role: "Pass dynamic values to client translations from the server to improve client performance:
<Transmitter
terms={[
"pricing",
["welcome", { query: { stage: process.env.NODE_ENV } }],
]}
>
<ClientComponent />
</Transmitter>Access nested keys with dot notation or colon prefix:
// Dot notation
t("header.nav.home");
// Namespace in options
const { t } = await getTranslation({ namespace: "header" });
t("nav.home");
// Colon prefix (overrides default namespace)
t("footer:copyright");- Client components (
useTranslation,ClientTranslation) inherit language from server parents - The
termsarray accepts namespace prefixes (e.g.,"nav") or specific keys (e.g.,"nav.home") - Use
next/root-params,@nimpl/gettersor@nimpl/contextfor automatic route parameter detection
MIT