Panoramica

Questo rilascio aggiunge il supporto ai valori di contesto derivati in gt-react. Quando traduci contenuti, non c'è sempre una mappatura uno a uno tra il testo sorgente e le relative traduzioni: una singola frase in inglese può richiedere più traduzioni in un'altra lingua. La derivazione del contesto risolve questo problema consentendoti di generare più voci di traduzione a partire da una singola stringa sorgente.

Panoramica: come funzionano le traduzioni di GT

Nel sistema di traduzione di GT, racchiudi le stringhe traducibili in gt():

import { useGT } from 'gt-react';

function Greeting() {
  const gt = useGT();
  return <p>{gt("Hello, world!")}</p>;
}

Ogni chiamata a gt() crea una voce sorgente — una porzione di testo da tradurre. Normalmente, una voce sorgente produce una traduzione per ogni lingua.

Che cos'è derive?

La funzione derive() dice alla CLI di GT di registrare più voci di traduzione a partire da una singola chiamata gt(), in base a diversi valori di runtime. Invece di scrivere chiamate gt() separate per ogni variante, usi derive() per esprimerle tutte in un solo punto, e la CLI genera le voci sorgente appropriate nella fase di build.

Ad esempio, l'inglese non distingue il genere in "The boy/girl is playing,", mentre lo spagnolo sì ("El niño está jugando" vs "La niña está jugando"). Con derive(), puoi gestire questo caso in un'unica chiamata gt():

const subject = isBoy ? "boy" : "girl";
gt(`The ${derive(subject)} is playing.`);

La CLI rileva la chiamata derive() e registra due voci sorgente — una per "The boy is playing." e una per "The girl is playing." — ciascuna con una propria traduzione con la corretta concordanza in spagnolo.

Il problema: mappature uno-a-molti

Considera tre casi di come le voci sorgente si mappano alle voci di traduzione:

Caso 1: mappatura uno a uno

Ogni voce sorgente corrisponde esattamente a una sola voce di traduzione. Questo è il caso più semplice.

Caso 2: Mappatura molti-a-uno

Più voci sorgente confluiscono in un'unica traduzione. Ad esempio, l'inglese ha forme plurali, mentre il mandarino no:

Caso 3: mappatura uno-a-molti

Una singola voce sorgente richiede più traduzioni. Ad esempio, in spagnolo gli aggettivi concordano nel genere, a differenza dell'inglese:

Questo era il caso non supportato prima di questo rilascio. In precedenza, GT presumeva una mappatura uno-a-uno tra voci sorgente e traduzioni.

Soluzione: derive con $context

L'opzione $context di GT consente di distinguere tra voci di traduzione con lo stesso testo sorgente. In combinazione con derive(), puoi specificarlo direttamente nel punto di chiamata:

import { useGT, derive } from 'gt-react';

function StatusMessage({ isMasculine }) {
  const gt = useGT();

  return (
    <p>
      {gt("I am tired", {
        $context: derive(
          isMasculine ? "inflect as masculine" : "inflect as feminine"
        )
      })}
    </p>
  );
}

Nella fase di build, la CLI rileva la chiamata derive() e registra due voci sorgente distinte, ciascuna con la propria traduzione:

"I am tired" ($context: "inflect as masculine") → "Estoy cansado"
"I am tired" ($context: "inflect as feminine")  → "Estoy cansada"

In fase di runtime, viene selezionata la traduzione corretta in base al valore di isMasculine.

Senza derive(), dovresti scriverlo come due chiamate separate:

// Senza derive — più verboso, testo sorgente duplicato
const message = isMasculine
  ? gt("I am tired", { $context: "inflect as masculine" })
  : gt("I am tired", { $context: "inflect as feminine" });

derive() ottiene lo stesso risultato con meno ripetizioni e rende più chiaro lo scopo.

Perché non usare semplicemente un condizionale?

Come le stringhe di contenuto, i valori di $context devono essere statici: la CLI deve poterli determinare nella fase di build. Non puoi passare direttamente un'espressione di runtime come $context, perché la CLI non saprebbe quali valori potrebbe assumere. derive() risolve questo problema risalendo lo stack delle chiamate per determinare tutte le possibili stringhe statiche che potrebbero essere passate, consentendo alla CLI di registrare una voce sorgente per ciascuna di esse.

In sintesi

La derivazione del contesto risolve una lacuna fondamentale del modello di traduzione: l'impossibilità di rappresentare mappatura uno-a-molti tra il testo di origine e le voci di traduzione. Combinando derive() con $context, una singola chiamata a gt() può produrre più traduzioni, disambiguate a runtime.

Link correlati

• Riferimento API di derive() per le stringhe
• Riferimento API di derive() per i componenti
• derive() in Python
• Tutorial su derive() (Python)