js-localizations

Cloudbeds JS Localization Utilities

A robust utility library to manage and retrieve localized information such as country names, currency formats, and date-time utilities, using ISO standards and internationalization libraries. This library is optimized for performance through caching and includes several modules to cover localization needs.

Features

• Country: Retrieve country names, states, and translations by country code.
• Datetime: Format dates, convert timezones, parse and display relative time.
• Currency: Format currency values, parse currency strings, adjust precision.
• Language: Access country flags, translate country names, and localize data.

---

Installation

Install the package using npm:

npm install @cloudbeds/js-localizations

---

Usage

Importing Features

Method 1: Named Imports

You can import individual functions as needed.

import { getCountryName } from "@cloudbeds/js-localizations";
import { formatCurrency } from "@cloudbeds/js-localizations";

Method 2: Full Module Import

import * as LocalizationUtils from "@cloudbeds/js-localizations";

---

Module Usage

Country

This module provides functions for country name retrieval, state listing, and country translations.

import { getCountryName, getStatesNameByCountry, getCountryFlag, getCountriesWithTranslations } from "@cloudbeds/js-localizations";

// Retrieve country name in a specific language
const countryName = getCountryName("US", "es"); // Returns "Estados Unidos"

// Fetch list of states for a country
const states = getStatesNameByCountry("US");

// Retrieve country and states information
const countryAndStates = getCountryAndStatesNames("US");

// Get a list of all country names
const countryList = getCountryList();

// Get the flag emoji for a country
const flag = getCountryFlag("US");

// Retrieve country names in multiple languages
const countries = getCountriesWithTranslations(["US", "FR"], "es");

Datetime

Includes utilities for formatting dates, handling timezones, and displaying relative time.

import { formatDate, timeAgo } from "@cloudbeds/js-localizations";

// Format a date
const formattedDate = formatDate(new Date(), "yyyy-MM-dd");

// Display relative time
const relativeTime = timeAgo(new Date("2024-01-01"));

// Parse a date string and format it
const parsedDate = parseAndFormatDate("2024-01-01T12:00:00Z", "yyyy-MM-dd");

Currency

Contains tools to format and parse currency values.

import { formatCurrency, parseCurrency } from "@cloudbeds/js-localizations";

// Format a value as currency
const currencyString = formatCurrency(1234.56, "USD");

// Parse a currency string back to a number
const value = parseCurrency("$1,234.56");

// Extract value from an HTML span
const valueFromHtml = getValueFromHtmlSpan("<span>$1234.56</span>");

// Check if the value is below one penny
const isSubPenny = isValueSubPenny(0.009);

// Round a value that is less than a penny
const roundedValue = roundBelowPenny(0.005);

Language

Registers language locales from JSON files for a list of language codes, returning the successfully registered codes. The function getLanguageOptions then creates an array of language options, where each entry includes a language code, its name (in the original language), and its international names in the provided locales.

import { getLanguageOptions } from "@cloudbeds/js-localizations";

const result = getLanguageOptions(['es', 'de']); // send the supported languages

---

API

Country

• getCountryName(code: string, lang: string): string
• getStatesNameByCountry(code: string): string[]
• searchCountryByField(field: string, value: string): Country

Datetime

• formatDate(date: Date, format: string): string
• timeAgo(date: Date): string
• formatInTimeZone(date: Date, timezone: string): string

Currency

• formatCurrency(value: number, currencyCode: string): string
• parseCurrency(value: string): number
• getPrecision(value: number): number

Language

• getLanguageOptions(languageCodes: string[]): Language[]

---

Configuration

The library uses caching to optimize repeated calls. Caching can be configured using sessionStorage on the frontend and Map in Node.js environments.

---

Tests

Run tests using Vitest:

npm run test