Enhanced MS supports multiple languages out of the box, making it easy to display durations in your users’ native language. This guide shows you how to use localization features.
Creating localized instances
Use createMs to create an instance configured for a specific language:
English
German
Spanish
French
import { createMs } from 'enhanced-ms';
const ms = createMs({ language: 'en' });
ms(90061);
// "1 minute 30 seconds"
ms('1 hour 30 minutes');
// 5400000
import { createMs } from 'enhanced-ms';
const ms = createMs({ language: 'de' });
ms(90061);
// "1 Minute 30 Sekunden"
ms('1 Stunde 30 Minuten');
// 5400000
import { createMs } from 'enhanced-ms';
const ms = createMs({ language: 'es' });
ms(90061);
// "1 minuto 30 segundos"
ms('1 hora 30 minutos');
// 5400000
import { createMs } from 'enhanced-ms';
const ms = createMs({ language: 'fr' });
ms(90061);
// "1 minute 30 secondes"
ms('1 heure 30 minutes');
// 5400000
The default import from enhanced-ms uses English. Always use createMs when you need a different language.
Supported languages
Enhanced MS currently supports the following languages:
| Language | Code | Example Output |
|---|
| English | en | ”1 minute 30 seconds” |
| German | de | ”1 Minute 30 Sekunden” |
| Spanish | es | ”1 minuto 30 segundos” |
| French | fr | ”1 minute 30 secondes” |
| Italian | it | ”1 minuto 30 secondi” |
| Dutch | nl | ”1 minuut 30 seconden” |
| Russian | ru | ”1 минута 30 секунд” |
| Polish | pl | ”1 minuta 30 sekund” |
| Czech | cs | ”1 minuta 30 sekund” |
| Chinese (Simplified) | zh-CN | ”1分钟30秒” |
| Māori | mi | ”1 meneti 30 hēkona” |
Language-specific abbreviations
Each language has its own set of abbreviations:
import { createMs } from 'enhanced-ms';
// English abbreviations
const enMs = createMs({ language: 'en' });
enMs(90061, { useAbbreviations: true });
// "1m 30s"
// German abbreviations
const deMs = createMs({ language: 'de' });
deMs(90061, { useAbbreviations: true });
// "1Min. 30Sek."
// Spanish abbreviations
const esMs = createMs({ language: 'es' });
esMs(90061, { useAbbreviations: true });
// "1m 30s"
const ms = createMs({ language: 'de' });
ms('1 Stunde');
// 3600000
ms('30 Sekunden');
// 30000
ms('2 Tage 3 Stunden');
// 183600000
// Also accepts abbreviations
ms('1Std. 30Min.');
// 5400000
const ms = createMs({ language: 'ru' });
ms('1 час');
// 3600000
ms('30 секунд');
// 30000
ms('2 дня 3 часа');
// 183600000
const ms = createMs({ language: 'zh-CN' });
ms('1小时');
// 3600000
ms('30秒');
// 30000
ms('2天3小时');
// 183600000
Multi-language applications
For applications that support multiple languages, create instances for each language you need:
import { createMs } from 'enhanced-ms';
const formatters = {
en: createMs({ language: 'en' }),
de: createMs({ language: 'de' }),
es: createMs({ language: 'es' }),
fr: createMs({ language: 'fr' })
};
function formatDuration(milliseconds: number, locale: string) {
const ms = formatters[locale] || formatters.en;
return ms(milliseconds);
}
formatDuration(90061, 'en');
// "1 minute 30 seconds"
formatDuration(90061, 'de');
// "1 Minute 30 Sekunden"
formatDuration(90061, 'es');
// "1 minuto 30 segundos"
const ms = createMs({
language: 'de',
formatOptions: {
useAbbreviations: true,
unitLimit: 2
}
});
ms(90061);
// "1Min. 30Sek."
ms(90061000);
// "1T. 1Std."
// Override defaults for specific calls
ms(90061000, { unitLimit: 3 });
// "1T. 1Std. 1Min."
Set default options on the instance to avoid repeating the same options in every call.
Using presets with localization
All formatting presets work with any language:
const deMs = createMs({ language: 'de' });
deMs(90061, 'short');
// "1Min. 30Sek."
deMs(90061, 'colonNotation');
// "01:30"
deMs(10.100100100, 'fullPrecision');
// "10 Millisekunden 100 Mikrosekunden 100 Nanosekunden"
Custom language definitions
If your language isn’t supported, you can provide a custom language definition:
import { createMs } from 'enhanced-ms';
import type { LanguageDefinition } from 'enhanced-ms';
const customLanguage: LanguageDefinition = {
decimal: '.',
and: 'and',
units: {
second: {
name: (count) => count === 1 ? 'second' : 'seconds',
abbreviation: 's',
matches: ['second', 'seconds', 's', 'sec']
},
minute: {
name: (count) => count === 1 ? 'minute' : 'minutes',
abbreviation: 'm',
matches: ['minute', 'minutes', 'm', 'min']
},
// ... define other units
}
};
const ms = createMs({ language: customLanguage });
Custom language definitions must include all time units from nanoseconds to millennia. See the source code for complete examples. // German uses commas as decimal separators
const deMs = createMs({ language: 'de' });
deMs(1500.5, { includeMs: true });
// "1 Sekunde 500,5 Millisekunden"
// English uses periods
const enMs = createMs({ language: 'en' });
enMs(1500.5, { includeMs: true });
// "1 second 500.5 milliseconds"
Contributing new languages
You can help expand language support by contributing new language definitions to the Enhanced MS repository. Each language file defines:
- Decimal separator
- Conjunction word (like “and”)
- Unit names (singular and plural)
- Abbreviations
- Parsing patterns
See existing language files in the src/languages directory for examples.