Uso de la función 't'

Guía completa sobre cómo usar la función t para traducir y formatear varios tipos de contenido.

Uso de la extensión

Al usar la extensión de Quetzal para VSCode/Cursor, podrás envolver tus cadenas con la función t automáticamente. Sin embargo, esta página documentará el uso manual.

Importar la función ‘t’

Para traducir cadenas en tu aplicación, deben estar envueltas en la función t de Quetzal.

La función t es cómo Quetzal sabe qué enviar para traducción y dónde colocar el texto traducido.

//Next.js
import { useI18n } from "@quetzallabs/i18n"; //Componentes del lado del cliente
import { getI18nUtils } from "@quetzallabs/i18n"; //Código del lado del servidor

//React:
import { useI18n } from "@quetzallabs/i18n-react-native"; //Componentes del lado del cliente
import { getI18nUtils } from "@quetzallabs/i18n-react-native"; //Código del lado del servidor

export default function Page() {
  const { t } = useI18n(); //Para componentes del lado del cliente
  const { t } = await getI18nUtils(); //Para código del lado del servidor
}

La función t de Quetzal está construida sobre la función t de next-intl y se comporta de manera similar. Consulte la documentación de next-intl para obtener instrucciones de uso de la función t.

Envolver Cadenas

Una vez que hayas importado e inicializado la función t, puedes comenzar a marcar cadenas para la traducción

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return <p>{t("Aquí hay texto normal")}</p>;
}

Salida: Aquí está el texto normal

Casos especiales

Texto Dinámico

Usa marcadores de posición para insertar valores dinámicamente en tu texto traducido.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t("Aquí hay un {dynamic1} con un {dynamic2}", {
        dynamic: 4,
        dynamic2: "cuatro",
      })}
    </p>
  );
}

Resultado: Aquí hay un 4

Pluralización

Manejar la pluralización según el valor pasado.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t(
        "Tienes {count, plural, =0 {ningún seguidor aún} =1 {un seguidor} other {# seguidores}}.",
        { count: 4 }
      )}
    </p>
  );
}

Resultado: Tienes 4 seguidores.

Números Ordinales

Formatear números ordinales correctamente en diferentes idiomas.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t(
        "¡Es tu {year, selectordinal, one {#er} two {#do} few {#er} other {#to}} cumpleaños!",
        { year: 1 }
      )}
    </p>
  );
}

Resultado: ¡Es tu 1er cumpleaños!

Texto en múltiples casos

Manejar selecciones de múltiples casos, como traducciones basadas en género.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t("{gender, select, female {Ella} male {Él} other {Ellos}} está en línea.", {
        gender: "male",
      })}
    </p>
  );
}

Resultado: Está en línea.

Escapar llaves

Escapa las llaves en tu texto usando comillas simples.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return <p>{t("Escapa las llaves con comillas simples (ej. '{nombre'})")}</p>;
}

Salida: Escape las llaves con comillas simples (ej. {nombre})

Formato de texto enriquecido

Incorpora texto enriquecido o elementos HTML en tus traducciones.

import { useI18n } from "@quetzallabs/i18n";
import { ReactNode } from "react";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t("Consulte <guidelines>las pautas</guidelines>.", {
        guidelines: (chunks: ReactNode) => <a href="/guidelines">{chunks}</a>,
      })}
    </p>
  );
}

Resultado: Consulte las pautas.

Elementos HTML incrustados

Puedes incrustar elementos HTML directamente en tus cadenas traducidas.

import { useI18n } from "@quetzallabs/i18n";
import { ReactNode } from "react";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t("Esto es <important>importante</important>", {
        important: (chunks: ReactNode) => <b>{chunks}</b>,
      })}
    </p>
  );
}

Resultado: Esto es importante

Números regulares

Formatear números simples según la configuración regional del usuario.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return <p>{t(1234.56)}</p>;
}

Salida: 1.234,56 (en configuración regional es-419)

Monedas

Formatear números como monedas.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return <p>{t(499.9, { style: "currency", currency: "USD" })}</p>;
}

Salida: $499.90

Porcentajes

Formatear números como porcentajes.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return <p>{t(0.857, { style: "percent" })}</p>;
}

Salida: 85,7%

Formatos de Números Personalizados

Aplicar formato personalizado de números.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>{t(1234.56, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}</p>
  );
}

Resultado: 1.234,56

Sintaxis ICU para números

Utilice la sintaxis ICU para formatear números en los mensajes.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t("Este producto cuesta {price, number, currency}", {
        price: 32000.99,
        number: {
          currency: {
            style: "currency",
            currency: "EUR",
          },
        },
      })}
    </p>
  );
}

Resultado: Este producto cuesta €32.000,99

Fechas

Formatear fechas según la configuración regional del usuario.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t(new Date(), {
        year: "numeric",
        month: "long",
        day: "numeric",
      })}
    </p>
  );
}

Output: August 12, 2024 (in en-US locale)

Rangos de fechas

Formatear un rango de fechas.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t([new Date("2020-01-01"), new Date("2020-12-31")], {
        year: "numeric",
        month: "long",
        day: "numeric",
      })}
    </p>
  );
}

Output: January 1, 2020 – December 31, 2020 (in en-US locale)

Listas (Conjunciones)

Formatear listas usando conjunciones.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t(["HTML", "CSS", "JavaScript"], {
        type: "conjunction",
      })}
    </p>
  );
}

Resultado: HTML, CSS y JavaScript

Listas (Disyunciones)

Formatear listas usando disyunciones.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  return (
    <p>
      {t(["HTML", "CSS", "JavaScript"], {
        type: "disyunción",
      })}
    </p>
  );
}

Resultado: HTML, CSS o JavaScript

Listas de Variables

Formatear listas generadas de variables.

import { useI18n } from "@quetzallabs/i18n";

export default function Page() {
  const { t } = useI18n();

  const usuarios = [
    { id: 1, nombre: "Alice" },
    { id: 2, nombre: "Bob" },
    { id: 3, nombre: "Charlie" },
  ];

  const elementos = usuarios.map((usuario) => (
    <a key={usuario.id} href={`/usuario/${usuario.id}`}>
      {usuario.nombre}
    </a>
  ));

  return <p>{t(elementos)}</p>;
}

Salida: Alice, Bob y Charlie