Descripción general

Este lanzamiento añade compatibilidad con valores de contexto derivados en gt-react. Al traducir contenido, no siempre hay una correspondencia uno a uno entre el texto de origen y sus traducciones: una sola frase en inglés puede requerir varias traducciones en otro idioma. La derivación de contexto resuelve esto, ya que te permite generar varias entradas de traducción a partir de una sola cadena de origen.

Contexto: cómo funcionan las traducciones en GT

En el sistema de traducción de GT, las cadenas traducibles se envuelven con gt():

import { useGT } from 'gt-react';

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

Cada llamada a gt() crea una entrada de origen: un fragmento de texto que se traduce. Normalmente, cada entrada de origen genera una traducción por idioma.

¿Qué es derivación?

La función derive() le indica a la CLI de GT que registre múltiples entradas de traducción a partir de una sola llamada a gt(), en función de distintos valores de tiempo de ejecución. En lugar de escribir llamadas a gt() por separado para cada variante, usas derive() para expresar todas las variantes en un solo lugar, y la CLI genera las entradas de origen correspondientes en tiempo de construcción.

Por ejemplo, en inglés no se distingue el género en "The boy/girl is playing," pero en español sí ("El niño está jugando" frente a "La niña está jugando"). Con derive(), puedes resolver esto en una sola llamada a gt():

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

La CLI detecta la llamada a derive() y registra dos entradas de origen —una para "The boy is playing." y otra para "The girl is playing."—, cada una con su propia traducción y la concordancia correcta en español.

El problema: asignaciones de uno a varios

Considera tres casos de cómo las entradas de origen se asignan a las entradas de traducción:

Caso 1: Mapeo uno a uno

Cada entrada de origen se asigna a exactamente una entrada de traducción. Este es el caso más sencillo.

Caso 2: Mapeo de varios a uno

Varias entradas de origen se agrupan en una sola traducción. Por ejemplo, el inglés tiene formas plurales, pero el mandarín no:

Caso 3: Mapeo de uno a varios

Una sola entrada de origen requiere múltiples traducciones. Por ejemplo, el español tiene concordancia de género en los adjetivos, mientras que el inglés no:

Este era el caso que no se admitía antes de este lanzamiento. Anteriormente, GT asumía un mapeo de uno a uno entre las entradas de origen y las traducciones.

Solución: derivación con $context

La opción $context de GT te permite desambiguar entradas de traducción para un mismo texto de origen. Combinada con derive(), puedes expresarlo directamente en la llamada:

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

En tiempo de construcción, la CLI detecta la llamada a derive() y registra dos entradas de origen independientes, cada una con su propia traducción:

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

En tiempo de ejecución, se selecciona la traducción correcta en función del valor de isMasculine.

Sin derive(), tendrías que escribirlo como dos llamadas separadas:

// Sin derive — más verboso, texto fuente duplicado
const message = isMasculine
  ? gt("I am tired", { $context: "inflect as masculine" })
  : gt("I am tired", { $context: "inflect as feminine" });

derive() logra el mismo resultado con menos duplicación y aclara mejor la intención.

¿Por qué no usar simplemente un condicional?

Al igual que las cadenas de contenido, los valores de $context deben ser estáticos: la CLI necesita resolverlos en tiempo de construcción. No puedes pasar directamente una expresión de tiempo de ejecución como $context porque la CLI no sabría qué valores podría tomar. derive() resuelve esto rastreando la pila de llamadas para determinar todas las posibles cadenas estáticas que podrían pasarse, lo que permite a la CLI registrar una entrada de origen para cada una.

En resumen

La derivación del contexto aborda una limitación fundamental del modelo de traducción: la incapacidad de representar correspondencias de uno a varios entre las entradas de origen y las entradas de traducción. Al combinar derive() con $context, una sola llamada a gt() puede generar varias traducciones que se diferencian en tiempo de ejecución.

Enlaces relacionados

• derive() para cadenas: referencia de la API
• derive() para componentes: referencia de la API
• derive() en Python
• Tutorial de derive() (Python)