humanize-duration

Convert millisecond durations to English and many other languages.

Humanize Duration

I have the time in milliseconds and I want it to become "30 minutes" or "3 days, 1 hour". Enter Humanize Duration!

This package is available as humanize-duration on npm and Bower. You can also include the JavaScript file in the browser.

In the browser:

<script src="humanize-duration.js"></script>
<script>
humanizeDuration(12000)
</script> 

In Node (or Browserify or Webpack or anywhere with CommonJS):

var humanizeDuration = require("humanize-duration")
humanizeDuration(12000)

By default, Humanize Duration will humanize down to the second, and will return a decimal for the smallest unit. It will humanize in English by default.

humanizeDuration(3000)      // "3 seconds" 
humanizeDuration(2015)      // "2.25 seconds" 
humanizeDuration(97320000)  // "1 day, 3 hours, 2 minutes" 

You can change the settings by passing options as the second argument:

humanizeDuration(3000, { language: "es" })  // "3 segundos" 
humanizeDuration(5000, { language: "ko" })  // "5 초" 
 
humanizeDuration(22140000, { delimiter: " and " })  // "6 hours and 9 minutes" 
humanizeDuration(22140000, { delimiter: "--" })     // "6 hours--9 minutes" 
 
humanizeDuration(260040000, { spacer: " whole " })  // "3 whole days, 14 whole minutes" 
humanizeDuration(260040000, { spacer: "" })         // "3days, 14minutes" 
 
humanizeDuration(1000000000000)                  // 31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds 
humanizeDuration(1000000000000, { largest: 2 })  // 31 years, 8 month 
 
humanizeDuration(3600000, { units: ["h"] })       // "1 hour" 
humanizeDuration(3600000, { units: ["m"] })       // "60 minutes" 
humanizeDuration(3600000, { units: ["d", "h"] })  // "1 hour" 
 
humanizeDuration(1200)                   // "1.2 seconds" 
humanizeDuration(1200, { round: true })  // "1 second" 
humanizeDuration(1600, { round: true })  // "2 seconds" 
 
humanizeDuration(1200)                          // "1.2 seconds" 
humanizeDuration(1200, { decimal: ' point ' })  // "1 point 2 seconds" 
 
humanizeDuration(400)    // "0.4 seconds" 
humanizeDuration(400, {  // "1 year, 1 month, 5 days" 
  unitMeasures: {
    y: 365,
    mo: 30,
    w: 7,
    d: 1
  }
})
 
humanizeDuration(3600000, {
  language: "es",
  units: ["m"]
})
// "60 minutos" 

If you find yourself setting same options over and over again, you can create a humanizer that changes the defaults, which you can still override later.

var spanishHumanizer = humanizeDuration.humanizer({
  language: "es",
  units: ["y", "mo", "d"]
})
 
spanishHumanizer(71177400000)  // "2 años, 3 meses, 2 días" 
spanishHumanizer(71177400000, { units: ["d", "h"] })  // "823 días, 19.5 horas" 

You can also add new languages to humanizers. For example:

var shortEnglishHumanizer = humanizeDuration.humanizer({
  language: "shortEn",
  languages: {
    shortEn: {
      yfunction() { return "y"; },
      mofunction() { return "mo"; },
      wfunction() { return "w"; },
      dfunction() { return "d"; },
      hfunction() { return "h"; },
      mfunction() { return "m"; },
      sfunction() { return "s"; },
      msfunction() { return "ms"; },
    }
  }
})
 
shortEnglishHumanizer(15600000)  // "4 h, 20 m" 

You can also add languages after initializing:

var humanizer = humanizeDuration.humanizer()
 
humanizer.languages.shortEn = {
  yfunction(c) { return c + "y"; },
  // ... 

Internally, the main humanizeDuration function is just a wrapper around a humanizer.

Humanize Duration supports the following languages:

Language Code
Arabic ar
Catalan ca
Chinese, simplified zh_CN
Chinese, traditional zh_TW
Czech cs
Danish da
Dutch nl
English en
Finnish fi
French fr
German de
Greek gr
Hungarian hu
Italian it
Japanese ja
Korean ko
Norwegian no
Polish pl
Portuguese pt
Russian ru
Spanish es
Swedish sv
Turkish tr
Ukrainian uk

For a list of supported languages, you can use the getSupportedLanguages function.

humanizeDuration.getSupportedLanguages()
// ["ar", "ca", "da", "de" ...] 

This function won't return any new languages you define; it will only return the defaults supported by the library.

Lovingly made by Evan Hahn with help from:

Licensed under the permissive Unlicense. Enjoy!