npm package: @i18nai/sdk
Description: > [!WARNING]   > This library is currently in development and not all features are available.
Latest version: 0.0.1-dev.0.0.7

# @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

```bash
# 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

```typescript
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

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

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

### Nested Translations

```typescript
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

```typescript
// 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

```typescript
new I18n(options: I18nOptions)
```

#### Options

```typescript
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.

```typescript
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

```html
<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