tc39 / proposal-intl-relative-time Goto Github PK

For example, in FormatRelativeTimeToParts when constructing the result object.

In other formatters the value is always optional...

This is related to #4, and we should make a decision as soon as possible because this will affect various open issues.

When discussing the RelativeTimeFormat formatToParts method in the April 18th ICU-TC call, we agreed that the underlying ICU API would break up the inner number format into parts (in addition to exposing the entire number range). The current specification draft exposes just the range of the whole number. Would it be useful to have this level of detail in JavaScript as well? For example, this could come up in examples like, "in 1,234 days" or "1.5 seconds ago". Currently, the substrings "1234" or "1.5" are represented as a single part.

For example, the rendered spec text includes a default unit ("second"), whereas the spec source does not.

Maybe we should also keep the rendering on gh-pages, so it can be updated with a PR rather than going to that externally hosted page.

This prohibition would match modern practice, e.g., in PluralRules. However, omitting new is currently allowed.

In the current spec language quarters will never be selected by the GetBestMatchUnit because they overlap months.

I suggest that we remove it from the best fit scenario, and leave it only for manual selection with {unit: 'quarter'}.

1.3.4 Plural Form Functions, FormatRelativeTime states:

1. Let units be ComputeTimeUnits(ms).
   8a. Let unit be GetBestMatchUnit(units).

Currently, ComputerTimeUnits returns units that may have negative values, and GetBestMatchUnit only checks if the unit value is smaller than a constant.

That makes the algorithm not work for "past" values.

Seems like at the moment the spec does not lowercase the unit names, so code like this will throw:

let rtf = new Intl.RelativeTimeFormat();
rtf.format(1, "Second");

Do we want it to throw or do we want to lowercase it?

ICU provides two functions for formatting relative date: text and numeric - the difference is that in text mode it attempts to use human readable terms like yesterday and last week instead of numeric 1 day ago and 1 week ago.

I'd like to suggest adding this in form of type option:

let rtf = new Intl.RelativeTimeFormat('en-US', {
  type: 'text'
});
rtf.format(new Date() - 1000 * 60 * 60 * 24); // 'yesterday'


let rtf2 = new Intl.RelativeTimeFormat('en-US', {
  type: 'numeric'
});
rtf2.format(new Date() - 1000 * 60 * 60 * 24); // '1 day ago'

I'd suggest the text value to be the default.

Current version of the spec specifies two relevant extension keys:

 The value of the [[RelevantExtensionKeys]] internal slot is ["rt", "pr"].
Note 1 Unicode Technical Standard 35 describes three locale extension keys that are relevant to relative time formatting, "rt" for relative time, and "pr" language plural rules to choose the proper relative time pattern. 

yet TR35 does not have either of those:

http://www.unicode.org/reports/tr35/#Locale_Extension_Key_and_Type_Data

Should we remove them?

