@nexim/localizer
Version:
Lightweight i18n utilities to handle translations, number formatting, date/time localization using native browser APIs.
187 lines (115 loc) • 8.25 kB
Markdown
[@nexim/localizer](../README.md) / Localizer
# Class: Localizer
Provides localization and internationalization functionality.
## Remarks
This class handles number formatting, text translation, date formatting,
and relative time calculations based on the specified locale.
## Constructors
### Constructor
> **new Localizer**(`options__`: `object`): `Localizer`
Creates a new instance of the Localizer class.
#### Parameters
| Parameter | Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `options__` | \{ `locale`: [`Locale`](../interfaces/Locale.md); `resource`: `null` \| `DictionaryReq`\<`any`\>; \} | Configuration options for localization |
| `options__.locale` | [`Locale`](../interfaces/Locale.md) | - |
| `options__.resource` | `null` \| `DictionaryReq`\<`any`\> | - |
#### Returns
`Localizer`
## Properties
| Property | Modifier | Type | Description |
| ------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| <a id="logger_"></a> `logger_` | `protected` | `AlwatrLogger` | - |
| <a id="numberformatter_"></a> `numberFormatter_` | `protected` | `NumberFormat` | **`Internal`** Number formatter instance for formatting numbers according to the locale. |
| <a id="unicodedigits_"></a> `unicodeDigits_` | `protected` | `UnicodeDigits` | **`Internal`** UnicodeDigits instance for converting numbers to locale-specific digits. |
| <a id="timeunits_"></a> `timeUnits_` | `static` | readonly \[\{ `label`: `"year"`; `seconds`: `31536000`; \}, \{ `label`: `"month"`; `seconds`: `2592000`; \}, \{ `label`: `"week"`; `seconds`: `604800`; \}, \{ `label`: `"day"`; `seconds`: `86400`; \}, \{ `label`: `"hour"`; `seconds`: `3600`; \}, \{ `label`: `"minute"`; `seconds`: `60`; \}, \{ `label`: `"second"`; `seconds`: `1`; \}\] | **`Internal`** Time units used for relative time calculations. |
## Methods
### message()
> **message**(`key`: `string`): `string`
Retrieves a localized message by key from the resource dictionary.
#### Parameters
| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------- |
| `key` | `string` | The key to lookup in the resource dictionary |
#### Returns
`string`
The localized message string
#### Remarks
- Returns "\{key\}" if the key is not found in the dictionary
- Returns an empty string if the key is null or undefined
#### Example
```typescript
const localizer = new Localizer({...});
console.log(localizer.message('hello_world')); // "Hello world!"
console.log(localizer.message('missing_key')); // "{missing_key}"
```
---
### number()
> **number**(`number?`: `null` \| `number`, `decimal?`: `number`): `string`
Formats a number according to the current locale settings.
#### Parameters
| Parameter | Type | Default value | Description |
| ---------- | ------------------ | ------------- | ------------------------------------- |
| `number?` | `null` \| `number` | `undefined` | The number to format |
| `decimal?` | `number` | `2` | Number of decimal places (default: 2) |
#### Returns
`string`
Formatted number string using locale-specific formatting
#### Example
```typescript
const localizer = new Localizer({...});
console.log(localizer.number(1234.567)); // "1,234.57"
console.log(localizer.number(1234.567, 1)); // "1,234.6"
```
---
### relativeTime()
> **relativeTime**(`date`: `number` \| `Date`, `from`: `number` \| `Date`, `options`: `RelativeTimeFormatOptions`): `string`
Creates a relative time string comparing two dates.
#### Parameters
| Parameter | Type | Description |
| --------- | --------------------------- | -------------------------------------------------------- |
| `date` | `number` \| `Date` | The date to compare (as Date object or timestamp) |
| `from` | `number` \| `Date` | Reference date for comparison (defaults to current time) |
| `options` | `RelativeTimeFormatOptions` | Formatting options for relative time |
#### Returns
`string`
Localized relative time string
#### Example
```typescript
const localizer = new Localizer({...});
const date = new Date(Date.now() - 3600000); // 1 hour ago
console.log(localizer.relativeTime(date)); // "1 hour ago"
```
---
### replaceNumber()
> **replaceNumber**(`str`: `string`): `string`
Replaces all numeric digits in a string with their locale-specific Unicode equivalents.
#### Parameters
| Parameter | Type | Description |
| --------- | -------- | ---------------------------------------------- |
| `str` | `string` | The input string containing numbers to replace |
#### Returns
`string`
String with numbers converted to locale-specific digits
#### Example
```typescript
const localizer = new Localizer({locale: {code: 'fa-IR', language: 'fa'}, ...});
console.log(localizer.replaceNumber('123')); // '۱۲۳'
```
---
### time()
> **time**(`date`: `number` \| `Date`, `options?`: `DateTimeFormatOptions`): `string`
Formats a date according to the current locale settings.
#### Parameters
| Parameter | Type | Description |
| ---------- | ----------------------- | ----------------------------------------------------- |
| `date` | `number` \| `Date` | Date to format (as Date object or timestamp) |
| `options?` | `DateTimeFormatOptions` | Intl.DateTimeFormatOptions for customizing the output |
#### Returns
`string`
Localized date string
#### Example
```typescript
const localizer = new Localizer({...});
console.log(localizer.time(new Date())); // "4/21/2025"
```