Sprints: Properly structure JS `Intl` docs

[bershanskiy]

User story

As an MDN reader, I want consistent reference documentation, so I can find information reliably.

Acceptance criteria

Members of Intl are actually not child pages of Intl, so they need to be moved to match the existing URL patterns and they need to conform to the page recipes as outlined in _linter requirements for JavaScript documentation_.

To avoid breaking URLs in tables on MDN, probably the content pages should be moved first (with old URL redirecting to new URL) and only then the BCD should be updated.

Related issues

• This is the content part of linter from https://github.com/mdn/browser-compat-data/issues/5201.
• TODO: BCD PR for URL update

Tasks

Below is a complete list of moves (including children of children of Intl, which might be moved automatically when their parent is moved):

× javascript\builtinsIntl.json

• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Collator"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Collator/compare"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/compare"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Collator/prototype"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/prototype"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Collator/resolvedOptions"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/resolvedOptions"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Collator/supportedLocalesOf"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/supportedLocalesOf"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/format"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/format"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/formatRange"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatRange"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/formatRangeToParts"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatRangeToParts"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/formatToParts"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatToParts"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/prototype"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/resolvedOptions"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Collator/supportedLocalesOf"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/supportedLocalesOf"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ListFormat"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ListFormat/format"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/format"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ListFormat/formatToParts"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/formatToParts"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ListFormat/prototype"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/prototype"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ListFormat/resolvedOptions"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/resolvedOptions"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ListFormat/supportedLocalesOf"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/supportedLocalesOf"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/baseName"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/baseName"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/calendar"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/caseFirst"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/caseFirst"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/collation"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/collation"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/hourCycle"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/language"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/language"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/maximize"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/maximize"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/minimize"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/minimize"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/numberingSystem"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/numberingSystem"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/numeric"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/numeric"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/prototype"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/prototype"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/region"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/region"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/script"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/script"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Locale/toString"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/toString"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/format"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/format"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/formatToParts"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/formatToParts"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/prototype"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/prototype"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/resolvedOptions"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/resolvedOptions"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/supportedLocalesOf"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/supportedLocalesOf"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/PluralRules"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/PluralRules"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/PluralRules/prototype"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/prototype"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/PluralRules/resolvedOptions"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/resolvedOptions"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/PluralRules/select"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/select"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/PluralRules/supportedLocalesOf"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/supportedLocalesOf"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/format"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/formatToParts"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/prototype"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/prototype"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/resolvedOptions"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions"
  
  
• Move
  
  
  
  • From: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/supportedLocalesOf"
  
  
  • To: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/supportedLocalesOf"
  
  

[vinyldarkscratch]

(I'd actually not be the right one to CC for this; currently, my work is solely focused on BCD, and I have no page creation/movement permissions on the MDN docs!)

[bershanskiy]

@vinyldarkscratch

I'd actually not be the right one to CC for this

I CC'ed you to inform you of the change and ensure the move is reasonable (aka I'm not miss-understanding something). If you prefer, I won't CC you in the future.

[vinyldarkscratch]

Ah, well thank you, I appreciate it! No worries -- I just thought someone else besides me would have a better opinion on the documentation structure. 😛

[chrisdavidmills]

This should really be @Elchi3 's call. He is the MDN JS lead.

[Elchi3]

We could do this, I guess...
I wonder why it was set up this way. I think it might have been to get these things into the sidebar more easily or something. Intl is a bit like a namespace object here: a content type we haven't defined as such, maybe we need to for stumptown.
If we are going to move these things around, we should also do it for all translations. JS docs are fairly well translated, I think, and it wouldn't be okay to just have the locales out of sync here. So, this is quite some page moving then.

How do we treat these namespace objects in API docs? Or in webextension docs? Maybe @wbamberg has opinions about the content structures, too. I think it would be great if we would first agree on how these things would be structured properly before we move a lot of pages.
(that said, this is unlikely a project I would just do now before going on holidays).

[bershanskiy]

I wonder why it was set up this way.

That happened over 5 years ago, so I don't think anyone still remembers why. :)

I think it would be great if we would first agree on how these things would be structured properly before we move a lot of pages.

Absolutely!

[bershanskiy]

Also, if Intl omission is intentional, then probably
https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/getCanonicalLocales
should be moved to
https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/getCanonicalLocales

[wbamberg]

tl;dr IMO, @bershanskiy is right.

Intl is a bit like a namespace object here: a content type we haven't defined as such

A close analog to Intl seems to be WebAssembly, which we treat as an object with only static members, some of which are constructors. We put all these pages under the WebAssembly page (e.g. WebAssembly.Memory()).