Hello.
I've been developing an implementation of a similar library based on CLDR some time ago.
https://github.com/catamphetamine/javascript-time-ago
That would be good if browsers finally incorporate this feature, still I guess I could transform my library into a polyfill compatible with your spec (once it's approved by the committee) for older browsers (iOS, Android).

I also found that things like yesterday and last year don't really work and I replaced them manually with 1 day ago and 1 year ago.
That's something you may find reasonable.

E.g., "days", not "day". See temporal which uses this convention. cc @maggiepint . This issue was raised at the July 2017 TC39 meeting.

This is a pretty basic feature that's missing. Should we add it into the [[Units]] field, as @rxaviers suggested? I don't think it should overlap as CLDR stores them in the same place.

https://github.com/tc39/ecma402/blob/master/README.md does not have 'Interval format'. So, I guess it's not on the table, yet.

This is a place holder for IntervalFormat. I'll add more details later.

For now, briefly what this API would do is to format an interval with the minimum redundancy given two points in time and a "pattern" (out of a fixed list of patterns).

For instance, given 2016-04-05 and 2016-04-07 and "YMD", the formatted result can be "April 5 - 7, 2016". For 2017-05-12 and 2017-07-04, the result can be "May 12 - July 4, 2017".

One item we do not have covered for the relativetime is compound units.

For typical UnitFormat+ListFormat it's easy - "5 hours, 35 minutes" is:

let lf = new Intl.ListFormat(locales, { type: "unit" });
let uf = new Intl.UnitFormat(locales);
lf.format([uf.format(5, "hour"), uf.format(35, "minute")]); // "5 hours, 35 minutes"

but that doesn't translate to RelativeTimeFormat:

let lf = new Intl.ListFormat(locales, { type: "unit" });
let rtf = new Intl.RelativeTimeFormat(locales);
lf.format([rtf.format(5, "hour"), rtf.format(35, "minute")]); // "in 5 hours, in 35 minutes"

InitializeRelativeTimeFormat has

Let localeData be %RelativeTimeFormat%.[[LocaleData]].
Let dataLocaleData be Get(localeData, dataLocale).
Let fields be Get(dataLocaleData, "fields").
Assert: fields is an object (see 1.3.3).
Set relativeTimeFormat.[[Fields]] to fields.

and relativeTimeFormat.[[Fields]] is later used, expecting that it has "second", "minute", "hour", … properties. However, http://tc39.github.io/proposal-intl-relative-time/#sec-Intl.RelativeTimeFormat-internal-slots claims

[[LocaleData]][Locale] has ordinary data properties "second", "minute", "hour", "day", "week", "month", "quarter" and "year".

without the intermediary fields object.

When the Intl.RelativeTimeFormat.prototype.format is called with an optional argument value, the following steps are taken:

When the Intl.RelativeTimeFormat.prototype.formatToParts is called with an optional argument value, the following steps are taken:

Both of these methods have two required arguments, rather than a single optional one.

It seems to just be passed into the underlying PartitionRelativeTimePattern, where an assertion will fail, but I don't see a proper cast.

CLDR and ICU provide as part of the RelativeDateTimeFormatter API an option to format time together with the date to produce strings like tomorrow at 3 pm or today at 3:45 pm.

Since we pass Date object as parameter already, all we really have to do is enable formatting of that.

My suggestion is to add hour, minute, second and hourCycle as options for RelativeTimeFormat.

Example:

let rtf = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric'
});

rtf.format(new Date() + 1000 * 60 * 60 * 24); // 'tomorrow at 3 pm'

let rtf = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric'
});

rtf.format(new Date() + 1000 * 60 * 60 * 24); // 'tomorrow at 3:45 pm'

by default those options would be undefined and no date+time formatting would happen.

I suggest that we keep this idea for second revision of the API, but wanted to propose it already to put it in scope of any API conversations.

There's been a lot written about RelativeTimeFormat, but it's scattered in a few different places. We should collect everything in a single README. The explainer should get at the main points of motivation for this design, including:

• Why this is the right level of abstraction
• Why did we make the main API choices that we made
• Why is this in terms of numbers, rather than dates/duration

The current spec text is a little excessively complicated; since we don't expose the pattern, and it's just a CLDR artifact, and since it's always used pretty simply here, I don't think we have to write the spec in those terms.

The current draft in 1.3.4 'GetBestMatchUnit' specifies:

1. If units.[[day]] is less than 26, return "day".

That in result means that 2 weeks will be displayed as "14 days".

I believe it would be useful to switch it to:

1. If units.[[day]] is less than 7, return "day".

Currently, the spec is considering "all" units possible when trying to determine the correct one - seconds, minutes, hours, days, weeks, months, quarters, years.

We still have more units to consider like "last Tuesday", and I can see users wanting to skip "quarters" or calculate only up to days, so - seconds, minutes, hours, normally, but nothing above days (so "4500 days ago").

It seems like a simple solution would be to allow people to pass the list of units to consider:

let x = new Intl.RelativeTimeFormat(locales, {
  unit: 'best fit',
  units: ['second', 'minute', 'hour', 'day']
});

