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%
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