Ir para o conteúdo

Integrações

React

O pacote oficial de React 18/19 para Verbaly. Hooks sobre o mesmo core reativo, um <Trans> ciente do compilador para rich text, e chaves + params totalmente tipados.

O que você pode fazer:

Instalação

Adicione o runtime, este pacote e o plugin do Vite, e depois o compilador, que é onde vive o comando verbaly. O init escreve a sua config e o seu catálogo fonte.

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

Depois adicione verbaly() aos plugins do vite.config. Ele escreve verbaly/app, o módulo que os seus componentes leem.

Em webpack, Rollup, esbuild ou Rspack, instale @verbaly/unplugin no lugar de @verbaly/vite: outros bundlers mostra como.

Setup e 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>;
}

O idioma que um visitante escolhe

setLocale de useLocale() troca todos os componentes, e a página acompanha: <html lang>, <html dir> e a escolha, salva no navegador. Um app de página única inicia no idioma fonte, então recupere essa escolha antes do primeiro 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 />);
});

Onde um servidor renderiza a página, como no Next.js, troque de idioma com useSwitchLocale de @verbaly/next/client: ele também grava o cookie que o servidor lê.

Escreva o texto no lugar

O compilador lê os seus arquivos .tsx: escreva o texto fonte com t e ele é extraído, ganha chave e é tipado ao salvar. Sem chave para inventar nem catálogo para tocar.

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

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

Prefere chaves legíveis? t.id('inbox.title') antes do template extrai sob o seu id em vez de um hash do conteúdo.

Prefere deixar o texto no seu catálogo? Escreva só a chave dele: ela é verificada e tipada do mesmo jeito. Veja Chaves e catálogos.

Rich text com <Trans>

Escreva o texto fonte no lugar e o compilador o extrai, exatamente como 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

Os Server Components renderizam já traduzidos no idioma do visitante, e os Client Components iniciam com o mesmo idioma e o mesmo catálogo: sem flash de texto sem tradução nem diferenças entre servidor e navegador.

Next.js precisa da integração (@verbaly/next) junto com o pacote de React e o compilador:

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

Conecte tudo

Envolva o seu config com withVerbaly. Ele liga a extração ao vivo no dev e o compilador de mensagens no Turbopack e no webpack. Quando o next build termina de compilar, lista o que faria o verbaly check falhar, então um comando que só carrega o seu config, como next typegen, nunca encontra esse relatório:

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

No layout raiz, getVerbalyProps serializa o idioma negociado e seu catálogo, e VerbalyProvider semeia o cliente a partir deles:

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 é para o cacheComponents, que o create-next-app liga: um layout que lê a requisição fora de <Suspense> faz o build falhar ali, e um idioma escolhido por cookie é exatamente isso. Sem cacheComponents, tire a linha. Para manter as páginas estáticas, coloque o idioma no endereço, mais abaixo.

Server e Client Components

Os Server Components recebem um t com escopo de requisição usando await getT(), resolvido uma vez por requisição (primeiro o endereço quando ele leva o idioma, depois o cookie, depois Accept-Language, depois seu 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>;
}

Texto rico num Server Component é o mesmo <Trans> do React, a partir de @verbaly/next/server: renderiza no idioma da requisição sem provider.

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

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

Fora de uma página, onde não há requisição para ler (uma imagem OG, um sitemap, um email), nomeie o idioma. Essa chamada nunca lê a requisição, então a rota continua estática:

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') });
}

Com routing: 'no-prefix', um cartão de compartilhamento pode misturar dois idiomas: um rastreador lê a página no idioma que negocia, enquanto uma imagem que nomeia o idioma sai sempre nele. Para mantê-los juntos, dê a cada idioma sua própria url com um modo de rotas com prefixo. Ou deixe a imagem ler a requisição como a página faz, com getT() sem idioma, que a gera a cada requisição.

Os Client Components usam os hooks de React, re-exportados de @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>;
}

As chaves são tipadas: getT() e useT() conferem cada chave e seus params contra o seu catálogo, e getRequestLocale() devolve um dos seus idiomas. Os tipos ficam em .verbaly/types.d.ts, junto dos módulos gerados e nunca commitados. O TypeScript pula uma pasta que começa com ponto, então o Verbaly adiciona esse arquivo ao include do seu tsconfig.json, como o Next adiciona .next/types. Num clone novo, next typegen && tsc --noEmit os escreve antes de conferi-los.

O idioma no endereço

Se as suas páginas vivem em app/[locale]/, diga isso primeiro na sua config: routing: 'prefix-all' dá a cada idioma o seu próprio segmento. É essa linha que dá ao getAlternates os outros idiomas e leva o useSwitchLocale ao novo endereço, e sem ela o setRequestLocale avisa uma vez, já que o segmento e a config se contradiriam.

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

Depois, entregue o segmento ao Verbaly. A partir do Next 16.3 não há nada para escrever: com o segmento no seu layout raiz, o Verbaly o lê sozinho em cada layout, página e função 'use cache'. Sua página é gerada com antecedência, e o endereço decide o idioma para todos que abrem o link. Do Next 15 ao 16.2, chame setRequestLocale em cada layout e em cada página da árvore, e passe o idioma para getT dentro de 'use cache': o Next pode renderizar uma página sem passar pelo layout dela, e uma página que não encontra o idioma lê o cookie em vez do endereço.

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 entrega ao generateMetadata o endereço desta página em todos os idiomas mais o canonical, que é o que diz a um buscador que suas traduções são a mesma página e não duplicatas. É o mesmo conjunto que um site renderizado estaticamente recebe.

Esses endereços, e o que o useSwitchLocale abre, seguem o trailingSlash do seu next.config. O Next nunca termina um endereço em barra a menos que você peça, então a página inicial em espanhol é /es.

Trocar de idioma

useSwitchLocale segue o seu routing. Quando o endereço leva o idioma, ele vai para a mesma página no novo idioma pelo router do app. Quando não, troca o cliente ao vivo, escreve o cookie que o servidor lê, e re-renderiza os Server Components via 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>;
}
↑↓para navegarEnterpara abrir
Copiado para a área de transferência