Uso de variables

Descripción general

Los componentes variables en gt-next te permiten insertar contenido dinámico en las traducciones. Estos componentes incluyen:

• <Var>: Para mostrar variables.
• <Num>: Para formatear números.
• <Currency>: Para formatear valores monetarios.
• <DateTime>: Para formatear fechas y horas.

En esta guía, cubriremos:

¿Qué son los componentes variables?

Los componentes variables se utilizan para envolver contenido dinámico como nombres de usuario, valores numéricos, fechas y monedas.

Estos componentes te permiten formatear y mostrar valores dinámicos de una manera que se ajusta a la configuración regional de tu usuario, sin requerir traducciones externas.

Utiliza los componentes variables junto con el componente <T> para asegurar que el contenido dinámico se muestre de forma precisa y consistente.

Cada componente variable tiene un comportamiento diferente:

• <Var>: Muestra cualquier contenido de forma dinámica, como nombres de usuario o identificadores.
• <Num>: Da formato a valores numéricos según las reglas específicas de la configuración regional.
• <Currency>: Da formato a valores monetarios con símbolos y reglas de localización.
• <DateTime>: Da formato a fechas y horas utilizando convenciones específicas de la configuración regional.

Mientras que el contenido JSX y las cadenas de texto se traducen mediante la General Translation API, los componentes variables se gestionan completamente de forma local.

Los componentes <Num>, <Currency> y <DateTime> utilizan la JS i18n API para formatear el contenido según la configuración regional del usuario.

Cómo usar componentes de variable

Uso básico

El uso para todos los componentes de variable es el mismo.

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>

Simplemente envuelve el componente de variable alrededor del contenido que deseas mostrar.

Uso de componentes de variable en <T>

Por sí solos, los componentes de variable no hacen mucho, ya que requieren conocer la configuración regional del usuario para formatear el contenido.

Por lo tanto, deberías usar los componentes de variable junto con los componentes <T>.

El componente <T> no solo se encargará de la traducción del contenido circundante, sino que también pasará la configuración regional correcta a sus componentes de variable hijos.

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

Localización de variables

Los componentes <Num>, <Currency> y <DateTime> incluyen soporte de localización incorporado. Estos componentes formatean automáticamente su contenido según la configuración regional seleccionada por el usuario, o según las opciones adicionales que se pasen como props.

Por ejemplo:

• <Num> muestra números con separadores decimales localizados.
• <Currency> muestra valores con símbolos de moneda localizados y posicionamiento adecuado.
• <DateTime> muestra fechas y horas de acuerdo a las reglas específicas de la configuración regional.

También puedes sobrescribir la configuración regional y las opciones de formato predeterminadas pasando props directamente a estos componentes.

Privacidad de datos

Los componentes de variable manejan todo el formateo localmente; por lo tanto, ninguno de sus hijos se envía a las APIs Generales de Traducción para su traducción (cuando se usan con componentes <T>). Esto es perfecto para mantener datos sensibles, como nombres de usuario o números de cuenta, privados y seguros.

Cada componente de variable maneja el formateo de manera diferente y debe usarse para tipos específicos de contenido:

• <Var>: Cualquier dato privado que no requiera formateo
  • Nombres de usuario, números de cuenta, etc.
• <Num>: Valores numéricos privados que deben formatearse según la configuración regional
  • Cantidades de pedidos, edad, distancia, etc.
• <Currency>: Valores de moneda privados que deben formatearse según la configuración regional
  • Montos de transacciones, saldos de cuentas, etc.
• <DateTime>: Valores de fecha y hora privados que deben formatearse según la configuración regional
  • Fechas de creación de cuentas, marcas de tiempo de pedidos, etc.

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

Ejemplos

<Var>

Debido a que el componente <Var> no realiza ningún formato, siempre debe usarse junto con un componente <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>
  );
}

Los componentes de variable también aíslan los datos, por lo que pueden usarse para mostrar contenido dinámico que no forma parte de una traducción.

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

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

En el ejemplo anterior, el operador ternario isAdmin hace que el componente Dashboard sea dinámico.

Sin el componente <Var>, esto sería un uso no válido del componente <T>.

<Num>

El componente <Num> puede usarse como hijo de un componente <T> o como un componente independiente.

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>

El componente <Currency> puede usarse como hijo de un componente <T> o como un componente independiente.

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>

El componente <DateTime> puede usarse como hijo de un componente <T> o como un componente independiente.

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()
  );
}

Errores Comunes

Ignorar Opciones de Localización

Para <Currency>, asegúrate de pasar la prop currency para especificar el tipo de moneda. Esto garantiza que se utilicen el símbolo y el formato de moneda correctos al mostrar el valor.

Otros componentes, como <Num> y <DateTime>, también tienen props opcionales que te permiten personalizar el formato según tus necesidades.

Notas

• Los componentes de variable aíslan los datos, por lo que pueden usarse para mostrar contenido dinámico que no forma parte de una traducción.
• Los componentes de variable no envían datos a las APIs de Traducción General, por lo que son perfectos para mantener datos sensibles privados y seguros.
• Los componentes de variable pueden usarse tanto como hijos de un componente <T> como de forma independiente.

Próximos pasos

• Explora la lógica condicional en Branching Components.
• Obtén más información sobre las opciones de formato para componentes de variables específicas en la Referencia de la API:
  • <Num>
  • <Currency>
  • <DateTime>
  • <Var>