Consider adding an FAQ section to the README

[glen-84]

Examples:

• Why must all messages be wrapped in braces?
  • Looks noisy and unclean, and would represent mostly-ignored content in MF1.
  • Answered here.
    • I always wonder how often leading and trailing whitespace is actually significant.
    • It seems that the opening and closing delimiter are more the responsibility of the storage, not the message specification.
• Why do both messages and placeholders use braces?
  • Isn't clear what is translatable.
  • A rule like "never translate anything inside braces" would be much easier to follow/read.
• Why use let and not var?
  • They are variables, so var may be more appropriate?

---

Alternative with translatable content not wrapped in braces:

{let $hostName = $host :person firstName=long}
{let $guestName = $guest :person firstName=long}
{let $guestsOther = $guestCount :number offset=1}

{match $host :gender, $guestOther :number}

{when female 0} {$hostName} does not give a party.
{when female 1} {$hostName} invites {$guestName} to her party.
{when female 2} {$hostName} invites {$guestName} and one other person to her party.
{when female *} {$hostName} invites {$guestName} and {$guestsOther} other people to her party.

{when male 0} {$hostName} does not give a party.
{when male 1} {$hostName} invites {$guestName} to his party.
{when male 2} {$hostName} invites {$guestName} and one other person to his party.
{when male *} {$hostName} invites {$guestName} and {$guestsOther} other people to his party.

{when * 0} {$hostName} does not give a party.
{when * 1} {$hostName} invites {$guestName} to their party.
{when * 2} {$hostName} invites {$guestName} and one other person to their party.
{when * *} {$hostName} invites {$guestName} and {$guestsOther} other people to their party.

I do like the formatting syntax mentioned here:

{let $hostName = $host:person(firstName=long)}
{let $guestName = $guest:person(firstName=long)}
{let $guestsOther = $guestCount:number(offset=1)}

• It makes the calls more compact, making it more clear that the parts are connected, and not just a space-delimited list.
• It allows you to get rid of the braces for placeholders, leaving braces for "control flow" only.

{match $count:plural}

{when 1} One apple
{when *} $count:number apples

