Skip to content

Semantic skeletons design #1067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 30 commits into
base: main
Choose a base branch
from
Open
Changes from 4 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
5180718
Semantic skeletons design
aphillips Apr 6, 2025
239b858
Add links
aphillips Apr 6, 2025
20f623a
Explain picture strings better
aphillips Apr 21, 2025
676f6c9
Update exploration/semantic-skeletons.md
aphillips Apr 22, 2025
289739f
Replace picture output with a table
aphillips Apr 22, 2025
e70ad8a
Fix objective section
aphillips Apr 22, 2025
c5cf831
Update semantic-skeletons.md
aphillips Apr 22, 2025
902eab7
Fix requirements per comments
aphillips Apr 22, 2025
f5de049
Update semantic-skeletons.md
aphillips Apr 22, 2025
d2a16a6
Update exploration/semantic-skeletons.md
aphillips Apr 22, 2025
941405b
Update exploration/semantic-skeletons.md
aphillips Apr 22, 2025
5028972
Update exploration/semantic-skeletons.md
aphillips Apr 22, 2025
10bb70d
clarify the picture string table
aphillips Apr 22, 2025
108e5f3
Update exploration/semantic-skeletons.md
aphillips Apr 23, 2025
9d326ec
Add FAQ, improve option bag skeleton description
aphillips Apr 23, 2025
b8dabd2
An apostrophe escaped notice
aphillips Apr 23, 2025
3ea7e4d
Update exploration/semantic-skeletons.md
aphillips Apr 23, 2025
0f36d02
Adding use cases and descriptions of types
aphillips Apr 25, 2025
1fb130b
Add an alternative design
aphillips Apr 27, 2025
afd0001
Update exploration/semantic-skeletons.md
aphillips Apr 29, 2025
a9440d5
Update exploration/semantic-skeletons.md
aphillips Apr 29, 2025
ff58cc3
Update exploration/semantic-skeletons.md
aphillips Apr 29, 2025
937c04b
Make `Intl.DateTimeFormat` present tense
aphillips Apr 29, 2025
1beea81
typo
aphillips May 2, 2025
be26724
Add @eemeli's example
aphillips May 2, 2025
7cf129a
Apply suggestion manually (time zone/offset discussion)
aphillips May 5, 2025
754c53f
Update exploration/semantic-skeletons.md
aphillips May 5, 2025
9f84cba
Start work on 2025-05-12 discussion
aphillips May 13, 2025
e29b5e2
Add materials about field width specification
aphillips Jun 4, 2025
8f41b5f
Add design from @sffc's comment
aphillips Jun 4, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 49 additions & 3 deletions exploration/semantic-skeletons.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ using a microsyntax derived from familiar 'picture strings' (see below)
combined with code in ICU (`DateTimePatternGenerator`) to produce the desired date/time value format.

`Intl.DateTimeFormat` provided options to provide a similar capability.
These weren't "skeletons" from the point of view that they didn't use a dedicated microsyntax
similar to 'picture strings',
but the effect was the same:
users specified which fields they wanted with which display options (such as width).
For example:
```javascript
options = {
Expand Down Expand Up @@ -62,14 +66,15 @@ Advantages of semantic skeletons over classical skeletons:

#### Avoid 'picture strings'

The MFWG early on considered including support for "picture strings" in the formatting of date/time values.
There is a Working Group consensus **_not_** to support picture strings in Unicode MessageFormat, if possible.
Many date/time formatting regimes provide for "picture strings".
A "picture string" is a pattern using a microsyntax in which the user (developer, translator, UX designer)
exactly specifies the desired format of the date/time value.
In a picture string, separators, spaces, and other formatting are explicitly specified.
This provides a lot of power to the developer or user experience designer, in terms of specifying formatting.
For example: `MMM dd, yyyy` or `yyyy-dd-MM'T'HH:mm:ss`

The MFWG early on considered including support for "picture strings" in the formatting of date/time values.
There is a Working Group consensus **_not_** to support picture strings in Unicode MessageFormat, if possible.

Picture strings require translators to interact with and "translate" the picture string
which is embedded into the _placeholder_ in order to get appropriately localized output.
Expand Down Expand Up @@ -129,6 +134,47 @@ selecting locale-appropriate separators,
and producing a "picture string" that can be consumed by date/time formatters
such as `java.text.SimpleDateFormat`.

### FAQ

This section considers some potential arguments against the design
or captures frequently asked questions about it.

**What if semantic skeletons doesn't support the format I want?
Unlike picture strings or classical skeletons, semantic skeletons do not allow unrestricted
composition of date/time formats.**

If there were an overlooked format, it could be added in a future release.
However, the designers of semantic skeletons have considered the breadth of use cases.
If a skeleton is not available, there is probably a good reason for avoiding it.

**My UX designer wants to specify different separators/presentational details.
I could do that with picture strings, but not with any kind of skeleton. Help!**

Specialized formats might be constructed using individual fields or by using formatToParts.
In general, such specialized designs rapidly become examples of poor internationalization,
since examples of such adjustments do not consider the breadth of date/time representation.

**Semantic skeletons are too new.
Implementation experience is limited.
Shouldn't we wait to adopt them?**

Unicode MessageFormat has a one-time opportunity to avoid "deprecated at birth" date/time formatting
and to provide a robust, internally-consistent mechanism that guides users away from
common date/time formatting pitfalls.

This is already ample experience with classical skeletons.
The difference with semantic skeletons is that it filters out "mistakes"
such as "11 PM April" (`jjMMMM` or `HHaMMMM`) or "2 2025" (`dyyyy`).

**What about specialized formats, such as ISO8601?**

These should be provided via other means that requiring a specialized pattern
and the (optional) `@locale` attribute. Do you really want to support this,
given that it can then be used for other things:
```
{$now :datetime pattern=|yyyy-MM-dd'T'HH:mm:ss.sssz| @locale=und timezone=UTC}
```

## Use-Cases

_What use-cases do we see? Ideally, quote concrete examples._
Expand Down Expand Up @@ -175,7 +221,7 @@ They should not have to coerce or convert normal date/time types in order to do
| `yMMMMd` | April 6, 2025 |
1. Developers, translators, and UI designers should not have to learn
multiple new microsyntaxes or multiple different sets of options for date/time value formatting.
1. Any microsyntax or option set specified should be easy to understand only from the placeholder.
1. Any microsyntax or option set specified should be easy to understand only from the expression.
1. Any microsyntax or option set specified should not _require_ translators to alter the values in most or all locales.

## Constraints
Expand Down