Add first draft of default attribute definitions #1098

eemeli · 2025-09-08T12:11:23Z

Adds an initial set of expression, markup, and message attribute definitions.

The proposed attributes are drawn from:

XLIFF 2.2
The messages.json web extension definition for placeholders.example
Enumerate supported metadata/properties for messages, sections & resources eemeli/message-resource-wg#19

As noted in the text, this is not intended as a final list, but as a starting point. The text is not being currently proposed to be normative, but we could change that later.

aphillips

Good start. Lots of nit-picky comments.

Maybe a good question is: should these be directly incorporated? Or should all of these XLIFFy things be namespaced? Some of what XLIFF does doesn't apply to UMF messages and some of it would be much better on a message resource level (instead of cluttering up the message itself).

spec/attributes/README.md

aphillips · 2025-09-08T16:20:30Z

spec/attributes/README.md

+
+#### @translate
+
+_Value:_ `yes` or `no`.


Indicate that yes is default?

Is there a reason attributes don't follow a similar structure to functions and their options here?

I don't think we've agreement that yes is the default. In fact, for expressions, I would think that the general default might in fact be no to indicate that a translator is not expected to make any changes to the expression.

Considering this a bit more, maybe something like translate=input or translate=|input,minimumFractionDigits| would be better? That would indicate which parts are expected to be translatable.

The default value is no when the attribute is not present, but yes when the attribute is present and has no value, right?

I don't like the values yes/no, but they are inherited from XLIFF (and its friends, such as ITS) and we should probably remain consistent with them (for portability at least)

Ah, that's a slightly different undrstanding of "default" than I'd had -- as in, the value that's applied if the attribute is not present at all.

I don't hate the yes/no as they're relatively legible and are perhaps easier to extend with other enum values than e.g. true/false would be. But as they're already in use by XLIFF, we should use the same values.

I think that requiring explicit values is cleaner.
How hard is it to type =no (3 characters)?

translate=|input,minimumFractionDigits| would be better? > That would indicate which parts are expected to be translatable.

I think that such info does not belong here, it belongs in the function registry.

A while ago I even provided a list of l10n attributes to use for each function option (something like hide, read-only, enum, free-form). I can even think of more options.

aphillips · 2025-09-08T16:21:23Z

spec/attributes/README.md

+
+Indicates whether or not the _markup_ and its contents can be re-ordered.
+
+#### @comment


Why not just permit the "global" attributes on markup?

I don't understand what this means.

You're repeating attributes defined above. Why not make those like @comment global to both expressions and markup?

That seems like an editorial fix we could apply later, if it does hold that the annotations continue to match on expressions and markup.

It would be a bad idea for identically-named attributes to diverge. The sets aren't identical, of course.

aphillips · 2025-09-08T16:23:14Z

spec/attributes/README.md

+
+#### @max-length
+
+_Value:_ A strictly positive integer, followed by a space, followed by one of the following:


digit size option?

That's limited to max 99, and we need to allow for limits greater than that.

spec/attributes/README.md

aphillips · 2025-09-08T16:24:14Z

spec/attributes/README.md

+_Value:_ A strictly positive integer, followed by a space, followed by one of the following:
+- `chars`
+- `bytes`
+- `lines`


Good luck with this one.

As in, we should not include it?

Measuring bytes will depend on some character encoding somewhere. Without an indication of the encoding (which this doesn't provide), there is no way to perform the measurement.

(FWIW, you're missing graphemes, which is another measurement (approximately "screen positions", but only approximately so).)

Lines depends on... font, font size, pixel width, line-breaking, hyphenation (insert more here) and are even harder to define that bytes.

Length limitations are a "fact of life" in localization, but badly defined mechanisms for them are not that helpful.

One option would be to leave out the units, and to let the implementation figure out what the limit means, something in the overlap of characters/code points/graphemes.

spec/attributes/README.md

Co-authored-by: Addison Phillips <[email protected]>

eemeli · 2025-09-09T09:47:43Z

Maybe a good question is: should these be directly incorporated? Or should all of these XLIFFy things be namespaced? Some of what XLIFF does doesn't apply to UMF messages and some of it would be much better on a message resource level (instead of cluttering up the message itself).

During yesterday's call, @mihnita also expressed concern regarding cluttering up a message with multiple attributes. His thought was that it would often be preferable to attach a u:id to an expression or markup, and refer to that from a separate message-level block to attach attribute-y metadata to the relevant placeholder(s).

To me, this speaks of a need to have that capability also be well defined, so that it can be ergonomically done across resource formats. In other words, I think we need a JavaDoc-y syntax for message-level attributes.

mihnita · 2025-10-06T16:23:10Z

spec/attributes/README.md

+
+Empty _messages_ SHOULD be accompanied by an explanatory `@comment`.
+
+#### @max-length


This is a can of worms :-)

One might want two kinds os length limitations:

storage
For example if you put the strings a in "traditional" database and you have a max size for the translations. Then you need the encoding of the string.
So you "max 120 bytes as utf-8"

visual (for example using em)
That is a can of worms.
Because "m" is not the same width as "l" :-)
And "AAAAVVVVV" is not the same width as "AVAVAVAV" (because of kerning).
And ligatures, and complex script.
To accurately measure anything you need the exact font, if it is monospaced or not, with the kerning table, ligatures, combining chars, etc.
Even the font version might affect you.
Then in some systems you can enable/disable opentype features.
To measure multi-lines you need the max length of one line, if hyphenation is available, the exact hyphenation data + engine, if justification is set or not :-)

