i18n-micro

A minimal, type-safe internationalization library for TypeScript. Built for the client, works everywhere.

Features

• Tiny — single class, zero dependencies
• Type-safe — translation keys are fully typed via deep path inference
• Interpolation — supports {placeholder} replacements in strings
• Isomorphic — works in the browser and on the server

Install

bun add i18n-micro

npm install i18n-micro

Usage

Define your translations

import I18n from "i18n-micro";

const i18n = new I18n(
    ["en", "es"],
    "en",
    {
        en: {
            greeting: "Hello, {name}!",
            nav: {
                home: "Home",
                about: "About",
            },
        },
        es: {
            greeting: "¡Hola, {name}!",
            nav: {
                home: "Inicio",
                about: "Acerca de",
            },
        },
    }
);

Translate

i18n.t("greeting", {name: "Daniel"}); // "Hello, Daniel!"
i18n.t("nav.home");                      // "Home"

Translation keys are fully autocompleted — typos are caught at compile time:

i18n.t("nav.hoem"); // ❌ TypeScript error

Change locale

i18n.changeLocale("es");
i18n.t("nav.home"); // "Inicio"

API

new I18n(locales, defaultLocale, texts)

| Param | Type | Description | |-----------------|--------------------------------|------------------------------------| | locales | readonly string[] | Array of supported locale codes | | defaultLocale | string (member of locales) | The locale used on initialization | | texts | Record<locale, translations> | Translation objects keyed by locale |

i18n.t(path, interpolableEntries?)

Returns the translated string at the given dot-separated path. Optionally replaces {key} placeholders with values from interpolableEntries.

i18n.changeLocale(newLocale)

Switches the active locale. newLocale must be one of the locales defined in the constructor.

Type Safety

The library infers deep dot-notation paths from your translation objects at the type level. This means:

• Only valid paths that resolve to a string leaf are accepted by t()
• Locale codes passed to changeLocale() are restricted to the ones you defined
• All of this works without codegen or extra build steps.

License

MIT © Daniel Quintero