Format de données JSX de GT
Référence du format de données JSX minifié de General Translation
Le format de données JSX de GT est un format de données minifié utilisé par les bibliothèques de General Translation pour représenter l’interface utilisateur traduite dans votre application React.
Introduction : arbres JSX
React représente les arbres JSX sous forme d’objets avec la structure suivante :
type Element = {
type: string;
props: {
children: JSXTree[] | JSXTree;
// ...autres props
};
// ...autres attributs
};
type JSXTree = Element | string;GT JSX est une version compressée de cette structure d’arbre JSX, utilisée par les bibliothèques General Translation pour représenter l’interface traduite dans votre application React.
Références
type Element = {
t?: string; // nom de la balise
c?: (Element | Variable | string)[]; // enfants
i?: number; // ID GT de l’élément
d?: {
b?: Record<string, Element | Variable | string>; // branches
t?: "p" | "b"; // type de transformation de branche (pluriel ou branche)
pl?: string; // espace réservé
ti?: string; // titre
alt?: string; // texte alternatif
arl?: string; // aria-label
arb?: string; // aria-labelledby
ard?: string; // aria-describedby
s?: Record<string, string>; // style
};
}
type Variable = {
k: string; // clé
v?: "v" | "n" | "c" | "d"; // type
i?: number; // ID GT
}
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];GT JSX : chaînes
La forme la plus simple de GT JSX est une chaîne, c’est-à-dire un texte statique.
Par exemple :
<T>Bonjour, le monde !</T>Sera représenté en JSX GT comme :
"Bonjour, monde !"Les tableaux de chaînes sont également valides en JSX avec GT :
["Bonjour, ", "monde !"]GT JSX : éléments
GT représente les types d’Element JSX de deux façons.
Variables
La première est une variable, un simple objet qui contient une clé et éventuellement un type. Elle sert à représenter des variables susceptibles d’évoluer au moment de l’exécution.
type Variable = {
k: string; // `k` représente la clé, le nom de la variable
v?: ( // indique le type de la variable ; s’il est omis, `v` est supposé
"v" | // `v`, variable générique
"n" | // `n`, variable numérique
"c" | // `c`, variable monétaire
"d" // `d`, variable de date/heure
);
i?: number; // id GT de la variable
}Exemple 1 : Var
<T>Bonjour, <Var>{name}</Var> !</T>Sera représenté en JSX de GT comme :
["Bonjour\u00a0", { k: "_gt_var_1", i: 1 }, " !"]Les variables sans prop name reçoivent des noms internes uniques générés à partir de leur id GT
Exemple 2 : Num
<T>Le décompte est de <Num>{count}</Num></T>Serait représenté en JSX de GT comme :
["Le compteur est à ", { k: "count", v: "n", i: 1 }]Exemple 3 : avec la prop name
<T>Ce produit coûte <Currency name="cost">{amount}</Currency></T>Sera représenté en JSX GT comme :
["Ce produit coûte ", { k: "cost", v: "c", i: 1 }]Éléments
Les éléments qui ne sont pas des variables sont représentés à l’aide de la structure de données suivante :
Notez que tous ces attributs sont facultatifs.
Un objet vide représenterait un élément traduit à la même position que son équivalent d’origine, sans contenu traduisible parmi ses descendants.
En pratique, i est toujours présent.
type Element = {
t?: string; // nom de la balise
c?: GTJSXTree | GTJSXTree[]; // children
i?: number; // ID GT de l’élément
d?: { // prop data-_gt
b?: Record<string, GTJSXTree | GTJSXTree[]>; // branches
t?: "p" | "b"; // type de transformation de branche (pluriel ou branche)
pl?: string; // espace réservé
ti?: string; // titre
alt?: string; // alt
arl?: string; // aria-label
arb?: string; // aria-labelledby
ard?: string; // aria-describedby
s?: Record<string, string>; // style
}
}Exemple 1 : balises simples
<T>Bonjour, <b>le monde</b> !</T>Serait représenté en JSX de GT comme :
["Bonjour, ", { c: "monde", i: 1 }, "!"]Exemple 2 : Imbrication, avec variables
<T><b>Bonjour</b>, je m’appelle <i><Var>{name}</Var></i></T>Serait représenté en JSX de GT comme :
[
{ t: "b", c: "Bonjour", i: 1 },
", je m’appelle ",
{
t: "i",
c: { k: "_gt_var_3", i: 3 },
i: 2
}
]Exemple 3 : avec pluriels
<T>
<Plural
n={count}
one={<>J’ai <Num>{count}</Num> article</>}
other={<>J’ai <Num>{count}</Num> articles</>}
/>
</T>Serait représenté en JSX de GT ainsi :
{
i: 1,
d: {
t: "p",
b: {
one: {
c: ["J’ai ", { k: "_gt_num_4", v: "n", i: 3 }, " élément"],
i: 2
},
other: {
c: ["J’ai ", { k: "_gt_num_4", v: "n", i: 3 }, " éléments"],
i: 2 // note the same ID is used for parallel branches
}
}
}
}Type GTJSX
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];ID GT
Les ID GT sont attribués aux éléments et aux variables d’un arbre JSX en parcours en profondeur d’abord, de façon séquentielle, en commençant à 1.
Lorsqu’il y a des composants de branchement comme <Branch> ou <Plural>, les mêmes ID GT sont attribués aux branches parallèles. Ainsi, même si une langue comporte plus de branches qu’une autre (par exemple, des langues avec davantage de formes plurielles), il est toujours possible de créer des éléments avec les bons props et la logique adéquate.
Fichiers JSON JSX GT
Chaque arbre JSX représente le contenu children d’un composant <T>.
Les composants sont regroupés dans des fichiers JSON de traduction.
Le type de l’objet JSON stocké dans ces fichiers correspond à :
type GTJSXFile = {
[key: string]: GTJSXTree;
}Où key est soit défini par l’utilisateur, soit le hachage de la langue source du GTJSXTree,
et GTJSXTree est le type de l’arbre JSX de GT décrit ci-dessus.
Exemple complet
Le JSX écrit :
<T>
<b>Le</b> <i>client</i> heureux d’Alice
</T>Serait représenté par l’arbre JSX suivant :
[
{
type: "b",
"props": {
"children": "d’Alice"
}
},
" heureux ",
{
type: "i",
"props": {
"children": "client"
}
}
]Ceci serait minifié en JSX GT comme :
[{ t: "b", c: "d’Alice", i: 1 }, " client ", { t: "i", c: "satisfait", i: 2 }]Une fois traduit en espagnol, le JSX de GT serait :
[{ c: "Le client", i: 2 }, " satisfait ", { c: "d’Alice", i: 1 }]Il serait stocké dans un fichier qui ressemble à :
{ "abc123": [{ "c": "Le client", "i": 2 }, " heureux ", { "c": "d’Alice", "i": 1 }] }abc123 est l’empreinte (hash) de l’arbre JSX GT original en anglais, pas de la traduction espagnole.Lorsque la traduction espagnole est réconciliée avec l’arbre JSX original, le résultat suivant est produit :
[
{
type: "i",
"props": {
"children": "Le client"
}
},
" heureux ",
{
type: "b",
"props": {
"children": "d’Alice"
}
}
]Qui peut ensuite être affiché comme l’interface utilisateur prévue :
<><i>Le client</i> heureux <b>d’Alice</b></>Hachages
Algorithme de hachage, longueur de hachage à définir
Éviter les hachages à l’exécution
Pour éviter de calculer des hachages à l’exécution, les bibliothèques proposent un mécanisme de secours optionnel permettant à l’utilisateur de spécifier un id.
<T id="example">
Bonjour, le monde
</T>Si l’id est présent dans le fichier JSON de traduction, il sera utilisé à la place du hash.
{ "example": "Bonjour, monde" }Que pensez-vous de ce guide ?