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:

``bash
npm install @cloudbeds/js-localizations
`

---

Usage

$3

#### Method 1: Named Imports
You can import individual functions as needed.

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

#### Method 2: Full Module Import

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

---

$3

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

`typescript
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.

`typescript
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.

`typescript
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("$1234.56");

// 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.

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

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

`

---

API

$3


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

$3

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

$3

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

$3

- 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:

`bash
npm run test
``