# gt-react: General Translation React SDK: GT JSX 数据格式
URL: https://generaltranslation.com/zh/docs/react/reference/gt-jsx.mdx
---
title: GT JSX 数据格式
description: General Translation JSX 压缩数据格式参考
---

{/* 自动生成：请勿直接编辑。请改为编辑 content/docs-templates/ 中的模板。 */}

GT JSX 数据格式是一种经过压缩的数据格式，供 General Translation 库用于在 React 应用中表示已翻译的 UI。


## 简介：JSX 树

React 将 JSX 树表示为如下结构的对象：

```ts
type Element = {
    type: string;
    props: {
        children: JSXTree[] | JSXTree;
        // ...其他 props
    };
    // ...其他属性
};
type JSXTree = Element | string;
```

GT JSX 是这种 JSX 树结构的压缩版本，General Translation 库用它来表示 React 应用中已翻译的 UI。


## 参考

```ts
type Element = {
    t?: string; // 标签名
    c?: (Element | Variable | string)[]; // 子元素
    i?: number; // GT ID of the element
    d?: {
        b?: Record<string, Element | Variable | string>; // branches
        t?: "p" | "b"; // 分支转换类型 (plural or branch)
        pl?: string; // placeholder
        ti?: string; // title
        alt?: string; // alt
        arl?: string; // aria-label
        arb?: string; // aria-labelledby
        ard?: string; // aria-describedby
        s?: Record<string, string>; // style
    };
}
type Variable = {
    k: string; // key
    v?: "v" | "n" | "c" | "d" | "rt"; // 类型
    i?: number; // GT ID
}
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];
```


## GT JSX：字符串

GT JSX 最简单的形式是字符串，表示一段静态文本。

例如：

```jsx
<T>Hello, world!</T>
```

在 GT JSX 中可表示为：

```ts
"Hello, world!"
```

字符串数组也可以作为有效的 GT JSX：

```ts
["Hello, ", "world!"]
```


## GT JSX: 元素

GT 可通过两种方式表示 JSX `Element` 类型。

### 变量

第一种是变量，即一个包含键和可选类型的简单对象，用于表示可在 runtime 时发生变化的变量。

```ts
type Variable = {
    k: string; // `k` represents key, the name of the variable
    v?: ( // represents the type of the variable, if left out is assumed as `v`
        "v" | // `v`, a generic variable
        "n" | // `n`, a number variable
        "c" | // `c`, a currency variable
        "d" | // `d`，日期时间变量
        "rt" // `rt`，相对时间变量
    );
    i?: number; // GT ID of the variable
}
```


#### 示例 1：Var

```jsx
<T>Hello, <Var>{name}</Var>!</T>
```

在 GT JSX 中可表示为：

```ts
["Hello, ", { k: "_gt_var_1", i: 1 }, "!"]
```

<Callout type="info">
  未提供 `name` prop 的变量会根据其 GT ID 自动分配唯一的内部名称
</Callout>


#### 示例 2：Num

```jsx
<T>The count is <Num>{count}</Num></T>
```

在 GT JSX 中表示为：

```ts
["The count is ", { k: "count", v: "n", i: 1 }]
```


#### 示例 3：使用 name 属性

```jsx
<T>This product costs <Currency name="cost">{amount}</Currency></T>
```

在 GT JSX 中可表示为：

```ts
["This product costs ", { k: "cost", v: "c", i: 1 }]
```


### 元素

非变量元素使用以下数据结构来表示：

<Callout type="info">
  请注意，这些属性都是可选的。
  空对象表示：该元素在与原始对应元素相同的位置上已被翻译，且其后代中没有可翻译内容。
  **但在实际中，`i` 始终会包含在内。**
</Callout>

```ts
type Element = {
    t?: string; // 标签名
    c?: GTJSXTree | GTJSXTree[]; // 子节点
    i?: number; // 元素的 GT ID
    d?: { // data-_gt 属性
        b?: Record<string, GTJSXTree | GTJSXTree[]>; // 分支
        t?: "p" | "b"; // 分支转换类型（plural 或 branch）
        pl?: string; // 占位符
        ti?: string; // 标题
        alt?: string; // alt
        arl?: string; // aria-label
        arb?: string; // aria-labelledby
        ard?: string; // aria-describedby
        s?: Record<string, string>; // 样式
    }
}
```


