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.

Choose technology

React

Vue.js

Vanilla TypeScript

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 installs all core components of the @localizer ecosystem, simplifying setup and ensuring compatibility. For details on included modules and usage, see the API Reference.

Translation (basic)

experimental

@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 } from '@localizer/core';
import { dictionary } from '@localizer/translate';

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

const yes = translations.key('yes');
const no = translations.key('no');

The dictionary() initializes a translation dictionary with specified locales. Call key(<translation key>) method to get a reference to a specific translated message.

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(yes));
console.log(frenchLocalizer(no));

This will output the following to the console:

Yes
Non

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.

TIP

For more details and comprehensive examples, refer to the Translation Documentation. It provides in-depth guidance on utilizing translation utilities, managing dictionaries, and implementing advanced localization techniques.

Translation (advanced)

experimental

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 } from '@localizer/core';
import { dictionary } from '@localizer/translate';

const translations = dictionary('Translations', {
  en: {
    files: `
.input {$count :number}
.match $count
0   {{No files}}
one {{{$count} file}}
*   {{{$count} files}}`,
  },
  ru: {
    files: `
.input {$count :number}
.match $count
0   {{Нет файлов}}
one {{{$count} файл}}
few {{{$count} файла}}
*   {{{$count} файлов}}`,
  },
});

const files = translations.key('files', true);

The dictionary() initializes a translation dictionary with specified locales. Call key(<translation key>, true) method to get a reference to a specific dynamic translated message as a value formatter.

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 = files({ count: 21 });

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

TIP

The library uses Unicode MessageFormat 2.0 for message formatting.

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.

TIP

For more details and comprehensive examples, refer to the Translation Documentation. It provides in-depth guidance on utilizing translation utilities, managing dictionaries, and implementing advanced localization techniques.

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 } from '@localizer/core';
import { dateTime } from '@localizer/format';

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:

8/18/2025, 04:43:25 AM
2025-08-18 04:43:25

TIP

Discover more about the available formatters and their capabilities in the Formatting Documentation. This section provides detailed examples and guidelines to help you effectively format dates, numbers, currencies, and other locale-specific values.