使用变量

概述

gt-next 中的变量组件允许你在翻译中插入动态内容。这些组件包括：

<Var>：用于渲染变量。
<Num>：用于格式化数字。
<Currency>：用于格式化货币数值。
<DateTime>：用于格式化日期和时间。

在本指南中，我们将介绍：

什么是变量组件？

如何使用变量组件

示例

常见陷阱

什么是变量组件？

变量组件用于包裹动态内容，如用户名、数值、日期和货币。

这些组件可以根据用户的本地化设置格式化并渲染动态值，无需任何外部翻译。

请将变量组件与 <T> 组件结合使用，以确保动态内容能够准确且一致地显示。

每种变量组件的行为各不相同：

<Var>：动态渲染任何内容，如用户名或标识符。
<Num>：根据本地化规则格式化数值。
<Currency>：使用符号和本地化规则格式化货币数值。
<DateTime>：使用本地化习惯格式化日期和时间。

虽然 JSX 内容和字符串通过 General Translation API 进行翻译，但变量组件完全在本地处理。

<Num>、<Currency> 和 <DateTime> 组件使用 JS i18n API 根据用户的本地化设置格式化内容。

被变量组件包裹的内容绝不会发送到 General Translation API，从而确保数据隐私和安全。

有关更多信息，请参见数据隐私部分。

如何使用变量组件

基本用法

所有变量组件的用法都是相同的。

const user = {
  name: 'John',
  age: 30,
  balance: 1000,
  birthday: new Date('1990-01-01'),
}
<div>
  <Var>{user.name}</Var>
  <Num>{user.age}</Num>
  <Currency>{user.balance}</Currency>
  <DateTime>{user.birthday}</DateTime>
</div>

只需将变量组件包裹在您想要显示的内容周围即可。

在 `<T>` 中使用变量组件

变量组件本身并不能做太多事情，因为它们需要了解用户的语言环境才能格式化内容。

因此，您应该将变量组件与 <T> 组件一起使用。

<T> 组件不仅会处理周围内容的翻译，还会将正确的语言环境传递给其子变量组件。

<T>
  The current time is <DateTime>{time}</DateTime>.
</T>

变量本地化

<Num>、<Currency> 和 <DateTime> 组件包含内置的本地化支持。这些组件会根据用户选择的语言环境，或根据作为属性传递的其他选项，自动格式化其内容。

例如：

<Num> 使用本地化的小数分隔符显示数字。
<Currency> 使用本地化的货币符号和位置显示值。
<DateTime> 根据特定语言环境的规则显示日期和时间。

您也可以通过直接向这些组件传递属性来覆盖默认的语言环境和格式化选项。

数据隐私

变量组件在本地处理所有格式化；因此，它们的子内容不会被发送到 General Translation API 进行翻译（当与 <T> 组件一起使用时）。这非常适合保持敏感数据（如用户名或账号）的私密性和安全性。

每个变量组件处理格式化的方式不同，应该用于特定类型的内容：

<Var>：任何不需要格式化的私有内容
- 用户名、账号等。
<Num>：应根据语言环境格式化的私有数值
- 订单数量、年龄、距离等。
<Currency>：应根据语言环境格式化的私有货币值
- 交易金额、账户余额等。
<DateTime>：应根据语言环境格式化的私有日期和时间值
- 账户创建日期、订单时间戳等。

分支组件和 <T> 组件会将数据发送到 General Translation API 进行翻译。

此外，在 <Var> 组件内嵌套 <T> 会将内容发送到 General Translation API 进行翻译。

<T>
  <Var>
    <T>Hello, world!</T>
    Goodbye, World!
  </Var>
</T>

在上面的示例中，"Hello, world!" 会被发送到 General Translation API 进行翻译，而 "Goodbye, World!" 不会。

示例

`<Var>`

由于 <Var> 组件本身不进行任何格式化，因此应始终与 <T> 组件一起使用。

import { T, Var } from 'gt-next';

export default function UserGreeting({ user }) {
  return (
    <T>
      Hello, <Var>{user.name}</Var>!
      Your address is <Var>{user.addr}</Var>
    </T>
  );
}

变量组件还能隔离数据，因此可以用来渲染不属于翻译内容的动态内容。

import { T, Var } from 'gt-next';

export default function Dashboard({ isAdmin }) {
  return (
    <T>
      Your Dashboard:
      <Var>{isAdmin ? <AdminDashboard /> : <UserDashboard />}</Var>
    </T>
  );
}

在上面的例子中，isAdmin 三元运算符让 Dashboard 组件变为动态。

如果没有 <Var> 组件，这将是 <T> 组件的无效用法。

当在 <T> 组件中使用动态内容时，请使用 <Var> 包裹所有动态内容！

`<Num>`

<Num> 组件可以作为 <T> 组件的子组件，也可以单独使用。

import { T, Num } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';

export default function OrderSummary() {
  const quantity = 10;
  return (
    <>
      <T>
        You have <Num>{quantity}</Num> items in your cart.
      </T>
      <Badge>
        <Num>{quantity}</Num> // This is the same as using quantity.toLocaleString()
      </Badge>
    </>
  );
}

`<Currency>`

<Currency> 组件可以作为 <T> 组件的子组件，也可以单独使用。

import { T, Currency } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';

export default function OrderSummary() {
  const total = 1000;
  return (
    <>
      <T>
        Your total is <Currency currency={"USD"}>{total}</Currency>.
      </T>
      <Badge>
        <Currency currency={"USD"}>{total}</Currency> // This will be formatted as $1,000
      </Badge>
    </>
  );
}

`<DateTime>`

<DateTime> 组件可以作为 <T> 组件的子组件，也可以单独使用。

import { T, DateTime } from 'gt-next';

export default function OrderSummary() {
  const date = new Date();
  return (
    <T>
      Your order was placed on <DateTime>{date}</DateTime>.
    </T>
    <DateTime>{date}</DateTime> // This is the same as using date.toLocaleDateString() or date.toLocaleTimeString()
  );
}

常见陷阱

忽略本地化选项

对于 <Currency>，请确保传递 currency 属性以指定货币类型。这样可以确保在显示数值时使用正确的货币符号和格式。

其他组件，如 <Num> 和 <DateTime>，也有可选属性，可以让你自定义格式化方式。

注意事项

变量组件会隔离数据，因此可以用于渲染不属于翻译内容的动态内容。
变量组件不会将数据发送到通用翻译 API，因此非常适合保护敏感数据的隐私和安全。
变量组件既可以作为 <T> 组件的子组件使用，也可以作为独立组件使用。

后续步骤

在分支组件中探索条件逻辑。
在 API 参考中了解更多关于特定变量组件的格式化选项：

使用变量

在本页面