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 in npm and Bower. You can also include the JavaScript 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(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:

LanguageCode
Arabicar
Catalanca
Chinese, simplifiedzh_CN
Chinese, traditionalzh_TW
Danishda
Dutchnl
Englishen
Frenchfr
Germande
Hungarianhu
Italianit
Japaneseja
Koreanko
Norwegianno
Polishpl
Portuguesept
Russianru
Spanishes
Swedishsv
Turkishtr
Ukrainianuk

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 langauges you define; it will only return the defaults supported by the library.

Lovingly made by Evan Hahn with help from:

Licensed under the WTFPL, so you can do whatever you want. Enjoy!