@nimpl/i18n
v4.0.0
Published
i18n library for working with translations in server and client components
Maintainers
vordgiReadme
@nimpl/i18n
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
Installation
npm i @nimpl/i18nWhy This Library?
Most 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.
Quick Start
1. Create i18n Configuration
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,
});2. Set Up Routes
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>
);
}3. Use Translations
// app/[lang]/page.tsx
import { getTranslation } from "@/i18n";
export default async function Page() {
const { t } = await getTranslation();
return <h1>{t("home.title")}</h1>;
}API
initialize
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);Config Options
| 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) |
getTranslation
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")Transmitter
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>ServerTranslation
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 }}
/>useTranslation
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" });ClientTranslation
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" /> }}
/>
);
}revalidate
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);Variable Interpolation
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: "Server-Side Query Injection
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>Namespaces
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");Notes
- 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
Examples
License
MIT