I18n Lite

i18n-lite-ts is a TypeScript localization module created to add super simple translations to a web app.

It's framework agnostic, but super easy to use and tested with React.

Quick start

You can use it in any web page:

Install the module

npm install @mattiamarchesini/i18n-lite-ts

Just use it

• Import the I18n class
• Instantiate it once, and use it all around the app

Guide

Translations

Create an object containing translations:

export const translations: Translations = { "en": { "hello": "Hello" }, "it": { "hello": "Ciao" } };

Or a JSON file (for example: /data/translations.json):

{ "en": { "hello": "Hello" }, "it": { "hello": "Ciao" } }

Initialization

Create a new instance:

export const i18n = new I18n(
    null,           // Current language as language code: keep it null to let the class detect it from a 'lang' query parameter (if present), or from the browser's settings
    translations   // Object containing translations
);

Usage

Now you just need to invoke the translation method with your instance:

i18n.t( 'hello' );

For example in contexts or methods:

alert( i18n.t( 'hello' ) );

Or in JSX:

<div>
    <h3>{ i18n.t( 'hello' ) }</h3>
</div>

JSON fetching

Don't want to fetch JSONs by yourself? Just pass the JSON file's URL:

export const i18n = new I18n(
    null,                       // Current language as language code: keep it null to let the class detect it from a 'lang' query parameter (if present), or from the browser's settings
    '/data/translations.json'   // Path to the JSON file to fetch to get translations
);

Be aware that fetching takes some milliseconds, so your app could render faster and you'll not see translations.

To have full control of timings just instantiate it normally and await the translations after:

export const i18n = new I18n(
    null,   // Current language as language code: keep it null to let the class detect it from a 'lang' query parameter (if present), or from the browser's settings
    {}      // Ignore translations for now, will fetch them manually in the next lines
);

await i18n.setTranslations( '/data/translations.json' );

// Here you will be sure that translations are available

React

If you use React:

• Instantiate I18n outside the components
• Await for translations just once when rendering the app

export const i18n = new I18n(
    null,   // Current language as language code: keep it null to let the class detect it from a 'lang' query parameter (if present), or from the browser's settings
    {}      // Ignore translations for now, will fetch them manually in the next lines
);

const App: React.FC = () => {
    const [ loaded, setLoaded ] = useState<boolean>( false );

    const loadTranslations = async () => {
        await i18n.setTranslations( '/data/translations.json' );
        setLoaded( true );
    };

    useEffect( () => {
        loadTranslations();
    }, [] );

    if ( !loaded ) {
        return <div>
            <p>...</p>
        </div>;
    }

    return <div>
        <h3>{ i18n.t( 'hello' ) }</h3>
    </div>;
};

Default language

Need to change the default language used for fall backs? Just call:

I18n.setDefaultLanguage( 'en' );

Demo - Quick start

This repo comes with a fully working demo in /demo/index.html, to see it run:

npm install
npm run demo

And open http://127.0.0.1:5173/demo/ in your browser.

Author

• Name: Mattia
• Surname: Marchesini
• Email: [email protected]
• Country: Italy

License

This project is licensed under the Attribution License (MIT-Style). You are free to use and modify the code, would be really appreciated if you give credit to the original author.

© 2025 Mattia Marchesini