It's probably beneficial to have pages that document an object's members be nested under that object itself, so this suggests that what we do with WebAssembly is right, and @bershanskiy is right to want to do the same for Intl.

One consequence of this is that given our sidebar implementation, if we want the objects they construct (like Collator) to appear in the top-level JS sidebar under "References/Built-in objects", then it looks like the pages must live directly underneath /docs/Web/JavaScript/Reference/Global_Objects.

So we can see that in the sidebar here, that Intl.Collator does appear, whereas WebAssembly.Memory doesn't.

That's probably OK. Noone has complained about this situation with respect to WebAssembly.Memory. And we will eventually rework the JS sidebars, and could address this when we do so, if we think it is important.

---

(This part is more possible things for the future.)

But also. We talked in London about whether it made sense to separate constructors from the objects they construct. To me (maybe only because my background is not JS?) it's really weird that we have these pages that are both, and that conflate constructors and the objects they create.
In fact you've already implemented this separation for BigInt.

What if we said:

• Intl is an object that has a member Collator(), that's a constructor for Intl.Collator objects. It has a docs page under Intl, like all the other members. This page describes the constructor's syntax.
• Intl.Collator is an object that has its own separate docs page. This page describes the overall object and lists its members.

If we did this, where would the page for the Intl.Collator object live?

• Living under Intl seems good for coherence, but means slugs would collide for the object and the constructor, unless we took more steps to prevent that. Also, the page for the Intl.Collator object seems less closely tied to Intl than the constructor.

• Or we could put it at the same level as the other "JS objects", although we might then want to stop calling it "/Global_Objects/" since they aren't global, whatever that means in this context. That would make it easier to list "all the objects" in the sidebar, assuming we wanted to do that. I think this option sounds better. But then, if we put the page at, say, "/JavaScript/Reference/Objects/Collator", it could in theory clash with the object constructed using the Foo.Collator() constructor.

How do we treat these namespace objects in API docs?

My sense is that we tend to do the latter thing, and put all the objects ("interfaces") at the top level under Web/API. But I'm not sure if the Web APIs have quite the same issue that we do here (and I'm also not sure if the Web APIs are a good choice to copy).

[Elchi3]

Thank you for this excellent analysis, Will!

A close analog to Intl seems to be WebAssembly

I was looking around but couldn't think of an analog but there you have it! Nice find!

given our sidebar implementation [...]
And we will eventually rework the JS sidebars, and could address this when we do so, if we think it is important.

Yes, this. I'm fine with not constraining us any longer to our brittle sidebars but instead think how about we want the content to be structured and then make sidebars work with that later.

Separate constructors from the objects they construct.
In fact you've already implemented this separation for BigInt.

Yes, I still think we should go this way all throughout. It is something I want work on once I'm back in January.

So, for Intl, could it look like this?

• /Intl (object, has no constructor)
• /Intl/getCanonicalLocales (method)
• /Intl/Collator (object)
• /Intl/Collator/Collator (constructor)
• /Intl/Collator/compare (method)
• /Intl/DateTimeFormat (object)
• /Intl/DateTimeFormat/DateTimeFormat (constructor)
• /Intl/DateTimeFormat/formatToParts (method)
• ...

That is, everything moves under Intl and we have dedicated pages for the objects and for the constructors (and we stop having "prototype" property pages).

[bershanskiy]

Separate constructors from the objects they construct.
In fact you've already implemented this separation for BigInt.

Yes, I still think we should go this way all throughout. It is something I want work on once I'm back in January.

For sanity I created a separate issue #2571 for that.

[Elchi3]

I've updated this to be a user stories per our sprint rules and I'm planning to do this work in our next sprint.

[Elchi3]

I've moved all pages and their translations.
The BCD update is in https://github.com/mdn/browser-compat-data/pull/6015

[wbamberg]

Very nice, Florian.

This isn't exactly a suggestion for a thing to change right now, just a thing to clarify :). In the Intl page we have a section "Properties". If I understand correctly we have decided to call this "Constructor properties" - I understand that renaming the sections isn't in scope for this, so I'm not exactly asking for this change.

But the items in there are links to the object pages (e.g. Intl.Collator) not the constructor pages (e.g. Intl.Collator() constructor. Is that what we want? I think it would be better to link to the constructor, since that's what these properties actually are. What do you think?

[Elchi3]

Thanks for the review, Will!

If I understand correctly we have decided to call this "Constructor properties"

Yes, I've renamed it.

But the items in there are links to the object pages (e.g. Intl.Collator) not the constructor pages (e.g. Intl.Collator() constructor. Is that what we want? I think it would be better to link to the constructor, since that's what these properties actually are. What do you think?

I agree constructor links are better. I've changed the links.

[Elchi3]

The BCD update was merged. I think this is all done now.