Transformations

@localizer/transform 1.0.1

Sometimes, you may need to perform additional processing on the results of formatting or translation. Common use cases include altering the character case. Since character case transformations can depend on locale-specific rules, the library offers a suite of transformation utilities that seamlessly integrate with its core functionality.

The primary method for applying transformations is the transform() function. This utility allows you to modify the output of a Localizable object by applying a sequence of transformations. Each transformation is applied in the order specified, enabling flexible and powerful customization of localized content.

import { getLocalizer } from '@localizer/core';
import { countryName } from '@localizer/format';
import { transform } from '@localizer/transform'; 

const localizer = getLocalizer('en-US');
const someLocalizable = countryName('FI');

const transformed = transform(someLocalizable, [upperCase]); 
console.log(localizer(transformed)); 

FINLAND

You can also apply transform() directly to a value formatter. This creates a new value formatter that automatically applies the specified transformations to its output:

import { getLocalizer } from '@localizer/core';
import { countryName } from '@localizer/format';
import { transform } from '@localizer/transform'; 

const localizer = getLocalizer('en-US');
const transformedValueFormatter = transform(countryName, [upperCase]); 

console.log(localizer(transformedValueFormatter('FI'))); 

FINLAND

The second argument of transform() method is an array of transformers. These transformers are applied sequentially to modify the result, offering a flexible way to customize localized content.

String transformations

Converting to lower case

To convert a Localizable object to lower case, use the lowerCase transformer. This utility ensures that each character is converted to its locale-specific lower-case equivalent, providing accurate and consistent results across different languages.

const transformed = transform(loc`strING`, [lowerCase]);
console.log(localizer(transformer));

string

Converting to upper case

To convert a Localizable object to upper case, use the upperCase transformer. This utility ensures that each character is converted to its locale-specific upper-case equivalent, providing accurate and consistent results across different languages.

const transformed = transform(loc`strING`, [upperCase]);
console.log(localizer(transformer));

STRING

Converting to title case

To convert a Localizable object to title case, use the capitalize transformer. This utility ensures that the first character of the string is converted to its locale-specific upper-case equivalent, while the rest of the string remains unchanged. It provides accurate and consistent results across different languages, adhering to locale-aware rules.

const transformed = transform(loc`strING`, [capitalize]);
console.log(localizer(transformer));

StrING

Applying custom transformation

You can create custom string transformations using the apply transformer factory. This utility allows you to define a transformation function that modifies the localized output in any way you need. For example, you can wrap text in markdown-style bold formatting:

const bold = apply((text) => `**${text}**`);
const transformed = transform(loc`strING`, [bold]);
console.log(localizer(transformed));

**strING**

This approach provides flexibility for implementing custom transformations while maintaining compatibility with the library's localization features.

const bold = apply((text) => `**${text}**`);
const transformed = transform(loc`strING`, [bold]);
console.log(localizer(transformer));

**strING**

NOTE

Such transformations are not tied to any specific locale. For scenarios requiring locale-aware transformations, you can implement a custom transformer by adhering to the Transformer type. This allows you to define transformations that respect locale-specific rules and nuances, ensuring accurate and context-sensitive results.

const bold = (localizable) => loc`**${localizable}**`;
const transformed = transform(loc`strING`, [bold]);
console.log(localizer(transformer));

Locale Transformations

Unlike string transformations, locale transformations enable you to override the locale used during the localization process. These transformations are particularly useful when you need to ensure consistent formatting or behavior across different locales, regardless of the user's selected language or region.

Using primary locale

preview

This transformer enables the use of the primary language for a country instead of the provided locale. This can be particularly useful in scenarios where consistent data formatting is preferred, regardless of the selected spoken language.

const fiFI = getLocalizer('fi-FI');
const svFI = getLocalizer('sv-FI');

const localizedDate = date(new Date());

console.log(fiFI(localizedDate));
console.log(svFI(localizedDate));

3.7.2025
2025-07-03

In Finland, the standard localization for the Swedish language may lead to unexpected results for some users. The usePrimaryLocale transformer helps ensure consistency by applying the primary locale for the region, making the localized output more intuitive and contextually appropriate.

const fiFI = getLocalizer('fi-FI');
const svFI = getLocalizer('sv-FI');

const fixedDate = transform(date, [usePrimaryLocale]); 

const localizedDate = date(new Date()); 
const localizedDate = fixedDate(new Date()); 

console.log(fiFI(localizedDate));
console.log(svFI(localizedDate));

3.7.2025
3.7.2025