Then, if you want to add weekdays or quarters, you'd just list it as one of the units.

Does it sound realistic?

Ref: #29 (comment)

Same issue as we had with PluralRules tc39/proposal-intl-plural-rules#29

In English, most style guides agree that integers in the range [1, 9] should be written as words (e.g. "in five minutes" as opposed to "in 5 minutes"). The same concept also exists in other languages; in German, this range is commonly said to be [1, 12].

In order to achieve this, are users supposed to formatToParts and use a library of their choice to write out the words based on custom rule sets? Is it maybe worth incorporating this behavior into the Intl API?

Right now, it's pretty implicit, just based on look at what the pattern of Get() is.

Appointed reviewers:

• Maggie Pint (@maggiepint)
• Mathias Bynens (@mathiasbynens)

In #9, a new option was added to RelativeTimeFormat: setting type to numeric or text. Some hesitations about naming were expressed in #9 (comment) ; @caridy has also expressed concern offline. Let's think harder about the right name here and brainstorm alternatives.

The ICU interface for getting at these times exposes strings like "yesterday" through a separate UDAT_ABSOLUTE_DAY unit. On the other hand, if you make an ordinary UDAT_RELATIVE_DAYS query for -1 days, you'll get "1 day ago". A couple questions about this:

• The current spec text says, first get the PluralRules, then select the template based on the PluralRules and direction, then fill it in. However, this would not allow getting something like "anteayer" (the day before yesterday) in Spanish because Spanish has no dual category; further, in English, it seems like a natural template to select would be "{0} day ago", rather than "yesterday". Do we want to use the ABSOLUTE version when available, falling back to the RELATIVE one only when appropriate?
• Are there any applications that would want to render as "1 day ago", or would really everybody want to render as "yesterday"? If so, maybe we should introduce separate "text" vs "numeric" modes, where "text" mode would use ABSOLUTE where applicable and fall back to RELATIVE if needed, and "numeric" would just start with RELATIVE. But something I don't understand is, does anyone want "numeric"?

Add calendar option, which follows the selected language and can be overridden manually, to handle non-Gregorian calendars relative times, e.g., "13 months ago" for Chinese calendar.

This needs to be properly defined...

For context, see #6.

It seems like the current spec text will always use type: "number". However, I would've expected the type to be the unit that the user requested, e.g, "hour". What was the intention here?

In InitializeRelativeTimeFormat, we have:

22. Let nfOptions be ObjectCreate(%ObjectPrototype%).

and

27. Let prOptions be ObjectCreate(%ObjectPrototype%).

If we could instead change these to ObjectCreate(null), that would reduce observable behavior that the engine could optimize out.

After reading this bugzilla thread I have a worry. Just a thought from the peanut gallery: it's not obvious to me that a Date + duration is the best input to get "tomorrow" out of. Wouldn't it be clearer to take two Dates?

(Edit: rewriting this paragraph) In the current proposal, how exactly is the math going to work? The easiest way for me to ask this is to point to Luxon's documentation: https://moment.github.io/luxon/docs/manual/math.html#calendar-math-vs-time-math. E.g. is 24 hours different than 1 day? How about 1 year vs 6 months 365 days? In what order do multiple units get added?

Luxon spends a lot of code and documentation sorting out how all that works and I know from supporting Moment that these issues come up all the time. It's not just that you'd have to do the math; it's that you'd need to commit to a very specific way of doing it, which sounds like something a built-in API would rather not do. Worse, if I wanted to do the math differently, I wouldn't be able to use the API, because I can't pass it the date I want to end up on.

What would be more clear and flexible would be telling me what one date is called relative to some other date, i.e. it's my job to do the math and hand the API both endpoints. I recognize this requires a very different API from what the non-anchored version does, which is essentially formatting durations. But it really does seem different. Of course, you have to do some math in any case, but the right answer to that math is way less ambiguous.

Current spec in 1.3.4 'FormatRelativeTime' states:

1. If v is between -1 (inclusive) and 1 (inclusive), then

