Formato de datos JSX de GT
Referencia del formato de datos JSX minimizado de General Translation
El formato de datos JSX de GT es un formato de datos minimizado que utilizan las bibliotecas de General Translation para representar la IU traducida en tu aplicación de React.
Introducción: árboles JSX
React representa los árboles JSX como objetos con la siguiente estructura:
type Element = {
type: string;
props: {
children: JSXTree[] | JSXTree;
// ...otras props
};
// ...otros atributos
};
type JSXTree = Element | string;GT JSX es una versión compacta de esta estructura de árbol JSX que las bibliotecas de General Translation utilizan para representar la UI traducida en tu aplicación de React.
Referencias
type Element = {
t?: string; // nombre de la etiqueta
c?: (Element | Variable | string)[]; // children
i?: number; // ID de GT del elemento
d?: {
b?: Record<string, Element | Variable | string>; // ramas
t?: "p" | "b"; // tipo de transformación de ramas (plural o ramificación)
pl?: string; // marcador de posición
ti?: string; // título
alt?: string; // alt
arl?: string; // aria-label
arb?: string; // aria-labelledby
ard?: string; // aria-describedby
s?: Record<string, string>; // estilos
};
}
type Variable = {
k: string; // clave
v?: "v" | "n" | "c" | "d"; // tipo
i?: number; // ID de GT
}
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];GT JSX: Cadenas
La forma más sencilla de GT JSX es una cadena, que representa un texto estático.
Por ejemplo:
<T>¡Hola, mundo!</T>Se representaría en JSX de GT como:
"¡Hola, mundo!"Los arrays de cadenas también son JSX de GT válidos:
["Hola, ", "mundo!"]GT JSX: Elementos
GT representa los tipos de Element en JSX de dos maneras posibles.
Variables
La primera es una variable, un objeto simple que contiene una clave y un tipo opcional. Se utiliza para representar variables que pueden cambiar en tiempo de ejecución.
type Variable = {
k: string; // `k` representa la clave, el nombre de la variable
v?: ( // representa el tipo de la variable; si se omite, se asume como `v`
"v" | // `v`, una variable genérica
"n" | // `n`, una variable numérica
"c" | // `c`, una variable monetaria
"d" // `d`, una variable de fecha y hora
);
i?: number; // id de GT de la variable
}Ejemplo 1: Var
<T>¡Hola, <Var>{name}</Var>!</T>Se representaría en JSX de GT como:
["Hola, ", { k: "_gt_var_1", i: 1 }, "¡"]Las variables que no tienen la prop name reciben nombres internos únicos basados en su ID de GT
Ejemplo 2: Num
<T>El contador es <Num>{count}</Num></T>Se representaría en JSX de GT como:
["El conteo es ", { k: "count", v: "n", i: 1 }]Ejemplo 3: con la prop name
<T>Este producto cuesta <Currency name="cost">{amount}</Currency></T>Se representaría en JSX de GT como:
["Este producto cuesta ", { k: "cost", v: "c", i: 1 }]Elementos
Los elementos que no son variables se representan con la siguiente estructura de datos:
Ten en cuenta que todos estos atributos son opcionales.
Un objeto vacío representaría un elemento traducido en la misma posición que su equivalente original, sin contenido traducible entre sus descendientes.
En la práctica, i siempre se incluye.
type Element = {
t?: string; // nombre de la etiqueta
c?: GTJSXTree | GTJSXTree[]; // children
i?: number; // ID de GT del elemento
d?: { // prop data-_gt
b?: Record<string, GTJSXTree | GTJSXTree[]>; // ramas
t?: "p" | "b"; // tipo de transformación de rama (plural o branch)
pl?: string; // marcador de posición
ti?: string; // título
alt?: string; // alt
arl?: string; // aria-label
arb?: string; // aria-labelledby
ard?: string; // aria-describedby
s?: Record<string, string>; // estilo
}
}Ejemplo 1: Etiquetas simples
<T>¡Hola, <b>mundo</b>!</T>Se representaría en JSX de GT como:
["Hola, ", { c: "mundo", i: 1 }, "!"]Ejemplo 2: Anidado con variables
<T><b>Hola</b>, me llamo <i><Var>{name}</Var></i></T>Se representaría en JSX de GT como:
[
{ t: "b", c: "Hola", i: 1 },
", mi nombre es ",
{
t: "i",
c: { k: "_gt_var_3", i: 3 },
i: 2
}
]Ejemplo 3: Con plurales
<T>
<Plural
n={count}
one={<>Tengo <Num>{count}</Num> artículo</>}
other={<>Tengo <Num>{count}</Num> artículos</>}
/>
</T>Se representaría en JSX de GT como:
{
i: 1,
d: {
t: "p",
b: {
one: {
c: ["Tengo", { k: "_gt_num_4", v: "n", i: 3 }, "artículo"],
i: 2
},
other: {
c: ["Tengo", { k: "_gt_num_4", v: "n", i: 3 }, "artículos"],
i: 2 // nota: se usa el mismo id para ramas paralelas
}
}
}
}Tipo de GTJSX
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];IDs de GT
Las IDs de GT se asignan a elementos y variables en un árbol JSX en orden de recorrido en profundidad y de forma secuencial, empezando por 1.
Cuando hay componentes de ramificación como <Branch> o <Plural>, se asignan las mismas IDs de GT a las ramas paralelas. Esto garantiza que, si en un idioma hay más ramas que en otro (p. ej., idiomas con más formas de plural), igualmente se puedan crear elementos con las props y la lógica correctas.
Archivos JSON de JSX de GT
Cada árbol de JSX representa el contenido (children) de un componente <T>.
Los componentes se almacenan juntos en archivos JSON de traducción.
El tipo del objeto JSON almacenado en estos archivos corresponde a:
type GTJSXFile = {
[key: string]: GTJSXTree;
}Donde key es definido por el usuario o el hash del GTJSXTree en el idioma original,
y GTJSXTree es el tipo del árbol JSX de GT descrito anteriormente.
Ejemplo completo
El JSX escrito:
<T>
<b>Cliente</b> <i>feliz</i> de Alice
</T>Se representaría como el siguiente árbol de JSX:
[
{
type: "b",
"props": {
"children": "de Alice"
}
},
" feliz "
{
type: "i",
"props": {
"children": "cliente"
}
}
]Esto se minificaría en GT JSX como:
[{ t: "b", c: "de Alice", i: 1 }, " contenta ", { t: "i", c: "clienta", i: 2 }]Al traducirse al español, el JSX de GT sería:
[{ c: "El cliente", i: 2 }, " feliz ", { c: "de Alice", i: 1 }]Se almacenaría en un archivo con el siguiente aspecto:
{ "abc123": [{ "c": "El cliente", "i": 2 }, " feliz ", { "c": "de Alice", "i": 1 }] }abc123 es el hash del árbol JSX de GT original en inglés, no de la traducción al español.Cuando la traducción al español se reconcilia con el árbol JSX original, se generará lo siguiente:
[
{
type: "i",
"props": {
"children": "El cliente"
}
},
" feliz ",
{
type: "b",
"props": {
"children": "de Alice"
}
}
]Que luego puede mostrarse como la interfaz de usuario prevista:
<><i>El cliente</i> feliz <b>de Alice</b></>Hashes
Algoritmo de hash, longitud del hash por determinar
Evitar hashes en tiempo de ejecución
Para evitar calcular hashes en tiempo de ejecución, las bibliotecas ofrecen un mecanismo opcional de contenido de respaldo predeterminado mediante el cual el usuario puede especificar un id.
<T id="example">
Hola, mundo
</T>Si el id está presente en el archivo JSON de traducción, se utilizará en lugar del hash.
{ "example": "Hola, mundo" }¿Qué te ha parecido esta guía?