($count is probably already formatted as a number because of the plural, but it's just an example)

I find it much easier to see:

• What should be translated (everything outside braces, excluding $-prefixed placeholders).
• Which parts are "control flow", which parts are placeholders, etc.

---

Putting that together, you get:

{var $hostName = $host:person(firstName=long)}
{var $guestName = $guest:person(firstName=long)}
{var $guestsOther = $guestCount:number(offset=1)}

{match $host:gender $guestOther:number}

{when female 0} $hostName does not give a party.
{when female 1} $hostName invites $guestName to her party.
{when female 2} $hostName invites $guestName and one other person to her party.
{when female *} $hostName invites $guestName and $guestsOther other people to her party.

{when male 0} $hostName does not give a party.
{when male 1} $hostName invites $guestName to his party.
{when male 2} $hostName invites $guestName and one other person to his party.
{when male *} $hostName invites $guestName and $guestsOther other people to his party.

{when * 0} $hostName does not give a party.
{when * 1} $hostName invites $guestName to their party.
{when * 2} $hostName invites $guestName and one other person to their party.
{when * *} $hostName invites $guestName and $guestsOther other people to their party.

The current example seems to go against the design goal of making it clear which parts of the message body are translatable content. I believe that the translatable content should be "plain text" without any wrapping or sigils, and the matching logic should be the part that is clearly marked and separated. There is too much noise with all the braces, it should be easier to parse for humans.

---

Edit: It can also support multiple formatters/functions:

$amount:number(style=currency):round

[glen-84]

@romulocintra What do you think?

[romulocintra]

cc @aphillips

[aphillips]

adding to the 23 January agenda

[duerst]

Eliminating braces around ($prefixed) variables may run into problems with languages that do not use inter-word spaces (Thai, Chinese, Japanese,...) or cases where word spaces are used by the (content of the) variables are supposed to become part of a word.

[glen-84]

That's a good point. I overlooked that.

While adding a $ on both sides could work, it's not a natural "paired" character like braces, brackets, or parentheses.

Square brackets are another option (to also differentiate between control flow and placeholders), but based on the existing issues, it seems that they are more commonly used in some languages.

That leaves using braces for placeholders as well:

{when female 0} {$hostName} does not give a party.

I'm not sure what impact the look-ahead that @stasm mentioned would have. Don't you already have to look past an opening brace to determine whether it's a message or placeholder (in the current syntax)?

[stasm]

Yes, we should definitely add an FAQ. The questions your give as examples are a good start (thanks) and are bound to resurface in the future. It’s a good idea to explicitly document the rationale for these choices.

I’m going to try to bootstrap some answers by giving a bit of context and linking a few references to past discussions in separate replies below, so that we can discuss each of them separately.

[stasm]

• Why must all messages be wrapped in braces?
  • Looks noisy and unclean, and would represent mostly-ignored content in MF1.
  • Answered here.
    • I always wonder how often leading and trailing whitespace is actually significant.
    • It seems that the opening and closing delimiter are more the responsibility of the storage, not the message specification.

I recall a discussion about which mode to start in: text or code.

• Always starting in "text" mode meant that we could drop pattern delimiters but would need a special syntax to mark let definitions and match selectors. Otherwise these syntax constructs would look like regular text or like placeholders.

• Always starting in "code" mode solves these syntax issues at the expense of requiring all translations to be delimited with braces at all times. Start in "code" mode exclusively #256 has a few arguments in favor of this approach.

[stasm]

The syntax that you propose starts in the "text" mode, i.e. the following is a valid single-variant message with no let definitions nor selectors:

$hostName does not give a party.

Dropping delimiters from around placeholders generally limits what we can do with placeholders. It constrains the scope of placeholders to named arguments. Instead, we'd like to be able to also use placeholders to express things like:

• markup, see https://github.com/unicode-org/message-format-wg/blob/main/spec/syntax.md#markup and Markup: how do ensure non-HTML display elements are first class? #238,
• standalone function calls, e.g. {:message id=some_other_message}, see https://github.com/unicode-org/message-format-wg/blob/main/spec/syntax.md#expressions,
• (hypothetically in the future) list arguments, e.g. {$foo $bar :listFormat separator=and}.

It also requires special-casing $ in translation text, which expands the group of characters classes that need escaping. As I mention in another sub-thread here, we generally tried to reduce the number of character classes that need escaping. And it makes it harder to know where the placeholder ends, in rare but possible cases where : or () are part of the translation text.

It's a domino effect of issues of different gravity and priority. We felt that delimiting placeholders was the most clear, simple and future-proof solution available. But it also meant that if we wanted to start in the "text" mode, control flow constructs (match selectors and let definitions) would need a different syntax -- otherwise a placeholder at the beginning of a message can be confused with a control flow expression. Or we'd need to be LL(2) and look past the opening { to see whether it's a start of a placeholder or a start of a control flow sequence.

[glen-84]

Always starting in "text" mode meant that we could drop pattern delimiters but would need a special syntax to mark let definitions and match selectors. Otherwise these syntax constructs would look like regular text or like placeholders.

If let or match definitions are wrapped in braces, how would they conflict with placeholders, beginning with a $?

{let $hostName = $host:person(firstName=long)}

Host name: {$hostName}

Always starting in "code" mode solves these syntax issues at the expense of requiring all translations to be delimited with braces at all times. Start in "code" mode exclusively #256 has a few arguments in favor of this approach.

And I'm suggesting that a syntax intended for less-technical users should not focus on the code mode – the text should be the most prominent.

Dropping delimiters from around placeholders generally limits what we can do with placeholders

In response to the comment by @duerst, I've returned to the ${...} syntax for placeholders.

Updated proposal.

[stasm]

• Why do both messages and placeholders use braces?
  • Isn't clear what is translatable.
  • A rule like "never translate anything inside braces" would be much easier to follow/read.

#255 has a lengthy discussion about this. As a group, we felt that it was more important to maximally limit the number of special characters that need to be escaped inside translation text. By using braces to delimit both patterns and placeholders, translations only ever need to escape \{ and \}. If we had chosen different delimiters for patterns, translations would need to delimit two different classes of characters, for example: literal \{ (to not start a placeholder) and a literal \] (to not end the current pattern).

Using curly braces everywhere is perhaps a bit less readable, but it can also be considered consistent, and is unambiguous syntax-wise. We assume that most developers writing MessageFormat strings can learn to use braces for everything, and that most translators will use CAT tools which hide the syntax anyways.

[stasm]

A note on why we felt limiting the number of special characters was important: we expect MessageFormat messages to be embedded in a wide variety of programming languages and container formats. The fewer characters need escaping, the less chance there is of a potential conflict with regards to what's considered "special". There's also less chance of a conflict with punctuation rules of natural languages.

[stasm]

• Why use let and not var?
  • They are variables, so var may be more appropriate?

The exact naming of things in MessageFormat is not final and is being discussed in #248. #289 considered a few more keywords but let continued to have the most support.

[glen-84]

Thanks. I don't feel too strongly about this one. I'll read a bit more, and comment if I have anything of value to add.

[glen-84]

Updated proposal:

{let $hostName = $host:person(firstName=long)}
{let $guestName = $guest:person(firstName=long)}
{let $guestsOther = $guestCount:number(offset=1)}

{match $host:gender $guestOther:number}

{when female 0} {$hostName} does not give a party.
{when female 1} {$hostName} invites {$guestName} to her party.
{when female 2} {$hostName} invites {$guestName} and one other person to her party.
{when female *} {$hostName} invites {$guestName} and {$guestsOther} other people to her party.

{when male 0} {$hostName} does not give a party.
{when male 1} {$hostName} invites {$guestName} to his party.
{when male 2} {$hostName} invites {$guestName} and one other person to his party.
{when male *} {$hostName} invites {$guestName} and {$guestsOther} other people to his party.

{when * 0} {$hostName} does not give a party.
{when * 1} {$hostName} invites {$guestName} to their party.
{when * 2} {$hostName} invites {$guestName} and one other person to their party.
{when * *} {$hostName} invites {$guestName} and {$guestsOther} other people to their party.

The two main differences from the current syntax:

1. "Code" is within braces, not the messages (text-first mode), making it cleaner and easier to identify plain text.
2. Compact function call syntax, making it easier for a human to parse and ignore placeholders as single units.

Regarding future list syntax options:

{[$foo $bar]:listFormat(separator=and)}

[aphillips]

As an individual:

Note that, while we tend to write messages in github in a multi-line format, in fact the pattern string is "all one line". Your proposal should consider how implementations determine the end of the message. Also note that the $ is a variable introducer, not a placeable introducer, that is, it's { $hostName } not {$ hostName }.

Chair hat on:

This item is on the agenda for tomorrow's call (which I hope you can make).

[glen-84]

Your proposal should consider how implementations determine the end of the message.

Hmm. Would it work for any non-placeholder/non-markup tag to terminate a message?

{match $host:gender} {when female} her car {when male} his car
//                                         ^ EOM              ^ EOM

Leading and trailing whitespace would be ignored, so this wouldn't capture the space after car.

{match $count:number}
{when 1} You have one notification. {when *} You have {$count} notifications.
//                                  ^ EOM                                    ^ EOM

If the first non-whitespace character after an unescaped opening brace is one of $, +, or -, then the message continues.

It's a pity that placeholders use the same delimiters. It would be nice if the placeholders were different:

{when 1} You have one notification. {when *} You have [$count] notifications.

I know, it would require another character to be escaped. 🫤

[aphillips]

leading and trailing whitespace would be ignored, so this wouldn't capture the space after car.

Leading and trailing whitespace are often important in messages. If we automatically trim them, users would have to have a way to indicate spaces that should be preserved. Yes, "meaningful" spaces are often due to poor internationalization practices (e.g. concatenation), but that doesn't mean we can ignore them.

I know, it would require another character to be escaped. 🫤

Yes and we discussed this at great length previously (@stasm provides some links). Quoting is one of the problem areas with the former 1.0 syntax and a barrier to users (both on the developer and linguistic sides).

Re-opening issues like this can be a challenge to making positive forward progress. FWIW, I made arguments similar to yours, so am sympathetic, but at some point our group needs to "disagree and commit"† to the design; as such as chair I tend to hold a higher bar in reopening decisions for discussion.

---

† "disagree and commit" is (part of) an Amazon leadership principle, the front half of which is "have backbone". I spent 14 years at Amazon, so it's probably not surprising to find myself thinking in those terms ("you can take the Old Fart out of Amazon, but you can't take..." etc.).

[glen-84]

Leading and trailing whitespace are often important in messages.

Still interested in hearing about the use cases for leading and trailing whitespace, but it can be solved using the syntax suggested by Eemeli in #275.

Re-opening issues like this can be a challenge to making positive forward progress.

I understand, and it may well be the correct decision. It just means that placeholders are a bit less distinguishable.

[glen-84]

Is there any chance that these two changes would be reconsidered? (text-first mode and compact function call syntax)