API de React

tyndale-react proporciona el provider de runtime, hooks de traducción, componentes de formato y helpers de servidor que usan las apps de Tyndale.

Provider y contexto

TyndaleProvider

Provider raíz para apps de React puras. Carga archivos de locale, expone el estado de traducción y alimenta todos los hooks y componentes.

import { TyndaleProvider } from 'tyndale-react';

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

Props

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

Si se omite initialTranslations, el provider obtiene {basePath}/{locale}.json y manifest.json en el navegador.

TyndaleContext

Contexto de React que contiene el locale actual, manifest, traducciones cargadas, estado de carga y la función changeLocale().

Úsalo directamente solo cuando necesites acceso personalizado al contexto. La mayoría de apps debería preferir los hooks de abajo.

useTyndaleContext()

Lee TyndaleContext y lanza un error si no hay ningún provider montado.

import { useTyndaleContext } from 'tyndale-react';

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

Hooks principales

useTranslation()

Devuelve una función de traducción con soporte de interpolación.

import { useTranslation } from 'tyndale-react';

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

Firma:

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

useLocale()

Devuelve la cadena del locale actual.

import { useLocale } from 'tyndale-react';

const locale = useLocale();

Fuera de un provider devuelve una cadena vacía y registra una advertencia en desarrollo.

useChangeLocale()

Devuelve una función que cambia el locale activo.

import { useChangeLocale } from 'tyndale-react';

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

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

En React puro, esto obtiene el JSON del nuevo locale y actualiza el estado del provider. En tyndale-next, el mismo hook desencadena un cambio de ruta en su lugar.

useDictionary(filenameKey)

Devuelve entradas de diccionario para un archivo de diccionario como un objeto plano.

import { useDictionary } from 'tyndale-react';

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

Firma:

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

El hook busca entradas del manifest con type: 'dictionary' y usa como fallback la clave del diccionario cuando falta una traducción.

Helper de servidor

getTranslation(options)

Helper async de servidor que carga un archivo de locale desde disco y devuelve una función de traducción.

Disponible tanto desde tyndale-react como desde la subruta solo de 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' });

Opciones:

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

Si locale === defaultLocale, omite la carga del archivo y devuelve la cadena de origen con la interpolación aplicada.

Marcadores de mensaje

msg(source)

Marca una cadena literal para extracción fuera del render de componentes y devuelve un elemento de React que se resuelve en tiempo de render.

import { msg } from 'tyndale-react';

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

msgString(source)

Marca una cadena literal para extracción y devuelve una cadena plana en lugar de un elemento de React.

import { msgString } from 'tyndale-react';

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

Usa msgString() en contextos no React como módulos TypeScript puros, frontmatter de Astro o utilidades de servidor.

Componentes de traducción y formato

<T>

Traduce contenido JSX serializando sus hijos, buscando el formato wire traducido y renderizando el resultado traducido.

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

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

Si no hay traducción disponible, renderiza los hijos originales.

<Var>

Marca un valor dinámico dentro de <T>.

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

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

<Num>

Formatea un número con Intl.NumberFormat. Dentro de <T>, también actúa como un placeholder con nombre.

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

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

<Currency>

Formatea moneda con el locale activo.

import { Currency } from 'tyndale-react';

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

<DateTime>

Formatea una fecha o marca de tiempo con Intl.DateTimeFormat.

import { DateTime } from 'tyndale-react';

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

<Plural>

Selecciona la rama plural correcta para el locale activo. Dentro de <T>, se serializa a sintaxis plural ICU.

import { Plural } from 'tyndale-react';

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

Helpers avanzados

Estas son exportaciones públicas, pero la mayoría de apps no las necesita a menos que estés integrando con la salida de extracción o con internals del formato wire.

computeHash(content) / hash(content)

Calcula el hash SHA-256 normalizado que Tyndale usa para la búsqueda de traducciones.

import { computeHash } from 'tyndale-react';

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

escapeWireFormat(text) / unescapeWireFormat(text)

Escapa o restaura texto literal para el formato wire de Tyndale.

serializeChildren(children) / deserializeWireFormat(...)

Convierte hijos de React al formato wire de Tyndale y viceversa.

parseIcuPlural(input)

Parsea un bloque plural ICU en su nombre de variable y ramas.

Recurre a estas solo cuando estés construyendo tooling o integraciones avanzadas de runtime alrededor del formato de traducción serializado de Tyndale.