Core

@better-translate/core funciona en cualquier proyecto TypeScript. Sin dependencia de framework ni requisito de runtime concreto. La misma configuración y la misma API aplican en Next.js, Astro, React, Bun, Node.js, un script o cualquier otro entorno TypeScript.

Los adaptadores son extensiones de core que añaden utilidades específicas del framework: enrutamiento con locale, contexto de React, helpers por petición, etc. Pero todo se construye sobre el mismo core.

Cuándo usar core directamente

Usa core sin adaptador cuando no necesites utilidades del framework. Incluye servidores, APIs, scripts, bibliotecas compartidas o cualquier entorno TypeScript donde no exista adaptador para tu stack.

1. Instalar el paquete

npm install @better-translate/core

2. Crear un archivo de traductor

Crea src/i18n.ts:

1import { configureTranslations } from "@better-translate/core";23const en = {4  home: {5    title: "Hello",6    description: "This is the English version.",7  },8} as const;910const es = {11  home: {12    title: "Hola",13    description: "Esta es la version en espanol.",14  },15} as const;1617export const translator = await configureTranslations({18  availableLocales: ["en", "es"] as const,19  defaultLocale: "en",20  fallbackLocale: "en",21  messages: { en, es },22});

3. Usar el traductor en cualquier sitio

1import { translator } from "./i18n";23translator.t("home.title"); // "Hello"4translator.t("home.title", { locale: "es" }); // "Hola"5translator.t("home.description", { locale: "es" });

4. Añadir otro locale más tarde

1const fr = {2  home: {3    title: "Bonjour",4    description: "Ceci est la version francaise.",5  },6} as const;78export const translator = await configureTranslations({9  availableLocales: ["en", "es", "fr"] as const,10  defaultLocale: "en",11  fallbackLocale: "en",12  messages: { en, es, fr },13});

Comportamiento de fallback

Si el locale activo no tiene una clave, better-translate prueba el locale de fallback. Si el fallback tampoco la tiene, devuelve la cadena de la clave.

• → Falta el valor en el locale → valor del locale de fallback
• → Falta también en el fallback → cadena de la clave

Loaders asíncronos

Registra loaders de locale para idiomas que no quieras precargar. Los locales cargados se cachean tras la primera carga correcta.

1const translator = await configureTranslations({2  availableLocales: ["en", "fr"] as const,3  defaultLocale: "en",4  messages: { en },5  loaders: {6    fr: async () => import("./messages/fr").then((m) => m.default),7  },8});910// carga fr bajo demanda y lo cachea11await translator.loadLocale("fr");

5. Extraer cadenas automáticamente con la CLI

En lugar de nombrar claves a mano, marca cadenas con { bt: true } y deja que la CLI las extraiga y les asigne clave:

1import { t } from "@better-translate/core";23// Escribe la cadena fuente directamente — la CLI la convierte en clave correcta4t("Hello world", { bt: true });

Ejecuta npx bt extract para sincronizar las cadenas en tu archivo de locale fuente y reescribir las llamadas a claves correctas. Consulta la documentación de la CLI para la configuración completa.

Continuar con

• Provider y hooks de React
• Configuración de Next.js App Router
• Helpers de petición en Astro

Ejemplos

• core-elysia-example — configuración TypeScript/Node.js plana