Componentes Variables

Resumen

Los Componentes Variables en gt-next te permiten insertar contenido dinámico, no traducible en las traducciones. Estos componentes incluyen:

<Var>: Para renderizar variables.
<Num>: Para formatear números con localización.
<Currency>: Para formatear valores de moneda con localización.
<DateTime>: Para formatear fechas y horas.

Estos componentes se utilizan dentro de componentes <T> o como parte de entradas de diccionario de plantillas para asegurar que el contenido dinámico se muestre de manera precisa y consistente.

En esta referencia, cubriremos:

Qué son los Componentes Variables y cómo funcionan.
Patrones de diseño para usar Componentes Variables en tus aplicaciones.
Algunos ejemplos de cómo usar cada Componente Variable.
Errores comunes a evitar al trabajar con Componentes Variables.

¿Qué son los Componentes Variables?

Los Componentes Variables se utilizan para envolver contenido dinámico. Esto incluye nombres de usuario, valores numéricos, fechas y monedas. Estos componentes son esenciales para mantener la integridad del contenido localizado, ya que te permiten formatear y mostrar valores dinámicos de una manera que se alinea con la configuración regional del usuario.

Cada Componente Variable tiene un comportamiento especializado:

<Var>: Muestra variables generales, como nombres de usuario o identificadores.
<Num>: Formatea valores numéricos según las reglas específicas de la configuración regional.
<Currency>: Formatea valores monetarios con símbolos y reglas de localización.
<DateTime>: Formatea fechas y horas utilizando convenciones específicas de la configuración regional.

Mientras que el contenido JSX y las cadenas de texto se traducen a través de las API de Traducción General, los Componentes Variables se manejan completamente de manera local. Esto significa que el contenido dentro de estos componentes nunca se envía al servicio de traducción, garantizando la privacidad y seguridad de los datos.

Mientras que el componente <Var> se utiliza como un recurso general para variables generales, los componentes <Num>, <Currency>, y <DateTime> se utilizan para tipos específicos de datos que requieren formato de localización. Para estos, utilizamos la API de i18n de JS para formatear el contenido de acuerdo con la configuración regional del usuario.

Patrones de Diseño

Envolviendo Componentes Variables en `<T>`

Los Componentes Variables a menudo se envuelven dentro de un componente <T> o como parte de una entrada de diccionario. Esto asegura que el contenido circundante se traduzca mientras que el contenido variable se renderiza dinámicamente y sin alteraciones.

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

Componentes Variables y Localización

Ciertos Componentes Variables, como <Num>, <Currency>, y <DateTime>, incluyen soporte de localización incorporado. Estos componentes formatean automáticamente su contenido basado en la configuración regional del usuario o en opciones adicionales pasadas como props.

Por ejemplo:

<Num> puede mostrar números con separadores decimales localizados.
<Currency> puede formatear valores con el símbolo de moneda correcto y su posición.
<DateTime> puede formatear fechas y horas según las reglas específicas de la configuración regional.

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

Privacidad de Datos

Como se mencionó anteriormente, los Componentes Variables manejan todo el reformateo localmente; por lo tanto, no se envía información a las APIs de Traducción General para su traducción. Esto es perfecto para mantener datos sensibles, como nombres de usuario o números de cuenta, privados y seguros.

Cada Componente Variable maneja el formato de manera diferente y debe usarse para tipos específicos de contenido privado:

<Var>: Información privada que no cambia de formato según la configuración regional: por ejemplo, nombres de usuario, números de cuenta.
<Num>: Valores numéricos privados que deben formatearse según la configuración regional: por ejemplo, cantidades de pedidos, edad, distancia.
<Currency>: Valores de moneda privados que deben formatearse según la configuración regional: por ejemplo, montos de transacciones, saldos de cuentas.
<DateTime>: Valores de fecha y hora privados que deben formatearse según la configuración regional: por ejemplo, fechas de creación de cuentas, marcas de tiempo de pedidos.

Cabe señalar que lo mismo no es cierto para los Componentes de Ramificación y los componentes <T>, que sí envían datos a las APIs de Traducción General para su traducción.

Ejemplos

Ejemplo de `<Var>`

Debido a que el componente <Var> no reformatea el contenido, casi siempre se envuelve en un componente <T>.

En este ejemplo vemos que pasar una variable al campo value o pasar una variable como hijo del componente <Var> tiene el mismo efecto. Como con cualquier otro componente, el componente <Var> se puede usar para envolver cualquier contenido JSX arbitrario.

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

Ejemplo de `<Num>`

A diferencia del componente <Var>, el componente <Num> se utiliza para formatear valores numéricos según las reglas específicas de la localidad. En este ejemplo, podemos ver cómo el componente <Num> se puede usar tanto como hijo de un componente <T> como un componente independiente.

import { T, Num } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';
 
export default function OrderSummary({ order }) {
  return (
    <>
      <T id="orderSummary">
        You have <Num value={order.quantity} /> items in your cart.
      </T>
      <Badge>
        <Num>{order.quantity}</Num>
      </Badge>
    </>
  );
}

Ejemplo de `<Currency>`

El componente <Currency> toma un valor numérico y lo formatea según la cadena de moneda proporcionada. En este ejemplo, vemos cómo el componente <Currency> se puede usar tanto como hijo de un componente <T> como un componente independiente.

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

Ejemplo de `<DateTime>`

El componente <DateTime> formatea valores de fecha y hora según la localidad del usuario. Nuevamente, vemos cómo el componente <DateTime> se puede usar tanto como hijo de un componente <T> como un componente independiente.

import { T, DateTime } from 'gt-next';
 
export default function OrderSummary({ order }) {
  return (
    <T id="orderSummary">
      Your order was placed on <DateTime value={order.date} />
    </T>
    <DateTime>{order.date}</DateTime>
  );
}

Los Componentes Variables son esenciales para mantener la visualización de contenido dinámico y privado en las traducciones.
Todo el reformateo se realiza localmente asegurando que no se envíen datos sensibles a las API de Traducción General.
Componentes como <Num>, <Currency>, y <DateTime> proporcionan características de localización para asegurar un formato preciso mientras que el componente <Var> se utiliza para variables generales que no requieren reformateo.

Próximos Pasos

Explora la lógica condicional en Componentes de Ramificación.
Aprende más sobre las opciones de formato para Componentes de Variable específicos en la Referencia de API.