@puraty/i18n-typed-message

A type-safe, minimalist Internationalization (i18n) message manager for TypeScript projects. This library eliminates runtime errors by enforcing translation key existence and placeholder parameter usage at compile time.

It is designed for high reliability and zero-cost abstraction over your message files.

Features

• Compile-Time Type Safety: TypeScript checks if your translation key exists and if all required parameters ({name}, {count}) are provided.
• Minimalist Core: Focuses purely on message substitution without heavy date/currency formatting dependencies.
• ESM First: Modern module structure for Node.js and browser bundlers.

Installation

npm install @puraty/i18n-typed-message

Usage

1. Define Message Structure

First, define the exact structure of your messages, including all placeholders, in a TypeScript file.

// src/messages.ts (Define the structure of translation keys)

export type AppMessages = {
    // Parameters: {appName} is required
    'welcome.title': 'Welcome to {appName}!', 
    
    // Parameters: {userName} and {count} are required
    'user.greeting': 'Hello, {userName}. You have {count} new messages.', 
    
    // No parameters
    'button.save': 'Save',
};

// The translation data type must conform to the keys in AppMessages
export type TranslationData = {
    [K in keyof AppMessages]: string;
};

2. Prepare Translation Files

Create your translation files (e.g., en.json, es.json) based on the TranslationData structure.

// en.json
{
    "welcome.title": "Welcome to {appName}!",
    "user.greeting": "Hello, {userName}. You have {count} new messages.",
    "button.save": "Save"
}

// es.json (Español)
{
    "welcome.title": "¡Bienvenido a {appName}!",
    "user.greeting": "Hola, {userName}. Tienes {count} mensajes nuevos.",
    "button.save": "Guardar"
}

3. Initialize and Use

Initialize the manager with your default locale messages, and use the t() function.

import { I18nManager } from '@puraty/i18n-typed-message';
import { TranslationData } from './messages'; // Import user-defined types

// Assume enMessages is loaded from en.json
const enMessages: TranslationData = /* ... en.json content ... */;

// Pass the message structure type (T) to enable type checking
const i18n = new I18nManager<TranslationData>('en-US', enMessages);

// Success: Compile OK
const welcome = i18n.t('welcome.title', { appName: 'My App' });
console.log(welcome); // Output: "Welcome to My App!"

// Error Example: (Compile-time error prevents runtime bugs)
const error2 = i18n.t('welcome.title');
// Type Error: Property 'appName' is missing in type '{}'.
const error3 = i18n.t('welcome.title', { appName: 'My App', extra: 1 });
// Type Error: Object literal may only specify known properties.

API Reference

| Function | Description | | :--- | :--- | | new I18nManager<T>(locale, messages) | Creates a new I18n manager. T is the type of the translation messages. | | t<K>(key, params) | Type-safe retrieval and substitution of a translation message. | | setLocale(locale, messages) | Changes the current locale and the message data set. | | getLocale() | Returns the current active locale string. |

License

This project is licensed under the ISC License. See the LICENSE file for details.

Contributing

Feel free to open issues or submit pull requests to improve this utility!