Skip to content

Integrations

React

The official React 18/19 package for Verbaly. Hooks over the same reactive core, a compiler-aware <Trans> for rich text, and keys + params fully typed.

What you can accomplish:

Installation

Add the runtime, this package and the Vite plugin, then the compiler, which is where the verbaly command lives. init writes your config and your source catalog.

 pnpm add verbaly @verbaly/react @verbaly/vite
 pnpm add -D @verbaly/compiler
npx verbaly init

Then add verbaly() to the plugins in vite.config. It writes verbaly/app, the module your components read.

On webpack, Rollup, esbuild or Rspack, install @verbaly/unplugin in place of @verbaly/vite: other bundlers shows how.

Setup & hooks

App.tsx
import { VerbalyProvider, useT, useLocale } from '@verbaly/react';
import { verbaly } from 'verbaly/app';

<VerbalyProvider instance={verbaly}>
  <App />
</VerbalyProvider>

function Inbox({ count }) {
  const t = useT();
  const [locale, setLocale] = useLocale();
  return <p>{t`You have ${count} messages`}</p>;
}

The language a visitor picks

setLocale from useLocale() switches every component, and the page follows: <html lang>, <html dir> and the choice, saved in the browser. A single-page app starts in its source language, so read that choice back before the first render:

main.tsx
// the saved choice, else the browser's, loaded before anything renders
import { resolveLocale } from 'verbaly';
import { locales, setLocale } from 'verbaly/app';

setLocale(resolveLocale({ supported: locales, path: false })).then(() => {
  createRoot(document.getElementById('root')!).render(<App />);
});

Where a server renders the page, as in Next.js, switch with useSwitchLocale from @verbaly/next/client instead: it also sets the cookie the server reads.

Write the text in place

The compiler reads your .tsx files: write the source text with t and it is extracted, keyed and typed on save. No key to invent, no catalog to touch.

Inbox.tsx
<p>{t`You have ${count} messages`}</p>

// extracted on save; the build rewrites it to:
<p>{t('nUDFBXR5', { count })}</p>

Prefer readable keys? t.id('inbox.title') before the template extracts under your id instead of a content hash.

Prefer to keep the text in your catalog? Write only its key: it is checked and typed the same way. See Keys and catalogs.

Rich text with <Trans>

Write the source text in place and the compiler extracts it, exactly like t`…`:

Agree.tsx
import { Trans } from '@verbaly/react';

// you write:
<Trans>Read the <a href='/terms'>terms</a> before continuing</Trans>

// the compiler extracts "Read the <a>terms</a> before continuing" and rewrites to:
<Trans id='x7Ka9q2f' components={{ a: <a href='/terms' /> }} />

Next.js

Server Components render already translated in the visitor's language, and Client Components start with the same language and catalog: no flash of untranslated text, no mismatch between server and browser.

Next.js needs the integration (@verbaly/next) alongside the React package and the compiler:

 pnpm add verbaly @verbaly/next @verbaly/react
 pnpm add -D @verbaly/compiler
npx verbaly init

Wire it up

Wrap your config with withVerbaly. It wires live extraction in dev and the message compiler on Turbopack and webpack. Once next build has compiled, it lists what verbaly check would fail on, so a command that only loads your config, like next typegen, never meets that report:

next.config.ts
import { withVerbaly } from '@verbaly/next';

export default withVerbaly({ /* your Next config */ });

// locales live in your verbaly.config (npx verbaly init), where verbaly check reads them too

In the root layout, getVerbalyProps serializes the negotiated language and its catalog, and VerbalyProvider seeds the client from them:

app/layout.tsx
import { getRequestLocale, getVerbalyProps } from '@verbaly/next/server';
import { VerbalyProvider } from '@verbaly/next/client';
import { localeDirection } from 'verbaly';

// the language comes from the cookie and Accept-Language, so the shell renders per request
export const instant = false;

export default async function RootLayout({ children }) {
  const locale = await getRequestLocale();
  const props = await getVerbalyProps();
  return (
    <html lang={locale} dir={localeDirection(locale)}>
      <body>
        <VerbalyProvider {...props}>{children}</VerbalyProvider>
      </body>
    </html>
  );
}

