Getting started

This guide provides essential information to get started quickly. From installation to basic usage, you'll learn how to integrate the tool into your workflow and utilize its features effectively. Begin with the installation instructions below, and explore advanced topics and API documentation as needed.

Installation

To get started, install the @localizer/all package, which provides all core components of the @localizer ecosystem in one package.

Use one of the following commands based on your package manager:

npm

npm install @localizer/all

pnpm

pnpm install @localizer/all

yarn

yarn add @localizer/all

bun

bun add @localizer/all

TIP

If you're unsure which package manager to use, start with npm, as it is included with Node.js by default. Choose another option if it better suits your workflow.

Refer to this documentation for detailed information on components and their features.

NOTE

The @localizer/all package provides all core components of the @localizer ecosystem in one package, simplifying setup and ensuring compatibility. For details on included modules and usage, see the API Reference.

Translation (basic)

@localizer provides a vast set of utilities for localization, translation and data formatting. Below are examples for main functionality:

Define a simple dictionary to manage translations for your user interface. This centralized approach ensures easy maintenance and scalability as your application evolves.

Here’s how you can define a basic dictionary:

import { getLocalizer, dictionary } from '@localizer/all';

const translations = dictionary({
  yes: {
    en: 'Yes',
    fr: 'Oui',
    es: 'Sí',
    de: 'Ja',
  },
  no: {
    en: 'No',
    fr: 'Non',
    es: 'No',
    de: 'Nein',
  },
});

// Type of translations is:
// {
//   yes: Localizable;
//   no: Localizable;
// }

The dictionary() function creates a strongly-typed object, ensuring translation keys are validated at compile time to prevent errors from missing or incorrect keys.

To use the translations in your application, you can simply pass the keys to Localizer:

const englishLocalizer = getLocalizer('en-US');
const frenchLocalizer = getLocalizer('fr-FR');

console.log(englishLocalizer(translations.yes));
console.log(frenchLocalizer(translations.yes));

This will output the following to the console:

Yes
Oui

This approach simplifies translation management and integrates with TypeScript, ensuring type safety and autocompletion for all keys.

Using this basic dictionary setup, you can quickly localize your application's user interface. For advanced use cases like dynamic translations or context-based localization, see the advanced examples in this guide.

Translation (advanced)

Dynamic translations allow you to include runtime values like user names, dates, or numbers in your strings. Define a dictionary where translation values are functions that accept arguments and return formatted strings.

Here’s an example of how you can define a dictionary with dynamic translations:

import { getLocalizer, loc } from '@localizer/all';
import { dictionary, plural } from '@localizer/all';
import { one, two, few, many, other } from '@localizer/all';
import { decimal } from '@localizer/all';

const translations = dictionary({
  files: (count: number) => ({
    en: plural(count, {
      0: loc`No files`,
      [one]: loc`${decimal(count)} file`,
      [two]: loc`${decimal(count)} files`,
      [few]: loc`${decimal(count)} files`,
      [many]: loc`${decimal(count)} files`,
      [other]: loc`${decimal(count)} files`,
    }),
    ru: plural(count, {
      0: loc`Нет файлов`,
      [one]: loc`${decimal(count)} файл`,
      [two]: loc`${decimal(count)} файла`,
      [few]: loc`${decimal(count)} файлов`,
      [many]: loc`${decimal(count)} файлов`,
      [other]: loc`${decimal(count)} файлов`,
    }),
  }),
});

// Type of translations is:
// {
//   files: (count: number) => Localizable;
// }

The dictionary() function creates a strongly-typed object where values are functions that accept arguments and return formatted strings. This enables seamless injection of dynamic content into translations.

To use these dynamic translations in your application, you can pass the result to the Localizer:

const englishLocalizer = getLocalizer('en-US');
const russianLocalizer = getLocalizer('ru-RU');

const twentyOneFiles = translations.files(21);

console.log(englishLocalizer(twentyOneFiles));
console.log(russianLocalizer(twentyOneFiles));

This will produce the following output in the console:

21 files
21 файл

Dynamic translations enable personalized and context-aware localization by injecting runtime values like names, dates, or numbers into strings. This approach is ideal for applications requiring user-specific or culturally adaptive content.

For advanced scenarios, such as complex pluralization or external translation service integration, refer to the additional examples in this guide to enhance your localization strategy.

Formatting of values

To format or localize values like dates, numbers, or currencies, use @localizer utilities. These tools ensure data is displayed correctly for any locale.

import { getLocalizer, dateTime } from '@localizer/all';

const now = dateTime(new Date());

const englishLocalizer = getLocalizer('en-US');
const swedishLocalizer = getLocalizer('sv-SE');

console.log(englishLocalizer(now));
console.log(swedishLocalizer(now));

This will produce the following output in the console:

7/2/2025, 01:59:22 PM
2025-07-02 13:59:22