#### 示例 1：简单标签

```jsx
<T>Hello, <b>world</b>!</T>
```

在 GT JSX 中可表示为：

```ts
["Hello, ", { c: "world", i: 1 }, "!"]
```


#### 示例 2：嵌套并带有变量

```jsx
<T><b>Hello</b>, my name is <i><Var>{name}</Var></i></T>
```

在 GT JSX 中可表示为：

```ts
[
    { t: "b", c: "Hello", i: 1 },
    ", my name is ",
    { 
        t: "i",
        c: { k: "_gt_var_3", i: 3 }, 
        i: 2 
    }
]
```


#### 示例 3：使用复数形式

```jsx
<T>
    <Plural 
        n={count} 
        one={<>I have <Num>{count}</Num> item</>} 
        other={<>I have <Num>{count}</Num> items</>}
    />
</T>
```

在 GT JSX 中可表示为：

```ts
{ 
    i: 1,
    d: {
        t: "p",
        b: {
            one: {
                c: ["I have", { k: "_gt_num_4", v: "n", i: 3 }, "item"],
                i: 2 
            },
            other: {
                c: ["I have", { k: "_gt_num_4", v: "n", i: 3 }, "items"],
                i: 2 // 注意：并行分支使用相同的 ID
            }
        }
    }
}
```


### GTJSX 类型

```ts
type GTJSXTree = Element | Variable | string | (Element | Variable | string)[];
```


## GT ID

GT ID 会以深度优先、顺序递增的方式分配给 JSX 树中的元素和变量，从 1 开始。

当存在 `<Branch>` 或 `<Plural>` 这类分支组件时，并行分支会被分配相同的 GT ID。这样一来，即使某种语言中的分支比另一种语言更多 (例如某些语言有更多的复数形式) ，仍然可以创建具有正确 props 和逻辑的元素。

## GT JSX JSON 文件

每棵 JSX Tree 都表示一个 `<T>` 组件的子节点。
这些组件会统一存储在翻译 JSON 文件中。
这些文件中存储的 JSON 对象类型如下：

```ts
type GTJSXFile = {
    [key: string]: GTJSXTree;
}
```

其中，`key` 可以是用户自定义的，也可以是原始语言 `GTJSXTree` 的哈希值，
而 `GTJSXTree` 则是上文所述的 GT JSX 树类型。


### 完整示例

编写的 JSX：

```jsx
<T>
    <b>Alice's</b> happy <i>customer</i>
</T>
```

可表示为如下 JSX 树：

```ts
[
    {
        type: "b",
        "props": {
            "children": "Alice's"
        }
    },
    " happy ",
    {
        type: "i",
        "props": {
            "children": "customer"
        }
    }
]
```

这会被压缩成 GT JSX，如下所示：

```ts
[{ t: "b", c: "Alice's", i: 1 }, " happy ", { t: "i", c: "customer", i: 2 }]
```

翻译成西班牙语后，GT JSX 如下：

```ts
[{ c: "El cliente", i: 2 }, " feliz ", { c: "de Alice", i: 1 }]
```

它会存储在如下所示的文件中：

```json
{ "abc123": [{ "c": "El cliente", "i": 2 }, " feliz ", { "c": "de Alice", "i": 1 }] }
```

<Callout type="info">`abc123` 是原始英文 GT JSX 树的哈希值，而不是西班牙语翻译的哈希值。</Callout>

当西班牙语翻译与原始 JSX 树进行协调时，会生成以下内容：

```ts
[
    {
        type: "i",
        "props": {
            "children": "El cliente"
        }
    },
    " feliz ",
    {
        type: "b",
        "props": {
            "children": "de Alice"
        }
    }
]
```

随后即可显示为预期的 UI：

```jsx
<><i>El cliente</i> feliz <b>de Alice</b></>
```


### 哈希

哈希算法、哈希长度待定

### 避免在 runtime 时计算哈希

为避免在 runtime 时计算哈希，这些库提供了一个可选的回退机制，允许用户指定 ID。

```jsx
<T id="example">
    Hello, world
</T>
```

如果翻译 JSON 文件中包含该 ID，则会优先使用它，而不是哈希值。

```json
{ "example": "Hello, world" }
```