API React

tyndale-react fornisce il provider runtime, gli hook di traduzione, i componenti di formattazione e gli helper server usati dalle app Tyndale.

Provider e contesto

TyndaleProvider

Provider radice per app React plain. Carica i file di locale, espone lo stato di traduzione e alimenta tutti gli hook e i componenti.

import { TyndaleProvider } from 'tyndale-react';

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

Proprietà

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

Se initialTranslations viene omesso, il provider recupera {basePath}/{locale}.json e manifest.json nel browser.

TyndaleContext

Contesto React che contiene il locale corrente, il manifest, le traduzioni caricate, lo stato di caricamento e la funzione changeLocale().

Usalo direttamente solo quando hai bisogno di un accesso personalizzato al contesto. La maggior parte delle app dovrebbe preferire gli hook qui sotto.

useTyndaleContext()

Legge TyndaleContext e genera un errore se non è montato alcun provider.

import { useTyndaleContext } from 'tyndale-react';

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

Hook principali

useTranslation()

Restituisce una funzione di traduzione con supporto per l’interpolazione.

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()

Restituisce la stringa del locale corrente.

import { useLocale } from 'tyndale-react';

const locale = useLocale();

Fuori da un provider restituisce una stringa vuota e registra un avviso in sviluppo.

useChangeLocale()

Restituisce una funzione che cambia il locale attivo.

import { useChangeLocale } from 'tyndale-react';

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

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

In React plain, questo recupera il JSON del nuovo locale e aggiorna lo stato del provider. In tyndale-next, lo stesso hook attiva invece un cambio di route.

useDictionary(filenameKey)

Restituisce le voci di dizionario per un file di dizionario come oggetto plain.

import { useDictionary } from 'tyndale-react';

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

Firma:

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

L’hook cerca le voci del manifest con type: 'dictionary' e usa come fallback la chiave del dizionario quando manca una traduzione.

Helper server

getTranslation(options)

Helper server asincrono che carica da disco un file di locale e restituisce una funzione di traduzione.

Disponibile sia da tyndale-react sia dal subpath solo server:

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

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

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

Opzioni:

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

Se locale === defaultLocale, salta il caricamento del file e restituisce la stringa sorgente con l’interpolazione applicata.

Marcatori dei messaggi

msg(source)

Contrassegna una stringa letterale per l’estrazione fuori dal render del componente e restituisce un elemento React che viene risolto in fase di render.

import { msg } from 'tyndale-react';

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

msgString(source)

Contrassegna una stringa letterale per l’estrazione e restituisce una stringa plain invece di un elemento React.

import { msgString } from 'tyndale-react';

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

Usa msgString() in contesti non React come moduli TypeScript plain, frontmatter Astro o utility server.

Componenti di traduzione e formattazione

<T>

Traduce contenuti JSX serializzando i suoi children, cercando il formato wire tradotto e renderizzando il risultato tradotto.

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

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

Se non è disponibile alcuna traduzione, renderizza i children sorgente.

<Var>

Contrassegna un valore dinamico all’interno di <T>.

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

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

<Num>

Formatta un numero con Intl.NumberFormat. All’interno di <T>, agisce anche come placeholder nominato.

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

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

<Currency>

Formatta la valuta con il locale attivo.

import { Currency } from 'tyndale-react';

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

<DateTime>

Formatta una data o un timestamp con Intl.DateTimeFormat.

import { DateTime } from 'tyndale-react';

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

<Plural>

Seleziona il ramo plurale corretto per il locale attivo. All’interno di <T>, viene serializzato nella sintassi plurale ICU.

import { Plural } from 'tyndale-react';

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

Helper avanzati

Questi sono export pubblici, ma la maggior parte delle app non ne ha bisogno, a meno che tu non stia integrando con l’output di estrazione o con gli interni del wire-format.

computeHash(content) / hash(content)

Calcola l’hash SHA-256 normalizzato che Tyndale usa per la ricerca delle traduzioni.

import { computeHash } from 'tyndale-react';

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

escapeWireFormat(text) / unescapeWireFormat(text)

Esegue l’escape o ripristina il testo letterale per il wire format di Tyndale.

serializeChildren(children) / deserializeWireFormat(...)

Converte i children React nel wire format di Tyndale e viceversa.

parseIcuPlural(input)

Analizza un blocco plurale ICU nel suo nome variabile e nei suoi rami.

Usali solo quando stai costruendo tooling o integrazioni runtime avanzate attorno al formato di traduzione serializzato di Tyndale.