GT JSX-Datenformat
Referenz zum kompakten JSX-Datenformat von General Translation
Das GT JSX-Datenformat ist ein kompaktes Datenformat, das von den Bibliotheken von General Translation verwendet wird, um übersetzte UIs in Ihrer React-Anwendung darzustellen.
Einführung: JSX-Bäume
React repräsentiert JSX-Bäume als Objekte mit der folgenden Struktur:
type Element = {
type: string;
props: {
children: JSXTree[] | JSXTree;
// …weitere Props
};
// …weitere Attribute
};
type JSXTree = Element | string;GT JSX ist eine komprimierte Version dieser JSX-Baumstruktur, die von den General Translation Bibliotheken genutzt wird, um übersetzte UI in Ihrer React-Anwendung darzustellen.
Referenz
type Element = {
t?: string; // Tagname
c?: (Element | Variable | string)[]; // children
i?: number; // GT-ID des Elements
d?: {
b?: Record<string, Element | Variable | string>; // Zweige
t?: "p" | "b"; // Typ der Zweigtransformation (Plural oder Branch)
pl?: string; // Platzhalter
ti?: string; // Titel
alt?: string; // Alt-Text
arl?: string; // aria-label
arb?: string; // aria-labelledby
ard?: string; // aria-describedby
s?: Record<string, string>; // Stil
};
}
type Variable = {
k: string; // Schlüssel
v?: "v" | "n" | "c" | "d"; // Typ
i?: number; // GT-ID
}
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];GT JSX: Strings
Die einfachste Form von GT JSX ist ein String, der einen statischen Text darstellt.
Zum Beispiel:
<T>Hallo, Welt!</T>Würde in GT-JSX wie folgt dargestellt:
„Hallo, Welt!"String-Arrays sind ebenfalls gültiges GT-JSX:
[„Hallo, ", „Welt!"]GT JSX: Elemente
GT kann JSX-Element-Typen auf zwei Arten darstellen.
Variables
Zuerst handelt es sich um eine Variable – ein einfaches Objekt mit einem Schlüssel und einem optionalen Typ. Sie dient dazu, Variablen darzustellen, die sich zur Laufzeit ändern können.
type Variable = {
k: string; // `k` steht für Key, den Namen der Variable
v?: ( // steht für den Typ der Variable; wenn weggelassen, wird `v` angenommen
"v" | // `v`, eine generische Variable
"n" | // `n`, eine Zahlenvariable
"c" | // `c`, eine Währungsvariable
"d" // `d`, eine Datums-/Zeitvariable
);
i?: number; // GT-ID der Variable
}Beispiel 1: Var
<T>Hallo, <Var>{name}</Var>!</T>Würde in GT-JSX wie folgt dargestellt:
["Hallo ", { k: "_gt_var_1", i: 1 }, "!"]Variablen ohne name-Prop erhalten eindeutige interne Namen auf Grundlage ihrer GT-id
Beispiel 2: Num
<T>Die Anzahl beträgt <Num>{count}</Num></T>Wird in GT JSX wie folgt dargestellt:
["Die Anzahl beträgt ", { k: "count", v: "n", i: 1 }]Beispiel 3: Mit dem Name-Prop
<T>Dieses Produkt kostet <Currency name="cost">{amount}</Currency></T>Würde in GT-JSX wie folgt dargestellt:
["Dieses Produkt kostet ", { k: "cost", v: "c", i: 1 }]Elemente
Elemente, die keine Variablen sind, werden durch die folgende Datenstruktur dargestellt:
Beachten Sie, dass alle diese Attribute optional sind.
Ein leeres Objekt würde ein übersetztes Element an derselben Position wie sein ursprüngliches Pendant darstellen, ohne übersetzbaren Inhalt in seinen Nachfahren.
In der Praxis ist i immer enthalten.
type Element = {
t?: string; // Tagname
c?: GTJSXTree | GTJSXTree[]; // children
i?: number; // GT-ID des Elements
d?: { // data-_gt-Attribut
b?: Record<string, GTJSXTree | GTJSXTree[]>; // Zweige
t?: "p" | "b"; // Typ der Zweigtransformation (Plural oder Branch)
pl?: string; // Platzhalter
ti?: string; // Titel
alt?: string; // alt
arl?: string; // aria-label
arb?: string; // aria-labelledby
ard?: string; // aria-describedby
s?: Record<string, string>; // style
}
}Beispiel 1: Einfache Tags
<T>Hallo, <b>Welt</b>!</T>Würde in GT-JSX wie folgt dargestellt:
["Hallo, ", { c: "Welt", i: 1 }, "!"]Beispiel 2: Verschachtelt, mit Variablen
<T><b>Hallo</b>, ich heiße <i><Var>{name}</Var></i></T>Würde in GT-JSX wie folgt dargestellt:
[
{ t: "b", c: "Hallo", i: 1 },
", ich heiße ",
{
t: "i",
c: { k: "_gt_var_3", i: 3 },
i: 2
}
]Beispiel 3: Mit Pluralformen
<T>
<Plural
n={count}
one={<>Ich habe <Num>{count}</Num> Element</>}
other={<>Ich habe <Num>{count}</Num> Elemente</>}
/>
</T>Würde in GT-JSX wie folgt dargestellt:
{
i: 1,
d: {
t: "p",
b: {
one: {
c: ["Ich habe", { k: "_gt_num_4", v: "n", i: 3 }, "Eintrag"],
i: 2
},
other: {
c: ["Ich habe", { k: "_gt_num_4", v: "n", i: 3 }, "Einträge"],
i: 2 // Hinweis: dieselbe ID wird für parallele Zweige verwendet
}
}
}
}GTJSX-Typ
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];GT-IDs
GT-IDs werden in einem JSX-Baum in Tiefensuche und der Reihe nach vergeben, beginnend mit 1.
Wenn es verzweigende Komponenten wie <Branch> oder <Plural> gibt, erhalten parallele Zweige dieselben GT-IDs. So ist sichergestellt, dass auch dann Elemente mit den richtigen Props und der richtigen Logik erzeugt werden können, wenn es in einer Sprache mehr Zweige gibt als in einer anderen (z. B. Sprachen mit mehr Pluralformen).
GT JSX JSON-Dateien
Jeder JSX-Baum repräsentiert die children eines <T>-Components.
Komponenten werden gemeinsam in Übersetzungs-JSON-Dateien gespeichert.
Der Typ des in diesen Dateien gespeicherten JSON-Objekts entspricht:
type GTJSXFile = {
[key: string]: GTJSXTree;
}Wobei key entweder benutzerdefiniert ist oder dem Hash des ursprünglichen Sprach-GTJSXTree entspricht,
und GTJSXTree der oben beschriebene Typ des GT-JSX-Baums ist.
Vollständiges Beispiel
Das verfasste JSX:
<T>
<b>Alices</b> zufriedener <i>Kunde</i>
</T>Würde als folgender JSX-Baum dargestellt:
[
{
type: "b",
"props": {
"children": "Alices"
}
},
" glücklicher "
{
type: "i",
"props": {
"children": "Kunde"
}
}
]Dies würde in GT-JSX wie folgt minimiert:
[{ t: "b", c: "Alices", i: 1 }, " zufriedene ", { t: "i", c: "Kundin", i: 2 }]Auf Spanisch übersetzt sähe das GT-JSX so aus:
[{ c: "Der Kunde", i: 2 }, " zufrieden ", { c: "von Alice", i: 1 }]Es würde in einer Datei gespeichert, die so aussieht:
{ "abc123": [{ "c": "Der Kunde", "i": 2 }, " glücklich ", { "c": "von Alice", "i": 1 }] }abc123 ist der Hash des ursprünglichen englischen GT-JSX-Baums, nicht der spanischen Übersetzung.Wenn die spanische Übersetzung mit dem ursprünglichen JSX-Baum abgeglichen wird, ergibt sich Folgendes:
[
{
type: "i",
"props": {
"children": "Der Kunde"
}
},
" ist glücklich ",
{
type: "b",
"props": {
"children": "von Alice"
}
}
]Die dann wie vorgesehen in der UI dargestellt werden kann:
<><i>Der glückliche Kunde</i> <b>von Alice</b></>Hashes
Hashing-Algorithmus, Hash-Länge noch festzulegen
Hashes zur Laufzeit vermeiden
Um das Berechnen von Hashes zur Laufzeit zu vermeiden, bieten die Bibliotheken einen optionalen Standardwert-Mechanismus, bei dem der Nutzer eine id angeben kann.
<T id="example">
Hallo, Welt
</T>Wenn die id in der Übersetzungs-JSON-Datei vorhanden ist, wird sie anstelle des Hashes verwendet.
{ "example": "Hallo, Welt" }Wie ist dieser Leitfaden?