Internationalization (i18n) in TypeScript: A Complete Guide

Internationalization (i18n) in TypeScript: Overview of Tools and Practices

Internationalization (i18n) is the process of designing software so that it can be adapted to various languages and regional standards without changes to the source code. For TypeScript applications, choosing the right i18n library is critical: it affects type safety of translations, performance, and ease of maintenance. In this article, we will look at three main approaches and tools for implementing i18n in TypeScript.

1. i18next — The Classic Solution

i18next is the most popular library for internationalization in the JavaScript/TypeScript ecosystem. It supports many frameworks (React, Vue, Angular) and has an extensive plugin ecosystem.

Installation:

npm install i18next i18next-browser-languagedetector

Basic setup with TypeScript:

import i18n from 'i18next';import { initReactI18next } from 'react-i18next';

// Typing translation resourcesdeclare module 'i18next' {  interface CustomTypeOptions {    defaultNS: 'common';    resources: {      common: typeof import('./locales/en/common.json');    };  }}

i18n.use(initReactI18next).init({  resources: {    en: { common: require('./locales/en/common.json') },    ru: { common: require('./locales/ru/common.json') },  },  lng: 'ru',  fallbackLng: 'en',  interpolation: { escapeValue: false },});

export default i18n;

Usage example in a component:

import { useTranslation } from 'react-i18next';

function Greeting() {  const { t } = useTranslation();  const userName = 'Anna';    return (    <div>      <p>{t('greeting', { name: userName })}</p>      <p>{t('itemsCount', { count: 5 })}</p>    </div>  );}

Pros:

• Huge community and documentation
• Support for pluralization
• Variable interpolation
• Dynamic loading of language resources

Cons:

• Lack of strict typing out of the box
• Need for additional TypeScript configuration for full type safety
• JSON translation files are not automatically typed

2. typesafe-i18n — Strict Typing

typesafe-i18n is a library created specifically for TypeScript. Its main feature is generating types based on your translation files.

Installation:

npm install typesafe-i18n

Setup and example:

// Create a translation file: src/i18n/en/index.tsexport const en = {  greeting: 'Hello {name}!',  itemsCount: 'You have {count} item | You have {count} items',} as const;

// Type generation (runs automatically)// npx typesafe-i18n

// Usage in a componentimport { i18n } from './i18n/i18n-util';

function Profile() {  const LL = i18n();    return (    <div>      <p>{LL.greeting({ name: 'Anna' })}</p>      <p>{LL.itemsCount({ count: 5 })}</p>    </div>  );}

Pros:

• Full type safety at all stages
• Autocomplete in IDE (IntelliSense)
• Parameter validation at compile time
• Support for pluralization and interpolation

Cons:

• Smaller community and fewer plugins
• Requires type generation on every translation change
• Less flexibility for non-standard scenarios

3. Lingui — Ecosystem with Compilation

Lingui is a modern library that uses compilation for