Next.js API

@linguanahq/next integrates Linguana with Next.js 16 App Router. Peer dependencies: next >=16 <17, react and react-dom >=19 <20. Follow the Next.js guide for setup.

Entry points

@linguanahq/next/server is marked server-only; importing it into a Client Component fails the build. @linguanahq/next/compiler-runtime and @linguanahq/next/loader are used by compiled output and the bundler; do not import them directly.

withLinguana(options)

import { withLinguana, type LinguanaNextOptions } from "@linguanahq/next/plugin";

export default withLinguana(options)(nextConfig);

Returns a function that accepts a NextConfig object or a Next.js configuration function (sync or async) and returns an async configuration function. Options are validated immediately.

Unlike the Vite plugin, providing a token does not enable upload; set upload: true explicitly.

translation

translation: {
  enabled: true,
  maxChargeMicros: 100_000,
  waitTimeoutMs: 300_000,
  publish: "development",
}

Requires upload: true, token, environment: "development", enabled: true, and publish: "development". maxChargeMicros must be a positive safe integer; waitTimeoutMs, when set, must be positive. Build translation behaves as described in the Vite integration API.

runtime

Runtime options are serialized into public configuration and shipped to the browser. Put only browser-safe values here.

LocaleOption has code, displayName, and nativeName, plus optional tier and fallbackLocale.

Configuration behavior

• Adds the Linguana loader for *.js, *.jsx, *.ts, and *.tsx to Turbopack rules (excluding dependencies) and as a webpack pre-loader (excluding node_modules), before your existing rules.
• Writes public runtime configuration to .linguana/next/runtime.json when it changes.
• After a successful next build compilation, scans eligible source, writes the manifest, and uploads it when upload is enabled. This runs once per build and composes with your own compiler.runAfterProductionCompile hook.
• Applying withLinguana twice with the same options is a no-op; different options fail.

Default exclusions

Dependencies (node_modules), .next, .linguana, .git, dist, build, .output, and coverage directories; tests (*.test.*, *.spec.*, __tests__); declarations (*.d.ts); configuration files (*.config.*); next-env.d.ts; and the Next.js output directory.

LinguanaProvider

import { LinguanaProvider } from "@linguanahq/next/server";

<LinguanaProvider>{children}</LinguanaProvider>

Async Server Component for the root layout. It reads the request's cookies and Accept-Language header, resolves the language and catalogs, and provides them to Server and Client Components beneath it. Takes only children; configuration comes from withLinguana.

getLocale()

const locale: string = await getLocale();

Returns the language resolved for the current request. Use it for <html lang>.

getTranslations()

const { locale, t, translate } = await getTranslations();

Wrap results in String() where a string is required, such as metadata titles. Resolution runs once per request and is shared by every server helper.

T

import { T } from "@linguanahq/next";

<T id="guide-link" defaultMessage="Read <link>the guide</link>" components={{ link: <a href="/guide" /> }} />

Props match the React T component: id?, required defaultMessage, values?, components?, and context?. In Server Components it is an async component; in Client Components it uses the client runtime.

useTranslation()

"use client";
import { useTranslation } from "@linguanahq/next/client";

const { locale, t, setLocale, ready, availableLocales, diagnostics } = useTranslation();

Returns the React useTranslation() values with Next.js language switching:

setLocale ignores languages not in availableLocales. If the target catalog cannot be loaded within five seconds or fails verification, the current language stays and a catalog-load-failed diagnostic is added. Throws Next.js translations require LinguanaProvider in the root layout. outside the provider.

LanguageSelector

import { LanguageSelector } from "@linguanahq/next/client";

<LanguageSelector label="Language" className="language" />

Renders a search input and an accessible select listing nativeName — displayName for each language. The select is disabled while a change is in progress. The root element has the data-linguana-language-selector attribute for styling.

Hosted requests

With publishableKey and an endpoint, the server reads:

• GET {configEndpoint}/api/v1/runtime/projects/{projectId}/environment/{environment} for languages, when availableLocales is not set.
• GET {catalogEndpoint}/api/v1/catalogs/{projectId}/{environment}/{locale} for a target catalog not embedded.

Requests send the x-linguana-key header, bypass the Next.js data cache, and time out after five seconds. See Catalog delivery.

Diagnostics

Server diagnostics are written with console.warn and prefixed [linguana]. They include catalog verification and loading failures, and missing-translation and invalid-translation events, sampled once per message per request. Client diagnostics are available through useTranslation().diagnostics with the codes described in the React API.

Configuration errors

See Next.js troubleshooting for fixes.

See also

Next.js guide · React API · Environment variables