Relative time/dates

[zbraniecki]

There are two major areas where relative time/date formatting could use standardization:

1. Relative time representation

Good example are timers - representing time like "31 hours, 15 minutes and 23 seconds" as "31:15:23".

1. pretty relative date/time.
   A lot of web apps humanize relative date and time with messages like:

• a few seconds ago
• less than a minute ago
• one hour ago
• in one hour
• yesterday
• last week
• in 2 days

All of those patterns are available in CLDR and it would enable web authors to provide better user interfaces if we could incorporate this kind of formatting either into DateTimeFormat or into a separate RelativeDateTimeFormat.

[caridy]

@zbraniecki, now that we are ready to start working on the 3rd edition (using this repo), I plan to champion the relative time feature based on the initial work that we did on https://github.com/yahoo/intl-relativeformat. Do you want to help?

[zbraniecki]

absolutely. We're currently using a very nasty hack for that[1] and I'd love to see some better, possibly CLDR based, API for that.
I'll be definitely interested in shimming whatever we come up with for Firefox and Firefox OS which should give us some ability to test how it works early on.

[1] https://github.com/mozilla-b2g/gaia/blob/19696d5db8e7e078204b15597b9d01c788e5f04f/shared/js/l10n_date.js#L132

[caridy]

I could not find "a few minutes ago" data in CLDR, nor the "one", "less than", etc...

Here is the initial spec: https://github.com/caridy/intl-relative-time-spec, and here is the HTML version https://rawgit.com/caridy/intl-relative-time-spec/master/index.html

[zbraniecki]

That looks awesome! Thanks @caridy

I'll play with this against our use cases more, but first thing I miss here is pure duration. You have "X ago" and "in X", but you don't have "X". Examples:

• "1 month" "1m"
• "26 hours" / "26h"
• "5 seconds", "5 sec", "5s"
  etc.

[zbraniecki]

Hmm, the more I think about this the more I feel like there's a direct overlap area between three proposals:

• this one
• [Proposal] Compact Decimal Format to abbreviate large numbers #37 - abbreviate numbers
• Unit formatting API #32 - Unit formatting
• NumberFormat

First of all, there are three modes - future (in 5 minutes), past (5 minutes ago) and "neutral" (5 minutes).

Second, there may be specific maximum unit to show - "50000" meters is "50km", and "5000000" meters is "5000km". Same for "12000000" minutes being "50000h".
Third, on top of maximum number, there should be an option what to do with the modulo - 125 minutes may be "2 hours" or "2 hours and 5 minutes".
The maximum number may actually be a float - "160" minutes may be "2.5 hours" or "2 hours and 30 minutes", same for "2.5 miles", "2.5 GB" etc.
And lastly, all of that should be formatter by the NumberFormat.

I think that however incremental we want to take it, we should design the API to be forward compatible to allow ourselves to add the next bits later.

[caridy]

1. I haven't see the data for the neutral form of time in cldr, did you?
2. best fit vs specific unit should provide the flexibility to select the right form. If we have the concrete data in cldr I can look into expanding this proposal to cover other scales.
3. if you look into the draft, I did use %NumberFormat% to format the numeric value before replacing the cldr {0} value in the pluralization forms.

[srl295]

one day ago see CLDR UTS #35: Part 4 (Dates), #3 Calendar Fields

[rxaviers]

"neutral" (5 minutes).
I haven't see the data for the neutral form of time in cldr, did you?

@caridy @zbraniecki the "neutral form" (or sometimes referred to as absolute time) you are talking about is called "unit" - #37 :) as you may already figured out.

[zbraniecki]

@rxaviers - So #37 is about abbreviation, but #32 is about units. Did you mean #32? Should we keep it separate from this API? I feel like they overlap a lot and I feel tempted to try to address future/past/absolute in one API, but I don't have much experience designing APIs like that so I can imagine that there may be an obvious reason not to.

[zbraniecki]

@caridy - in CLDR the "absolute time" is part of Duration Patterns - http://unicode.org/repos/cldr/trunk/specs/ldml/tr35-general.html#durationUnit

I'm talking about things like:
2000s -> "00:33:20.00" (0 hours, 33 minutes and 20 sec)

Is it part of your plan for this API?

[caridy]

@zbraniecki that's a good question, we need some bikeshedding on this topic I guess. Obviously that fits into the relative time paradigm since you have to use %Date.now% to compute the lapse. The other part of the equation is to figure whether or not %Date.now% is a default value of a configuration option, allowing users to provide the pivot, just like we do in intl-relativeformat, that probably makes more sense for the absolute, but it is proven to be useful for past and future as well.

[zbraniecki]

Yeah, I mocked it today for our code in Clock/Timer/Stopwatch app and I used something like that:

var formatter = mozIntl.DurationFormat(navigator.languages, {
  hour: true,
  minute: true,
  second: true
  //millisecond: true
});
formatter.format(milliseconds);

