Localizer

@localizer/core 1.2.1

Localizer applies a selected locale to Localizable objects. Use getLocalizer() to create a Localizer instance.

import { getLocalizer, loc } from '@localizer/core';

const localizable = loc((locale) => `Current locale is ${locale}`);

const localizer = getLocalizer('en-US');
const localizedString: string = localizer(localizable);

console.log(localizedString);

Current locale is en-US

A Localizer can process a Localizable object or a function that generates one, such as a value formatter. When given a function, it returns a new function that produces a localized string.

import { getLocalizer, loc } from '@localizer/core';

const localizableFn = (value: number) =>
  loc((locale) => `Value is ${value} in locale ${locale}`);

const localizer = getLocalizer('en-US');
const localizedFunction: (value: number) => string = localizer(localizableFn);

console.log(localizedFunction(42));

Value is 42 in locale en-US

Locale resolution

Translations are often defined at the language level (e.g., en for English) rather than the locale level (e.g., en-US for U.S. English). When specific locale translations are incomplete, the library falls back to a predefined set of locales to ensure comprehensive coverage.

The fallback mechanism is controlled by the fallbackLocales configuration property. Below is an example of how locale resolution works with the default configuration (fallbackLocales set to ['en']):

Input Locale	Resolution Chain
en	en
en-US	en-US → en
sv-FI	sv-FI → sv → en

For en, the library uses en translations. For en-US, it tries en-US first, then falls back to en. For sv-FI, it checks sv-FI, then sv, and finally en.

This ensures translations remain comprehensive even with missing locale data.

Implicit localization

experimental

In rapid prototyping, applying Localizer functions explicitly can be tedious. The library supports implicit localization, activated via the activeLocale property or the setActiveLocale() function, simplifying workflows for temporary projects.

import { loc, setActiveLocale } from '@localizer/core';

const localizable = loc((locale) => `Current locale is ${locale}`);

// This will throw an error, because implicit localization is not enabled
// console.log(`Explicit mode: ${localizable}`);

setActiveLocale('en-US');
console.log(`Implicit mode: ${localizable}`);

Implicit mode: Current locale is en-US

WARNING

Implicit localization is not recommended for production use, as it may lead to inconsistent or incorrect outputs due to accidental plain stringification instead of precise, locale-aware formatting.

Special localizers

UninitializedLocalizer

This localizer throws a TypeError when invoked, helping identify race conditions caused by delayed or improper locale initialization.

import { UninitializedLocalizer, Empty } from '@localizer/core';

console.log(UninitializedLocalizer(Empty)); 
> RangeError: Attempt to use Localizer before locale was set 

TestLocalizer

experimental

This localizer consistently produces locale-independent machine representations of localizable values. It is particularly useful for unit or integration testing, where ensuring reproducibility and avoiding locale-specific variations is critical.

import { TestLocalizer } from '@localizer/format';
import { decimal, date } from '@localizer/format';
import { dictionary } from '@localizer/translate';

const translations = dictionary({
  files: (count: number) => ({
    en: loc`${decimal(count)} files`,
    fi: loc`${decimal(count)} tiedostoa`,
    sv: loc`${decimal(count)} filer`,
  }),
});

describe('TestLocalizer', () => {
  it('should produce locale-independent representations', () => {
    expect(TestLocalizer(date(1751555555000))).toBe('"2025-07-03T15:12:35.000Z"');
    expect(TestLocalizer(translations.files(5))).toBe('files(5)');
  });
});