export const instant = false is for cacheComponents, which create-next-app turns on: a layout that reads the request outside <Suspense> fails the build there, and a language chosen by cookie is exactly that. Without cacheComponents, leave the line out. To keep pages static instead, put the language in the address, below.

Server and Client Components

Server Components get a request-scoped t with await getT(), resolved once per request (the address first when it carries the language, then the cookie, then Accept-Language, then your fallback):

app/page.tsx
import { getT } from '@verbaly/next/server';

export default async function Page() {
  const t = await getT();
  return <h1>{t`Welcome back`}</h1>;
}

Rich text in a Server Component is the same <Trans> as in React, from @verbaly/next/server: it renders in the request's language with no provider.

app/page.tsx
import { Trans } from '@verbaly/next/server';

<Trans>Read the <a href="/terms">terms</a> before you go on</Trans>

Outside a page, where there is no request to read (an OG image, a sitemap, an email), name the language. That call never reads the request, so the route stays static:

app/og/route.ts
import { getT } from '@verbaly/next/server';

export async function GET() {
  const t = await getT({ locale: 'es' });
  return Response.json({ title: t('home.lead') });
}

With routing: 'no-prefix', a share card can mix two languages: a crawler reads the page in the language it negotiates, while an image that names its language is always in that one. To keep them together, give each language its own url with a prefix routing mode. Or let the image read the request like the page does, with getT() and no language, which renders it on every request.

Client Components use the React hooks, re-exported from @verbaly/next/client:

Counter.tsx
'use client';
import { useT } from '@verbaly/next/client';

export function Counter() {
  const t = useT();
  return <p>{t`You have new messages`}</p>;
}

Keys are typed: getT() and useT() check every key and its params against your catalog, and getRequestLocale() returns one of your languages. The types live in .verbaly/types.d.ts, next to the generated modules and never committed. TypeScript skips a dot folder, so Verbaly adds that file to the include of your tsconfig.json, the way Next adds .next/types. On a fresh clone, next typegen && tsc --noEmit writes them before it checks them.

The language in the address

If your pages live under app/[locale]/, say so in your config first: routing: 'prefix-all' gives every language its own segment. That line is what gives getAlternates the other languages and sends useSwitchLocale to the new address, and without it setRequestLocale warns once, since the segment and the config would contradict each other.

verbaly.config.ts
export default {
  locales: ['en', 'es', 'pt'],
  routing: 'prefix-all',
};

Then hand Verbaly the segment. On Next 16.3 and later there is nothing to write: with the segment in your root layout, Verbaly reads it by itself in every layout, page and 'use cache' function. Your page is built ahead of time, and the address decides the language for everyone who opens the link. On Next 15 up to 16.2, call setRequestLocale in every layout and every page of the tree, and pass the language to getT inside 'use cache': Next can render a page without running its layout, and a page that finds no language reads the cookie instead of the address.

app/[locale]/layout.tsx
import { setRequestLocale, getVerbalyProps, getAlternates } from '@verbaly/next/server';
import { locales } from 'verbaly/app';

export function generateStaticParams() {
  return locales.map((locale) => ({ locale }));
}

export async function generateMetadata({ params }) {
  const { locale } = await params;
  return { alternates: getAlternates({ path: `/${locale}`, baseUrl: 'https://example.com' }) };
}

export default async function LocaleLayout({ children, params }) {
  const { locale } = await params;
  setRequestLocale(locale);  // Next 15 to 16.2: in every layout and page
  return <VerbalyProvider {...(await getVerbalyProps())}>{children}</VerbalyProvider>;
}

getAlternates hands generateMetadata the address of this page in every language plus the canonical, which is what tells a search engine that your translations are the same page and not duplicates. It is the same set a statically rendered site gets.

Those addresses, and the one useSwitchLocale navigates to, follow trailingSlash in your next.config. Next never ends an address in a slash unless you ask it to, so the Spanish home is /es.

Switching languages

useSwitchLocale follows your routing. When the address carries the language, it moves to the same page in the new language through the app router. When it does not, it switches the client live, writes the cookie the server reads, and re-renders Server Components through router.refresh():

LangPicker.tsx
'use client';
import { useSwitchLocale } from '@verbaly/next/client';

export function LangPicker() {
  const switchLocale = useSwitchLocale();
  return <button onClick={() => switchLocale('es')}>Español</button>;
}
↑↓to moveEnterto open
Copied to clipboard