jralvarenga/better-translate

Core Skill

Use this guide when you want the smallest possible Better Translate setup.

What this package is for

@better-translate/core is the base translation engine.

Use it when:

• the app is plain TypeScript
• the code runs on Node.js, Bun, or an API
• you want one shared translator file before adding framework adapters

Smallest correct setup

Create one translator file and export it:

import { configureTranslations } from "@better-translate/core";

const en = {
  home: {
    title: "Hello",
  },
} as const;

const es = {
  home: {
    title: "Hola",
  },
} as const;

export const translator = await configureTranslations({
  availableLocales: ["en", "es"] as const,
  defaultLocale: "en",
  fallbackLocale: "en",
  messages: { en, es },
});

Keep TypeScript autocomplete available

TypeScript key autocomplete depends on the shared exported translator.

• Keep each messages object as const
• Export one shared translator
• Call translator.t(...) from code that needs typed keys

import { translator } from "./i18n";

translator.t("home.title");
translator.t("home.title", { locale: "es" });

That keeps locale values and translation keys inferred from the messages you configured.

When to add another package

• Add @better-translate/react when React components need hooks or locale switching
• Add @better-translate/nextjs when Next.js routes or server helpers need locale awareness
• Add @better-translate/astro when Astro requests need locale awareness
• Add @better-translate/md when content files should follow the same locale setup

Auto-extract strings without naming keys

Use { bt: true } in any t() call to write source text directly instead of inventing a key:

t("Hello world", { bt: true });

Then run npx bt extract to generate keys automatically and rewrite the calls. See skills/cli/SKILL.md for the full setup.

Main idea

Do not create one translation system per framework.

Create one core translator first, then let adapters read from it.