A tiny library that formats precise time differences as a vague/fuzzy time. Supports 10 languages.
- Why would I want that?
- What alternative libraries are there?
- How tiny is it?
- How do I install it?
- How do I use it?
- How do I build it?
- What license is it released under?
Displaying precise dates and times can give a website a formal and officious feel. Using fuzzy or vague time phrases like 'just now' or '3 days ago' can contribute to a much friendlier interface.
vagueTime.js provides a small, clean API for translating timestamps into those user-friendly phrases, heavily supported by unit tests. Vague time strings can be returned in English, German, French, Dutch, Danish, Japanese, Korean, Chinese or Brazilian Portuguese.
The library can be built with support for any combination of the supported languages. Single-language builds are typically around 4.3 kb unminified with comments, 1.3 kb minified or 0.7 kb minified + gzipped.
The largest build, containing all 10 supported languages, is 8.7 kb unminified with comments, 3.4 kb minified or 1.4 kb minified + gzipped.
If you're using npm:
npm install vague-time
Or if you just want the git repo:
git clone email@example.com:philbooth/vagueTime.js.git
If you're into other package managers, it is also available from Bower, Component and Jam.
If you are running in
or another CommonJS-style
vagueTime.js like so:
var vagueTime = require'vague-time';
It also the supports the AMD-style format preferred by Require.j
If you are
with an HTML
or neither of the above environments
the interface will be globally available
Please note that the default module contains all 10 supported languages. If you want to load a custom build, you must ensure that you reference that correct explicitly.
vagueTime.js exports a single public function,
which returns a vague time string
based on the argument(s) that you pass it.
The arguments are passed as properties on a single options object:
from: Timestamp or
Dateinstance denoting the origin point from which the vague time will be calculated. Defaults to
to: Timestamp or
Dateinstance denoting the target point to which the vague time will be calculated. Defaults to
units: String denoting the units that the
totimestamps are specified in. May be
's'for seconds or
'ms'for milliseconds. Defaults to
'ms'. This property has no effect when
Dateinstances rather than timestamps.
lang: String denoting the output language. May be
'zh'(Chinese. The default is set by the build options.
to is less than
the returned vague time will indicate
some point in the past.
to is greater than
it will indicate
some point in the future.
vagueTimegetfrom: 60to: 0units: 's'; // returns '1 minute ago'vagueTimegetfrom: 0to: 60units: 's'; // returns 'in 1 minute'vagueTimegetfrom: 7200to: 0units: 's'; // returns '2 hours ago'vagueTimegetfrom: 0to: 7200units: 's'lang: 'de'; // returns 'vor 2 Stunden'vagueTimegetfrom: 2015 0 3to: 2014 11 31lang: 'de'; // returns 'in 3 Tagen'vagueTimegetfrom: 0to: 259200units: 's'lang: 'fr'; // returns 'il y a 3 jours'vagueTimegetfrom: 2015 0 27to: 2014 11 31lang: 'fr'; // returns 'dans 4 semaines'
The build environment relies on
Assuming that you already have
Node.js and NPM set up,
you just need to run
to install all of the dependencies
as listed in
You can then lint the source module
with the command
npm run lint.
You can run the standard build process
with the command
npm run build
or run a custom build using the build script:
./build.js -l <comma-separated list of language codes> -d <default language code>
The unit tests are in
You can run them with the command
To run the tests in a web browser,