I can see it becoming a separate formatter or becoming part of RelativeFormat.

[rxaviers]

@rxaviers - So #37 is about abbreviation, but #32 is about units. Did you mean #32?

Whoops, yeap I meant #32 you're correct.

Should we keep it separate from this API? I feel like they overlap a lot and I feel tempted to try to address future/past/absolute in one API, but I don't have much experience designing APIs like that so I can imagine that there may be an obvious reason not to.

I agree with you that these three forms overlap. But, I'm not too convinced RelativeTimeFormat should include an absolute form. Because, FormatUnit can be used for that purpose.

• 2000s could be formatted as "00:33:20.00" (0 hours, 33 minutes and 20 sec) as you have mentioned. Similarly, other units too, e.g.:
• 65in or 5.5 feet could be formatted as 5'6", or 5 feet and 6 inches.
• 168oz or 10.5lb could be formatted as 10 pounds and 8 ounces.
• 182cm could be formatted as 1m and 82 cm.

I see the above as FormatUnit plus an abbreviation modifier. It just happens that it's easier to think of abbreviating 1000 into 1K, or $1,000,000 into $1M because they are powers of 10. The above unit abbreviations require that the abbreviation logic know how to convert units that are not powers of 10, including time.

PS: Eventually, there might be an API that gracefully unifies all the three (relative time formatting, unit formatting, and abbreviation). So far, I think FormatUnit is a foundation similar to what FormatPlural is for MessageFormat (or possible a different more sophisticated API for formatting messages).

[zbraniecki]

sounds great!

[caridy]

@rxaviers that's the same conclusion we arrived yesterday when discussing this issue. RelativeTimeFormat should focus on the timeline, producing past and future, relying on %Date.now% (or a provided time frame), and we can get absolute time as part of the unit api.

[rxaviers]

;)

[zbraniecki]

I separated discussion about DurationFormat to #47 since I'm not sure how it may fit into this API.

[caridy]

update: we are cooking the proposal for the next meeting in two weeks.

[zbraniecki]

Heads up, this has been advanced to Stage 0 as of today.

[zbraniecki]

This proposal has been advanced to Stage 1 as of today.

[zbraniecki]

Today I submitted the patch proposal for an internal Gecko API mozIntl.RelativeTimeFormat which is based on the ECMA402 - https://bugzilla.mozilla.org/show_bug.cgi?id=1270140

I also submitted suggestions for the spec changes based on my implementation experience.
They're filed as issues at https://github.com/caridy/intl-relative-time-spec

[zbraniecki]

Intl.RelativeTimeFormat proposal has reached Stage 3 at today's TC39 meeting!

[littledan]

I don't remember that happening... I thought we just go to Stage 2, and we had to go back and make the changes that were suggested in the previous meeting.

[zbraniecki]

My bad. The notes were confusing. I corrected the stages2 - RTF is in Stage 2.

[zbraniecki]

In other news, RTF landed behind the flag in SpiderMonkey - https://bugzilla.mozilla.org/show_bug.cgi?id=1270140

[jungshik]

Another minor spec issue: I'm not sure if keying off of the result of PluralRules is enough. For example, in German, there's no special "dual" PluralRules form; however, there is a special word for the day before yesterday and the day after tomorrow, as in this example. Should we put an extra Get for the exact number, before "falling back" to getting the plural category? I think this would match the structure of CLDR.

I guess there are more languages like German. Korean also has special words for the day after tomorrow and the day before yesterday. Actually, it has special words for 3 days ago and 3 days from today.

[jungshik]

As with unit format, I wonder what the plan is for 'more than one units'.

3 days and 5 hours ago
5 hours and 25 minutes ago
In 3 minutes and 40 seconds

[caridy]

3 days and 5 hours ago
5 hours and 25 minutes ago
In 3 minutes and 40 seconds

we can support those in the future by providing an option for more accuracy.

[catamphetamine]

Just dropping by to say that I implemented a polyfill for the current Intl.RelativeTimeFormat spec in case anyone finds it useful.
https://github.com/catamphetamine/relative-time-format

[zbraniecki]

Intl.RelativeTimeFormat achieved Stage 3 as of today!

[jungshik]

Perform ! CreateDataPropertyOrThrow(nfOptions, "minimumIntegerDigits", 2

The spec has the above provision. I wonder why minIntDigits is set to 2. That leads to zero-padding likes '04 days ago', 'In 05 hours' instead of '4 days ago' / 'In 5 hours'.

[FrankYFTang]

Should we just closed this issue now since we already have Intl.RelativeTimeFormat in Stage 3?

[sffc]

We can close this when the corresponding proposal reaches Stage 4 and is merged. This issue has the tag "active proposal".

[anba]

Intl.RelativeTimeFormat has been merged.

[sffc]

Thanks @anba; this proposal is now Stage 4 and merged. Closing as Fixed