while some languages provide -2,2:
http://www.unicode.org/cldr/charts/28/summary/pl.html#1531

I believe it should state:

1. If v is between -2 (inclusive) and 2 (inclusive), then

1.4.2 Intl.RelativeTimeFormat.prototype[ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "Object".

Why? What is even the point of having the property if you're going to make it say "Object"?

Names are currently "long", "short" and "narrow". Why not medium in the middle? Where do they come from? This was raised at the July 2017 TC39 meeting. (cc @msaboff)

We decided to not include any bestFit algorithm in the first iteration of the RelativeTimeFormat API and instead we expect the client libraries like momentjs and others to add them on top.

I'm working currently on such higher-level wrapper and I encountered an interesting API design dilemma that I'd like to get a recommendation for.

When we designed the core formatters for the Intl API, we pushed all resolving pieces into the object constructors. That has two nice benefits - it does the computations and data retrieving at object creation, making the core operation (usually format) as lightweight as possible, and gives us resolvedOptions method that allows users to retrieve the values the object options were resolved to.

Now, in RelativeTimeFormat, we introduce a new concept - an option that is resolved at core operation calltime, rather than construction time. The format(value, unit) differs from all previous Intl APIs in the unit component.
Since it's a dummy operation which does not compute anything, that works, but both for higher level APIs and for the future bestFit, we should plan ahead how we're going to facilitate an API that has to select the unit when core operation is called, and how to provide an ability for the user to retrieve not only the result string, but also the unit it resolved to.

To present it as JS, I see two ways to do it:

let rtf = new Intl.RelativeTimeFormat('en-US', {style: 'short'});
let result = rtf.format(5, 'bestFit');
result === {'value': 'in 5 sec', unit: 'second'};

or:

let rtf = new Intl.RelativeTimeFormat('en-US', {style: 'short'});
let value = rtf.format(5, 'bestFit'); // 'in 5 sec'
let unit = rtf.resolveBestFitUnit(5); // 'second'

There of course may be others that I didn't think of :)

@rxaviers , @caridy , @littledan , @maggiepint, @icambron - can you share your preference?

What should be the "numeric" output for (0, "day")? 0 days ago or in 0 days?

Would we use the below?

rtf.format(0, "day");
// > "in 0 days"

rtf.format(-0, "day");
// > "0 days ago"

We need to update the spec to reflect this special case.

Relative time format may be useful within localization contexts but in order for that to work, we'd need to follow ICU and expose ability to capitalize the formatted string.

ICU exposes UDisplayContext [0] which in this case would take one of the three values standalone, sentence-start or sentence-middle. Example:

let rtf = new Intl.RelativeTimeFormat('en-US', {
  context: 'sentence-start'
});
rtf.format(new Date() - 1000 * 60 * 60 * 24); // 'Yesterday'

let rtf = new Intl.RelativeTimeFormat('en-US', {
  context: 'sentence-middle'
});
rtf.format(new Date() - 1000 * 60 * 60 * 24); // 'yesterday'

I don't think we should do this for the first revision, but wanted to file an issue already to put it in peoples radar when talking about API.

[0] http://www.icu-project.org/apiref/icu4c/udisplaycontext_8h.html#ac80aa1aceff6c7ad2e9f983a19d8d868

Update: this can be solved by using a calendar option as Zibi suggests below.

Problem

The current proposal takes a number of ms as argument and calculates the correspondent second, minute, ..., year for formatting, being a positive in the future and a negative in past, which seems very sane.

It happens that some calendards have different months and years lengths [1]. Thankfully, the equation (used here for deducing time units) should always work for seconds, minutes, hours, and days, but it might fail for deducing months and years. For example, in the Chinese Calendar there are 12 or 13 months; in the Islamic Calendar, there are 354 or 355 days year.

In a general sense, e.g., suppose a developer is writing a game where he needs to display the relative time of Martian months, the current calculation doesn't make sense. Note that in this example case, it doesn't make sense even for day.

General thoughts

Above we have a good and a bad news. The bad news is that the problem lies in the calendar calculation and that's usually a tough problem. The good news is that it doesn't have anything to do with internationalization/localization (i18n).

The i18n problem is very simple, it's to display the localized message, e.g., 10 seconds ago where numeric value is -10 and unit is second. Additionally to this problem is whether or not the formatted text is integer or decimal, because it could change the plural form.

The calendar calculation problem is whether or not a bunch of ms corresponds to a bunch of months.

The current relative time proposal tries to solve both problems. It would be easier if it sticks with the i18n problem only.

Any thoughts?

1:

• In the Chinese Calendar there are 12 or 13 months https://en.wikipedia.org/wiki/Chinese_calendar and http://www.math.nus.edu.sg/aslaksen/calendar/cal.pdf
• In the Islamic Calendar, there are 354 or 355 days year. https://en.wikipedia.org/wiki/Islamic_calendar
• More calendars https://en.wikipedia.org/wiki/List_of_calendars.

Hi,

In the interest of full disclosure, this is my first time reviewing spec text - so I may just not understand a convention. However, I find this wording ambiguous:

When the Intl.RelativeTimeFormat.prototype.format is called with an optional argument value, the following steps are taken:

Let relativeTimeFormat be *this* value.

What does this refer to? If I understand correctly it should mean that the object relativeTimeFormat is the same as the this value in the function - which would make sense because the next line validates that relativeTimeFormat is an instance of a relative time format object. It's just confusing because the word value is already defined as a different (number) argument.

If anything, I might change it to Let relativeTimeFormat be *this*.

It just seems cleaner--all those Get()s are unobservable since the object never leaks, but this is a fragile-feeling property.

The "bestFit" unit is currently specified as following:

• If units.[[Second]] is less than 60, return "Second".
• If units.[[Minute]] is less than 60, return "Minute".
• If units.[[Hour]] is less than 24, return "Hour".
• If units.[[Day]] is less than 7, return "Day".
• If units.[[Week]] is less than 4, return "Week".
• If units.[[Month]] is less than 12, return "Month".
• Return "Year".

For numeric type output, this works nicely, i.e., the following table shows the output for past tense, but we obviously have the equivalent for the future tense.

For the textual output, we have the following.

Problem

The verbose outputs can be misleading depending on the context. For example:

Diagnose

For the numeric output, the continuous distance basted on seconds (or milliseconds) works fine. Although for the textual output, the continuous distance can lead to incorrect results, instead it should be used a discrete count based on the subject unit. For example, see the 4 tables below that corresponds to the 4 items above respectively.

The last row of the table above shows a case where "yesterday" is wrong. Note it happens when the continuous distance !== discrete distance in days. The second row shows a case where both "10 hours ago" or "yesterday" could be used without prejudice. Note when the continuous distance === discrete distance in days, there's no doubt.

The similar occurs to the following units.

For the numeric output, the continuous distance basted on seconds (or milliseconds) works fine. Although for the textual output, the continuous distance can lead to incorrect results, instead it should be used a discrete count based on the subject unit. For example, see the 4 tables below that corresponds to the 4 items above respectively.

The last row of the table above shows a case where "yesterday" is wrong. Note it happens when the continuous distance !== discrete distance in days. The second row shows a case where both "10 hours ago" or "yesterday" could be used without prejudice. Note when the continuous distance === discrete distance in days, there's no doubt.

The similar occurs to the following units.

Conclusion

For textual output, we need an additional handling for the bestFit that takes into account what I'm calling the discrece distance in the respective unit.

For the case where the output is wrong, the fix is a clear requirement. For the cases where both are ok, it is subject to additional analysis. Ideally the API should handle this nicely. I mean, if now is "10 AM", the output "11 hours ago" should be ok instead of "yesterday". Although, I would definitely prefer seeing "yesterday" than "19 hours ago". There should be a threshold based on the discrete distance for the switch.

FWIW, https://github.com/rxaviers/relative-time/ handles discrete distance.