humanize-time-tool/README.md

A simple and lightweight Node.js library for human-friendly time formatting and localization.

````markdown
# humanize-time-tool

![npm version](https://img.shields.io/npm/v/humanize-time-tool.svg)  
![npm downloads](https://img.shields.io/npm/dm/humanize-time-tool.svg)  
![license](https://img.shields.io/npm/l/humanize-time-tool.svg?cacheBust=1)  

A simple and lightweight Node.js library for human-friendly time formatting with built-in localization (i18n) support.

## Features

- Format timestamps as "time ago" strings (e.g., "5 minutes ago")
- Supports 20+ languages with easy language switching
- Customizable and extendable translations  
- Lightweight and dependency-free  
- Automatic fallback to Swedish if translation is missing  
- Suitable for server-side rendering and client-side use

## Supported Languages

<!-- LANGUAGES_START -->
- ar - Arabic  
- be - Belarusian  
- bs - Bosnian  
- bg - Bulgarian  
- cs - Czech  
- da - Danish  
- de - German  
- el - Greek  
- en - English  
- es - Spanish  
- et - Estonian  
- fa - Persian  
- fi - Finnish  
- fr - French  
- he - Hebrew  
- hi - Hindi  
- hr - Croatian  
- hu - Hungarian  
- is - Icelandic  
- it - Italian  
- ja - Japanese  
- ko - Korean  
- lt - Lithuanian  
- lv - Latvian  
- nl - Dutch  
- no - Norwegian  
- pl - Polish  
- pt - Portuguese  
- ro - Romanian  
- ru - Russian  
- sk - Slovak  
- sl - Slovenian  
- sr - Serbian  
- sv - Swedish  
- th - Thai  
- tr - Turkish  
- uk - Ukrainian  
- vi - Vietnamese  
- zh - Chinese  
<!-- LANGUAGES_END -->

## Installation

```bash
npm install humanize-time-tool
````

## Usage

```js
import { timeAgo } from 'humanize-time-tool';

console.log(timeAgo(new Date(Date.now() - 5 * 60 * 1000), 'en')); // "5 minutes ago"
console.log(timeAgo('2025-01-01T00:00:00Z', 'sv'));              // "för några sekunder sedan" (example Swedish translation)

console.log(timeAgo(Date.now() - 3600 * 1000, 'en', { hour_one: 'an hour ago' })); // Custom override for one-hour string
```

## Language Middleware

This library provides a middleware function `languageMiddleware` to register and limit which languages are allowed (activated) at runtime.

You can use the middleware in your server (e.g., Express) to specify allowed languages with one of these options:

* `['*']` — allow **all available languages**
* `['sv', 'en']` — allow **only specific languages**, in this example Swedish and English

Example usage in Express:

```js
import express from 'express';
import { languageMiddleware } from 'humanize-time-tool';

const app = express();

// Allow only Swedish and English
app.use(languageMiddleware(['sv', 'en']));

// Or allow all languages
// app.use(languageMiddleware(['*']));
```

This approach ensures only the specified languages are registered and available via `getTranslations()` or `timeAgo()`.

## Important Notes

* **Translations are fully included inside the JavaScript code and loaded automatically.**
* There is **no need to load external translation files** or call `loadTranslations()` in normal usage.
* The `loadTranslations()` function remains exported only for advanced use cases like dynamically updating or overriding translations at runtime.

## API Reference

### `timeAgo(dateInput, lang = 'sv', customTranslations = {})`

Formats a given date into a localized "time ago" string.

* `dateInput`: Date object, ISO string, or timestamp
* `lang`: Language code (default `'sv'`)
* `customTranslations`: Optional object to override specific translation strings

Returns a string such as `"5 minutes ago"` or `"för 5 minuter sedan"`.

### `getTranslations(lang)`

Returns the translations object for the specified language if available; otherwise returns `undefined`.

### `loadTranslations()`

(Optional) Asynchronously loads translations from an external JSON file and merges them with built-in defaults.
Normally not needed since translations are included in the package.

## License

MIT

```