@i18nai/sdk

[!WARNING]
This library is currently in development and not all features are available.

A framework-agnostic TypeScript internationalization library that provides type-safe translations, nested key support, and parameter interpolation.

Installation

# Using npm
npm install @i18nai/sdk

# Using yarn
yarn add @i18nai/sdk

# Using pnpm
pnpm add @i18nai/sdk

# Using bun
bun add @i18nai/sdk

Features

• 🔤 Type-safe translations with full TypeScript support
• 🎯 Nested translation keys using dot notation
• 🔄 Parameter interpolation with {{param}} syntax
• 🌐 Dynamic locale switching with fallback support
• ⚡️ Runtime translation addition and updates
• 📦 Tree-shakeable ESM module
• 🌍 UMD format for direct browser usage
• 🪶 Lightweight with zero dependencies

Usage

Basic Setup

import { I18n } from "@i18nai/sdk";

const i18n = new I18n({
  defaultLocale: "en",
  translations: {
    en: {
      welcome: "Welcome",
      greeting: "Hello, {{name}}!"
    },
    es: {
      welcome: "Bienvenido",
      greeting: "¡Hola, {{name}}!"
    }
  }
});

Simple Translation

// Basic translation
const message = i18n.t("welcome"); // "Welcome"

// With parameters
const greeting = i18n.t("greeting", { 
  params: { name: "John" } 
}); // "Hello, John!"

Nested Translations

const i18n = new I18n({
  defaultLocale: "en",
  translations: {
    en: {
      nav: {
        home: "Home",
        settings: {
          profile: "Profile Settings",
          account: "Account Settings"
        }
      }
    }
  }
});

const settingsTitle = i18n.t("nav.settings.profile"); // "Profile Settings"

Locale Management

// Get current locale
const currentLocale = i18n.getLocale(); // "en"

// Switch locale
i18n.setLocale("es");

// Add new translations at runtime
i18n.addTranslations("fr", {
  welcome: "Bienvenue",
  greeting: "Bonjour, {{name}}!"
});

API Reference

Constructor

new I18n(options: I18nOptions)

Options

interface I18nOptions {
  defaultLocale: string;
  translations: Record<string, Translation>;
}

interface Translation {
  [key: string]: string | Translation;
}

Methods

t(key: string, options?: TranslateOptions): string

Translates a key with optional parameter interpolation.

interface TranslateOptions {
  params?: Record<string, string | number>;
}

setLocale(locale: string): void

Changes the current locale. Falls back to default locale if the specified locale is not found.

getLocale(): string

Returns the current active locale.

addTranslations(locale: string, translations: Translation): void

Adds or updates translations for a locale at runtime.

Module Formats

The package is distributed in multiple formats:

• ESM: dist/index.js
• UMD: dist/index.umd.js
• TypeScript types: dist/index.d.ts

Browser Usage

<script src="https://unpkg.com/@i18nai/sdk/dist/index.umd.js"></script>
<script>
  const i18n = new I18nAI.I18n({
    defaultLocale: "en",
    translations: {
      en: { hello: "Hello" }
    }
  });
</script>

License

MIT