TLDR: I would leave it out for now

mihnita · 2025-10-06T16:26:17Z

spec/attributes/README.md

+
+Identify the _functions_ and _markup_ supported by the _message_ formatter.
+
+#### @source


It really does not belong here!

mihnita · 2025-10-06T16:29:50Z

spec/attributes/README.md

+
+Indicates whether the _message_ is translatable or not.
+
+Some _messages_ may be required to have the same value in all locales.


Then they are not messages that should be stored in resource bundles. They can very well be hard-coded.

A better use case is probably to encode info about locale sensitive behavior. For example the fact that the default order for a Contacts app should be first-name, except that Japanese, and a few others should be last name.

But that would not be MF2.

TLDR: I am not sure I see a good use case.

mihnita · 2025-10-06T16:31:12Z

spec/attributes/README.md

+
+Some _messages_ may be required to have the same value in all locales.
+
+#### @version


I've bend in long debates about mechanisms like this one.
It is controversial, so I would leave it out for now.

mihnita · 2025-10-06T16:32:22Z

spec/attributes/README.md

@@ -0,0 +1,233 @@
+## Expression, Markup, and Message Attributes


In general I am not happy with the idea of storing all of this in the message proper.
This belongs in the storage, outside the message.

janispritzkau · 2025-10-13T18:59:25Z

I have a couple of questions and would like to share my understanding of the matter. In addition to the message resource standard, I’m considering how it could integrate with an in-context editing or translation tool.

Expression Attributes

These attributes may vary by locale, so it makes sense for them to be included within the message:

@comment
@term - Isn't @comment sufficient for this use case?
@example - This is really useful. It reminds me of OpenAPI, which lets you generate example queries.

For @translate, I think it should be consistent across locales. To me, it still makes more sense for it to be in the message rather than hardcoded. Perhaps it could be enforced through linters.

Markup Attributes

What exactly does the @comment attribute refer to in the markup context? Is it describing a particular use of the tag, or the type of tag itself, or the content between an opening/closing pair? If it's about the type of tag, ~~perhaps the resource-level metadata (in Message Resource) would be a better place~~ then it should go into a schema/registry.

The same with @term. What is it referring to?

~~Personally, I would drop these from the spec because they seem too application-specific:~~ Do these attributes define what translators can or shouldn’t do during translation?

@can-copy
@can-delete
@can-overlap
@can-reorder

Message Attributes

I understand the flexibility of having messages with @translate=no in the resource bundle. However, it feels odd to duplicate such messages across all locales. If a base locale or locale-independent bundle exists, then this attribute would make more sense.

I haven't had time to think about the other message-related attributes yet, so that's all for now.

Add first draft of default attribute definitions

6bc7fc2

eemeli added the Agenda+ Requested for upcoming teleconference label Sep 8, 2025

aphillips reviewed Sep 8, 2025

View reviewed changes

eemeli commented Sep 9, 2025

View reviewed changes

spec/attributes/README.md Show resolved Hide resolved

Apply suggestions from code review

39911f2

Co-authored-by: Addison Phillips <[email protected]>

eemeli requested review from aphillips and mihnita September 9, 2025 09:47

eemeli added 2 commits September 22, 2025 11:54

Update spec/attributes/README.md

cf12529

Update spec/attributes/README.md

50ec0b4

mihnita reviewed Oct 6, 2025

View reviewed changes


		Indicates whether or not the _markup_ and its contents can be re-ordered.

		#### @comment


		#### @max-length

		_Value:_ A strictly positive integer, followed by a space, followed by one of the following:


		Empty _messages_ SHOULD be accompanied by an explanatory `@comment`.

		#### @max-length


		Identify the _functions_ and _markup_ supported by the _message_ formatter.

		#### @source


		Indicates whether the _message_ is translatable or not.

		Some _messages_ may be required to have the same value in all locales.


		Some _messages_ may be required to have the same value in all locales.

		#### @version

		@@ -0,0 +1,233 @@
		## Expression, Markup, and Message Attributes

Uh oh!

Add first draft of default attribute definitions #1098

Are you sure you want to change the base?

Add first draft of default attribute definitions #1098

Uh oh!

Conversation

eemeli commented Sep 8, 2025

Uh oh!

aphillips left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aphillips Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eemeli commented Sep 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janispritzkau commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Expression Attributes

Markup Attributes

Message Attributes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aphillips Sep 9, 2025 •

edited

Loading

janispritzkau commented Oct 13, 2025 •

edited

Loading