API React

tyndale-react fornece o provider de runtime, hooks de tradução, componentes de formatação e auxiliares de servidor usados pelos apps Tyndale.

Provedor e contexto

TyndaleProvider

Provider raiz para apps React puros. Ele carrega arquivos de locale, expõe o estado de tradução e alimenta todos os hooks e componentes.

import { TyndaleProvider } from 'tyndale-react';

export function App() {
  return (
    <TyndaleProvider defaultLocale="en" locale="fr">
      <Routes />
    </TyndaleProvider>
  );
}

Props

• defaultLocale: string
• locale?: string
• basePath?: string — o padrão é /_tyndale
• initialTranslations?: Record<string, string>
• initialManifest?: Manifest | null
• onLocaleChange?: (locale: string) => void
• children: React.ReactNode

Se initialTranslations for omitido, o provider busca {basePath}/{locale}.json e manifest.json no navegador.

TyndaleContext

Contexto React que carrega o locale atual, manifest, traduções carregadas, estado de carregamento e função changeLocale().

Use-o diretamente apenas quando você precisar de acesso personalizado ao contexto. A maioria dos apps deve preferir os hooks abaixo.

useTyndaleContext()

Lê TyndaleContext e lança erro se nenhum provider estiver montado.

import { useTyndaleContext } from 'tyndale-react';

function LocaleBadge() {
  const { locale, defaultLocale, isLoading } = useTyndaleContext();
  return <span>{isLoading ? 'Loading…' : `${locale} / ${defaultLocale}`}</span>;
}

Hooks principais

useTranslation()

Retorna uma função de tradução com suporte a interpolação.

import { useTranslation } from 'tyndale-react';

function Greeting({ name }: { name: string }) {
  const t = useTranslation();
  return <p>{t('Hello, {name}!', { name })}</p>;
}

Assinatura:

(source: string, vars?: Record<string, string | number>) => string

useLocale()

Retorna a string do locale atual.

import { useLocale } from 'tyndale-react';

const locale = useLocale();

Fora de um provider, ele retorna uma string vazia e registra um aviso em desenvolvimento.

useChangeLocale()

Retorna uma função que altera o locale ativo.

import { useChangeLocale } from 'tyndale-react';

function LocaleSwitcher() {
  const changeLocale = useChangeLocale();

  return <button onClick={() => changeLocale('es')}>Español</button>;
}

Em React puro, isso busca o JSON do novo locale e atualiza o estado do provider. Em tyndale-next, o mesmo hook aciona uma mudança de rota.

useDictionary(filenameKey)

Retorna entradas de dicionário para um arquivo de dicionário como um objeto simples.

import { useDictionary } from 'tyndale-react';

function Nav() {
  const labels = useDictionary('common');
  return <a href="/docs">{labels.docs}</a>;
}

Assinatura:

(filenameKey: string) => Record<string, string>

O hook procura entradas do manifest com type: 'dictionary' e recorre à chave do dicionário quando uma tradução está ausente.

Auxiliar de servidor

getTranslation(options)

Auxiliar assíncrono de servidor que carrega um arquivo de locale do disco e retorna uma função de tradução.

Disponível tanto em tyndale-react quanto no subpath somente para servidor:

import { getTranslation } from 'tyndale-react/server';

const t = await getTranslation({
  locale: 'fr',
  defaultLocale: 'en',
  outputPath: 'public/_tyndale',
});

const title = t('Welcome, {name}!', { name: 'Ada' });

Opções:

• locale: string
• defaultLocale?: string
• outputPath: string

Se locale === defaultLocale, ele ignora o carregamento de arquivo e retorna a string de origem com a interpolação aplicada.

Marcadores de mensagem

msg(source)

Marca uma string literal para extração fora da renderização de componente e retorna um elemento React que é resolvido em tempo de renderização.

import { msg } from 'tyndale-react';

const nav = [{ href: '/', label: msg('Home') }];

msgString(source)

Marca uma string literal para extração e retorna uma string simples em vez de um elemento React.

import { msgString } from 'tyndale-react';

export const copy = {
  docs: msgString('Documentation'),
};

Use msgString() em contextos não React, como módulos TypeScript puros, frontmatter Astro ou utilitários de servidor.

Componentes de tradução e formatação

<T>

Traduz conteúdo JSX serializando seus children, buscando o formato wire traduzido e renderizando o resultado traduzido.

import { T, Var } from 'tyndale-react';

<T>
  Hello, <Var name="name">{name}</Var>!
</T>

Se nenhuma tradução estiver disponível, ele renderiza os children de origem.

<Var>

Marca um valor dinâmico dentro de <T>.

import { T, Var } from 'tyndale-react';

<T>
  Hello, <Var name="name">{name}</Var>!
</T>

<Num>

Formata um número com Intl.NumberFormat. Dentro de <T>, ele também atua como um placeholder nomeado.

import { T, Num } from 'tyndale-react';

<T>
  You have <Num name="count" value={count} /> unread messages.
</T>

<Currency>

Formata moeda com o locale ativo.

import { Currency } from 'tyndale-react';

<Currency value={49.99} currency="USD" />

<DateTime>

Formata uma data ou timestamp com Intl.DateTimeFormat.

import { DateTime } from 'tyndale-react';

<DateTime value={new Date()} options={{ dateStyle: 'long' }} />

<Plural>

Seleciona a ramificação plural correta para o locale ativo. Dentro de <T>, ele é serializado para a sintaxe plural ICU.

import { Plural } from 'tyndale-react';

<Plural count={count} one="1 item" other="{count} items" />

Auxiliares avançados

Estas são exportações públicas, mas a maioria dos apps não precisa delas, a menos que você esteja integrando com saída de extração ou com internals de wire-format.

computeHash(content) / hash(content)

Calcula o hash SHA-256 normalizado que o Tyndale usa para busca de tradução.

import { computeHash } from 'tyndale-react';

const id = computeHash('Welcome to our app.');

escapeWireFormat(text) / unescapeWireFormat(text)

Escapa ou restaura texto literal para o wire format do Tyndale.

serializeChildren(children) / deserializeWireFormat(...)

Converte children React para wire format do Tyndale e de volta.

parseIcuPlural(input)

Analisa um bloco plural ICU em seu nome de variável e ramificações.

Recorra a estes apenas quando estiver criando tooling ou integrações avançadas de runtime em torno do formato serializado de tradução do Tyndale.