变量组件

概述

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

<Var>: 用于渲染变量。
<Num>: 用于格式化带有本地化的数字。
<Currency>: 用于格式化带有本地化的货币值。
<DateTime>: 用于格式化日期和时间。

这些组件用于 <T> 组件内部或作为模板字典条目的一部分，以确保动态内容准确且一致地显示。

在本参考中，我们将介绍：

什么是变量组件以及它们如何工作。
在您的应用程序中使用变量组件的设计模式。
如何使用每个变量组件的一些示例。
使用变量组件时要避免的常见陷阱。

什么是变量组件？

变量组件用于包装动态内容。这包括用户名、数值、日期和货币。这些组件对于维护本地化内容的完整性至关重要，因为它们允许您以符合用户区域设置的方式格式化和显示动态值。

每个变量组件都有专门的行为：

<Var>: 显示一般变量，例如用户名或标识符。
<Num>: 根据特定区域设置规则格式化数值。
<Currency>: 使用符号和本地化规则格式化货币值。
<DateTime>: 使用特定区域设置的约定格式化日期和时间。

虽然 JSX 内容和字符串通过通用翻译 API 进行翻译，但变量组件完全在本地处理。这意味着这些组件中的内容从未发送到翻译服务，确保了数据隐私和安全。

虽然 <Var> 组件用作一般变量的通用组件，但 <Num>、<Currency> 和 <DateTime> 组件用于需要本地化格式的特定类型数据。对于这些，我们使用 JS i18n API 根据用户的区域设置格式化内容。

设计模式

在 `<T>` 中包装变量组件

变量组件通常被包装在 <T> 组件中或作为字典条目的一部分。这确保了周围的内容被翻译，而变量内容动态渲染且不被改变。

import { T, Var } from 'gt-next';
 
export default function UserGreeting({ user }) {
  return (
    <T id="greeting">
      Hello, <Var>{user.name}</Var>!
    </T>
  );
}

变量组件和本地化

某些变量组件，如 <Num>、<Currency> 和 <DateTime>，包含内置的本地化支持。这些组件会根据用户的区域设置或传递的额外选项自动格式化其内容。

例如：

<Num> 可以显示带有本地化小数分隔符的数字。
<Currency> 可以使用正确的货币符号和位置格式化数值。
<DateTime> 可以根据特定区域规则格式化日期和时间。

您还可以通过直接将属性传递给这些组件来覆盖默认的区域设置和格式选项。

数据隐私

如上所述，变量组件在本地处理所有重新格式化；因此，没有信息被发送到通用翻译 API 进行翻译。这非常适合保持敏感数据（如用户名或账号）私密和安全。

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

<Var>: 不会根据区域设置更改格式的私密信息：例如，用户名、账号。
<Num>: 应根据区域设置格式化的私密数值：例如，订单数量、年龄、距离。
<Currency>: 应根据区域设置格式化的私密货币数值：例如，交易金额、账户余额。
<DateTime>: 应根据区域设置格式化的私密日期和时间值：例如，账户创建日期、订单时间戳。

需要注意的是，分支组件和 <T> 组件并不适用，因为它们会将数据发送到通用翻译 API 进行翻译。

示例

`<Var>` 示例

由于 <Var> 组件不会重新格式化内容，因此几乎总是被包裹在 <T> 组件中。

在这个示例中，我们看到将变量传递给 value 字段或将变量作为 <Var> 组件的子元素传递具有相同的效果。与其他组件一样，<Var> 组件可以用于包裹任何任意的 JSX 内容。

import { T, Var } from 'gt-next';
 
export default function UserGreeting({ user }) {
  return (
    <T id="greeting">
      你好, <Var>{user.name}</Var>!
      你的地址是 <Var value={user.addr} />
    </T>
  );
}

`<Num>` 示例

与 <Var> 组件不同，<Num> 组件用于根据特定语言环境的规则格式化数值。在这个示例中，我们可以看到 <Num> 组件如何既可以作为 <T> 组件的子元素使用，也可以作为独立组件使用。

import { T, Num } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';
 
export default function OrderSummary({ order }) {
  return (
    <>
      <T id="orderSummary">
        你的购物车中有 <Num value={order.quantity} /> 件商品。
      </T>
      <Badge>
        <Num>{order.quantity}</Num>
      </Badge>
    </>
  );
}

`<Currency>` 示例

<Currency> 组件接受一个数值并根据提供的货币字符串进行格式化。在这个示例中，我们看到 <Currency> 组件如何既可以作为 <T> 组件的子元素使用，也可以作为独立组件使用。

import { T, Currency } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';
 
export default function OrderSummary({ order }) {
  return (
    <>
      <T id="orderSummary">
        你的总金额是 <Currency currency={curr}>{order.total}</Currency>。
      </T>
      <Badge>
        <Currency value={order.total} currency={curr} />
      </Badge>
    </>
  );
}

`<DateTime>` 示例

<DateTime> 组件根据用户的语言环境格式化日期和时间值。再次，我们看到 <DateTime> 组件如何既可以作为 <T> 组件的子元素使用，也可以作为独立组件使用。

import { T, DateTime } from 'gt-next';
 
export default function OrderSummary({ order }) {
  return (
    <T id="orderSummary">
      你的订单下单日期是 <DateTime value={order.date} />
    </T>
    <DateTime>{order.date}</DateTime>
  );
}

变量组件对于在翻译中显示动态和私有内容至关重要。
所有重新格式化都是在本地完成的，确保没有敏感数据被发送到通用翻译 API。
像 <Num>、<Currency> 和 <DateTime> 这样的组件提供本地化功能以确保准确的格式化，而 <Var> 组件用于不需要重新格式化的一般变量。

下一步

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