Core

@better-translate/core funciona en cualquier proyecto TypeScript. Sin dependencias de framework, sin requisitos de tiempo de ejecución. La misma configuración y la misma API se aplican tanto si estás en Next.js, Astro, React, Bun, Node.js, un script, o cualquier otro entorno TypeScript.

Adapters son extensiones del core que añaden helpers específicos del framework: enrutamiento consciente de locale, contexto de React, helpers por solicitud, etc. Pero todo se construye sobre el mismo core.

Cuándo usar el core directamente

Usa el core sin un adapter cuando no necesites helpers específicos del framework. Esto incluye servidores, APIs, scripts, bibliotecas compartidas, o cualquier entorno TypeScript donde no exista un adapter para tu configuración.

1. Instala el paquete

npm install @better-translate/core

2. Crea 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. Usa el traductor en cualquier lugar

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

4. Añade 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 intenta con el locale de fallback. Si el fallback tampoco la tiene, devuelve la cadena de la clave misma.

• → Valor de locale faltante → valor de locale de fallback
• → Valor de fallback faltante → cadena de la clave

Loaders asíncronos

Registra loaders de locale para idiomas que no quieras precargar. Los locales cargados se almacenan en caché después de la primera carga exitosa.

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 almacena en caché11await translator.loadLocale("fr");

5. Extrae cadenas automáticamente con el CLI

En lugar de nombrar las claves manualmente, marca las cadenas con { bt: true } y deja que el CLI las extraiga y genere las claves automáticamente:

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

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

Continúa con

• Proveedor de React y hooks
• Configuración de Next.js App Router
• Helpers de solicitud de Astro

Ejemplos

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