From 0881cb6f851eb8cbebcd1d4afacc0727806bb0bc Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 6 May 2024 12:56:54 +0300 Subject: [PATCH 01/10] Add design doc for u:options --- exploration/u-options.md | 149 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 exploration/u-options.md diff --git a/exploration/u-options.md b/exploration/u-options.md new file mode 100644 index 0000000000..a4dbe28aef --- /dev/null +++ b/exploration/u-options.md @@ -0,0 +1,149 @@ +# `u:` Options + +Status: **Accepted** + +
+ Metadata +
+
Contributors
+
@eemeli
+
First proposed
+
2023-05-06
+
Pull Requests
+
#780
+
+
+ +## Objective + +Provide common definitions for contextual options. + +## Background + +Function options may influence the resolution, selection, and formatting of annotated expressions. +These provide a great solution for options like `minFractionDigits`, `dateStyle`, +or other similar factors that influence the formatted result. + +However, this single bag of options is not appropriate in all cases, +in particular for options that change the formatting context for the function. + +## Use-Cases + +At least the following function and markup options should be considered: + +- An identifier for the expression or markup. + This is included in the formatted part, + and allows the parts of an expression to be explicitly addressed. + + > Example identifying two literal numbers: + > + > ``` + > The first number was {1234 :number u:id=first} and the second {56789 :number u:id=second}. + > ``` + +- An override for the locale used to format the expression. + Should be expressed as a non-empty sequence of BCP 47 language codes. + + > Example embedding a French literal in an English message: + > + > ``` + > In French, “{|bonjour| :string u:locale=fr}” is a greeting + > ``` + +- An override for the LTR/RTL/auto directionality of the expression. + + > Example explicitly isolating the directionality of a placeholder + > for a custom user-defined function: + > + > ``` + > Welcome, {$user :x:username u:dir=auto} + > ``` + +## Requirements + +Common options or attributes should work the same way in different functions. + +Special options or attributes should not conflict with other option names. + +## Constraints + +User-defined functions are free to use un-namespaced option names +even if the function identifier does use a namespace. + +The `u` namespace is reserved for future standardization. + +No literal syntax is provided for values that are lists or sequences of scalar values. + +## Proposed Design + +Define the expected values and handling for the following options +wherever they are used: + +- `u:id` — A string value that is included as an `id` or other suitable value + in the formatted part(s) for the placeholder, + or any other structured formatted results. + Ignored when formatting to a string, but could show up in error messages. +- `u:locale` — A comma-delimited list of BCP 47 language tags, + or an implementation-defined list of such tags. + The tags are parsed, and they replace the _locale_ + defined in the _formatting context_ for this expression or markup. +- `u:dir` — One of the string values `ltr`, `rtl`, or `auto`. + Replaces the character directionality + defined in the _formatting context_ for this expression or markup. + +Error handling should be well defined for invalid values. + +Additional restrictions could be imposed, +e.g. requiring that each `u:id` is unique within a formatted message. + +Drop variable values from the `attribute` rule: + +```diff +-attribute = "@" identifier [[s] "=" [s] (literal / variable)] ++attribute = "@" identifier [[s] "=" [s] literal] +``` + +## Alternatives Considered + +### Do nothing + +Continue to [caution](https://github.com/unicode-org/message-format-wg/blob/d38ff326d2381b3ef361e996c3431d1b251518d6/spec/syntax.md#attributes) +function authors and other implementers away from creating function-specific or implementation-specific option values +for the use cases presented above. + +As should be obvious, the current situation is not tenable in the long term, and should be resolved. + +### Do not provide any guidance + +Do not include in the spec rules or guidance for declaring formatted part identifiers, +or overriding the message locale or directionality. + +This would mean not defining anything for default registry functions either, +effectively requiring implementation-specific options like `icu:locale`. + +Other functions could use their own definitions and handling for similar options, +such as `locale` or `x:lang`. + +Formatted parts for markup would not be able to directly include an identifier. + +### Define options for default registry only + +Define at least `locale` and `dir` as options for default registry functions, +with handling internal to each function implementation. + +Other functions could use their own definitions and handling for similar options, +such as `locale` or `x:lang`. + +Formatted parts for markup would not be able to directly include an identifier. + +### Use expression attributes + +Use option-like syntax `@id=foo` instead of `u:id=foo`, as described in the +[Expression Attributes](https://github.com/unicode-org/message-format-wg/blob/d38ff326d2381b3ef361e996c3431d1b251518d6/exploration/expression-attributes.md) design document. + +Same runtime effects as with the proposed solution. + +Requires expression attribute values to accept variables, +for use like `@locale=$locale`. + +Defines a formatting runtime use for expression attributes. From 3d294d19a64d7bd7a1939f570a069361277eb167 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 6 May 2024 13:29:11 +0300 Subject: [PATCH 02/10] Apply changes to expression attributes design doc --- exploration/expression-attributes.md | 73 +++++++--------------------- 1 file changed, 17 insertions(+), 56 deletions(-) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index b1eb3e0f95..838fe44981 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -12,6 +12,7 @@ Status: **Proposed**
Pull Requests
#458
#772
+
#780
@@ -35,35 +36,6 @@ For example, many of the [XLIFF 2 inline element] attributes don't really make s At least the following expression attributes should be considered: -- Attributes with a formatting runtime impact: - - - `id` — An identifier for the expression. - This is included in the formatted part, - and allows the parts of an expression to be explicitly addressed. - - > Example identifying two literal numbers: - > - > ``` - > The first number was {1234 :number @id=first} and the second {56789 :number @id=second}. - > ``` - - - `locale` — An override for the locale used to format the expression. - Should be expressed as a non-empty sequence of BCP 47 language codes. - - > Example embedding a French literal in an English message: - > - > ``` - > In French, “{|bonjour| @locale=fr}” is a greeting - > ``` - - - `dir` — An override for the LTR/RTL/auto directionality of the expression. - - > Example explicitly isolating the directionality of a placeholder: - > - > ``` - > Welcome, {$username @dir=auto} - > ``` - - Attributes relevant for translators, tools, and other message operations, but with no runtime impact: @@ -88,10 +60,10 @@ At least the following expression attributes should be considered: whether the expression should or should not be localised. The values here correspond to those used for this property in HTML and elsewhere. - > Example embedding a non-translatable French literal in an English message: + > Example embedding a non-translatable CLI command in a message: > > ``` - > In French, "{|bonjour| @locale=fr @translate=no}" is a greeting + > Use {+code @translate=no}git ls-files{-code} to list all files in a repository. > ``` - `canCopy`, `canDelete`, `canOverlap`, `canReorder`, etc. — Flags supported by @@ -115,20 +87,12 @@ including expressions without an annotation. Attributes are distinct from function options. -Common attributes are defined by the MF2 specification -and must be supported by all implementations. - Users may define their own attributes. Implementations may define their own attributes. -Some attributes may have an effect on the formatting of an expression. -These cannot be defined within comments either within or outside a message. - Each attribute relates to a specific expression. -An attribute's scope is limited to the expression to which it relates. - Multiple attributes should be assignable to a single expression. Attributes should be assignable to all expressions, not just placeholders. @@ -143,25 +107,16 @@ the reserved/private-use rules will need to be adjusted to support attributes. ## Proposed Design -Add support for option-like `@key=value` attribute pairs at the end of any expression. - -If the syntax for function options is extended to support flag-like options -(see #386), -also extend expression attribute syntax to match. +Add support for `@key` attributes at the end of any expression or markup. +These may consist only of an attribute name, +or an option-like `@key=value` pair with a literal value. To distinguish expression attributes from options, require `@` as a prefix for each attribute asignment. -Examples: `@translate=yes` and `@locale=$exprLocale`. - -Define the meaning and supported values of some expression attributes in the specification, -including at least `@dir` and `@locale`. - -To support later extension of the specified set of attributes while allowing user extensibility, -suggest custom attribute names to include a U+002D Hyphen-Minus `-`. -Examples: `@can-copy=no`, `@note-link=|https://...|`. +Examples: `@translate=yes` and `@xliff:canCopy`. -Allow expression attributes to influence the formatting context, -but do not directly pass them to user-defined functions. +Do not allow expression or markup attributes to influence the formatting context, +or pass them to function handlers. ## Alternatives Considered @@ -172,9 +127,15 @@ If not explicitly defined, less information will be provided to translators. Function options may be used as a workaround, but each implementation and user will end up with different practices. -### Use function options, but with some suggested prefix like `_` +### Use function options, but with some suggested "discard" namespace like `_` + +Examples: `_:translate=yes` and `_:example=|World|`. + +Requires reserving an additional namespace. + +Requires cooperation from implementers to ignore all options using the namespace. -A bit less bad than the previous, but still mixes attributes and options into the same namespace. +Makes defining namespaced attributes difficult. At least a no-op function is required for otherwise unannotated expressions. From eabd18b06ef91b90c148ce40119f3320d2a34dbf Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 6 May 2024 08:24:39 -0700 Subject: [PATCH 03/10] Update exploration/u-options.md Co-authored-by: Eemeli Aro --- exploration/u-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/u-options.md b/exploration/u-options.md index a4dbe28aef..790a01297f 100644 --- a/exploration/u-options.md +++ b/exploration/u-options.md @@ -1,4 +1,4 @@ -# `u:` Options +# Contextual Options Status: **Accepted** From 1308971a16d77841bef94ef8a458193511886383 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 6 May 2024 18:25:32 +0300 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Addison Phillips --- exploration/u-options.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/exploration/u-options.md b/exploration/u-options.md index 790a01297f..d86d6fcb98 100644 --- a/exploration/u-options.md +++ b/exploration/u-options.md @@ -24,8 +24,16 @@ Function options may influence the resolution, selection, and formatting of anno These provide a great solution for options like `minFractionDigits`, `dateStyle`, or other similar factors that influence the formatted result. -However, this single bag of options is not appropriate in all cases, -in particular for options that change the formatting context for the function. +Such options naturally correspond to function arguments or builder-style function constructors. +Each option is specific to the associated API. +Users (message authors, translators, developers) should not expect +that a given option name has the same meaning between functions +or that its behavior stays the same. + +To reduce the learning curve for users and improve consistency, +it would be useful to have common options +(generally those related to the formatting context) +shared between all functions. ## Use-Cases @@ -42,12 +50,11 @@ At least the following function and markup options should be considered: > ``` - An override for the locale used to format the expression. - Should be expressed as a non-empty sequence of BCP 47 language codes. - > Example embedding a French literal in an English message: + > Example embedding a French date in an English message: > > ``` - > In French, “{|bonjour| :string u:locale=fr}” is a greeting + > In French, this date would be displayed as {|2024-05-06| :date u:locale=fr} > ``` - An override for the LTR/RTL/auto directionality of the expression. From d302fb226f73562818cedd4d4a485941ea2ae9ce Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 6 May 2024 18:27:09 +0300 Subject: [PATCH 05/10] Rename exploration/u-options.md -> exploration/contextual-options.md --- exploration/{u-options.md => contextual-options.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename exploration/{u-options.md => contextual-options.md} (100%) diff --git a/exploration/u-options.md b/exploration/contextual-options.md similarity index 100% rename from exploration/u-options.md rename to exploration/contextual-options.md From b880f9b2a3aee8d329e68af6a068d9e652013acd Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Wed, 22 May 2024 17:28:15 +0300 Subject: [PATCH 06/10] Refactor as a change of the expression-attributes proposal --- exploration/contextual-options.md | 156 ------------------------ exploration/expression-attributes.md | 175 +++++++++++++++++++++++---- 2 files changed, 150 insertions(+), 181 deletions(-) delete mode 100644 exploration/contextual-options.md diff --git a/exploration/contextual-options.md b/exploration/contextual-options.md deleted file mode 100644 index d86d6fcb98..0000000000 --- a/exploration/contextual-options.md +++ /dev/null @@ -1,156 +0,0 @@ -# Contextual Options - -Status: **Accepted** - -
- Metadata -
-
Contributors
-
@eemeli
-
First proposed
-
2023-05-06
-
Pull Requests
-
#780
-
-
- -## Objective - -Provide common definitions for contextual options. - -## Background - -Function options may influence the resolution, selection, and formatting of annotated expressions. -These provide a great solution for options like `minFractionDigits`, `dateStyle`, -or other similar factors that influence the formatted result. - -Such options naturally correspond to function arguments or builder-style function constructors. -Each option is specific to the associated API. -Users (message authors, translators, developers) should not expect -that a given option name has the same meaning between functions -or that its behavior stays the same. - -To reduce the learning curve for users and improve consistency, -it would be useful to have common options -(generally those related to the formatting context) -shared between all functions. - -## Use-Cases - -At least the following function and markup options should be considered: - -- An identifier for the expression or markup. - This is included in the formatted part, - and allows the parts of an expression to be explicitly addressed. - - > Example identifying two literal numbers: - > - > ``` - > The first number was {1234 :number u:id=first} and the second {56789 :number u:id=second}. - > ``` - -- An override for the locale used to format the expression. - - > Example embedding a French date in an English message: - > - > ``` - > In French, this date would be displayed as {|2024-05-06| :date u:locale=fr} - > ``` - -- An override for the LTR/RTL/auto directionality of the expression. - - > Example explicitly isolating the directionality of a placeholder - > for a custom user-defined function: - > - > ``` - > Welcome, {$user :x:username u:dir=auto} - > ``` - -## Requirements - -Common options or attributes should work the same way in different functions. - -Special options or attributes should not conflict with other option names. - -## Constraints - -User-defined functions are free to use un-namespaced option names -even if the function identifier does use a namespace. - -The `u` namespace is reserved for future standardization. - -No literal syntax is provided for values that are lists or sequences of scalar values. - -## Proposed Design - -Define the expected values and handling for the following options -wherever they are used: - -- `u:id` — A string value that is included as an `id` or other suitable value - in the formatted part(s) for the placeholder, - or any other structured formatted results. - Ignored when formatting to a string, but could show up in error messages. -- `u:locale` — A comma-delimited list of BCP 47 language tags, - or an implementation-defined list of such tags. - The tags are parsed, and they replace the _locale_ - defined in the _formatting context_ for this expression or markup. -- `u:dir` — One of the string values `ltr`, `rtl`, or `auto`. - Replaces the character directionality - defined in the _formatting context_ for this expression or markup. - -Error handling should be well defined for invalid values. - -Additional restrictions could be imposed, -e.g. requiring that each `u:id` is unique within a formatted message. - -Drop variable values from the `attribute` rule: - -```diff --attribute = "@" identifier [[s] "=" [s] (literal / variable)] -+attribute = "@" identifier [[s] "=" [s] literal] -``` - -## Alternatives Considered - -### Do nothing - -Continue to [caution](https://github.com/unicode-org/message-format-wg/blob/d38ff326d2381b3ef361e996c3431d1b251518d6/spec/syntax.md#attributes) -function authors and other implementers away from creating function-specific or implementation-specific option values -for the use cases presented above. - -As should be obvious, the current situation is not tenable in the long term, and should be resolved. - -### Do not provide any guidance - -Do not include in the spec rules or guidance for declaring formatted part identifiers, -or overriding the message locale or directionality. - -This would mean not defining anything for default registry functions either, -effectively requiring implementation-specific options like `icu:locale`. - -Other functions could use their own definitions and handling for similar options, -such as `locale` or `x:lang`. - -Formatted parts for markup would not be able to directly include an identifier. - -### Define options for default registry only - -Define at least `locale` and `dir` as options for default registry functions, -with handling internal to each function implementation. - -Other functions could use their own definitions and handling for similar options, -such as `locale` or `x:lang`. - -Formatted parts for markup would not be able to directly include an identifier. - -### Use expression attributes - -Use option-like syntax `@id=foo` instead of `u:id=foo`, as described in the -[Expression Attributes](https://github.com/unicode-org/message-format-wg/blob/d38ff326d2381b3ef361e996c3431d1b251518d6/exploration/expression-attributes.md) design document. - -Same runtime effects as with the proposed solution. - -Requires expression attribute values to accept variables, -for use like `@locale=$locale`. - -Defines a formatting runtime use for expression attributes. diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index ddc0bd4d11..e0dac5d23e 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -28,9 +28,23 @@ Function options may influence the resolution, selection, and formatting of anno These provide a great solution for options like `minFractionDigits`, `dateStyle`, or other similar factors that influence the formatted result. -However, this single bag of options is not appropriate in all cases, -in particular for attributes that pertain to the expression as a selector or a placeholder. -For example, many of the [XLIFF 2 inline element] attributes don't really make sense as function options. +Such options naturally correspond to function arguments or builder-style function constructors. +Each option is specific to the associated API. +Users (message authors, translators, developers) should not expect +that a given option name has the same meaning between functions +or that its behavior stays the same. + +To reduce the learning curve for users and improve consistency, +it would be useful to have common options +(generally those related to the formatting context) +shared between all functions. + +Separately from formatting concerns, +it is often useful to attach other information to message expressions and markup. +For example, presenting how an example value could be formatted can be very useful for the message's translation, +and providing the original source representation of a placeholder may be essential for being able to format a non-MF2 message, +if it has been transformed to MF2 to provide translators with a unified experience. +As a specific example, many of the [XLIFF 2 inline element] attributes don't really make sense as function options. [XLIFF 2 inline element]: http://docs.oasis-open.org/xliff/xliff-core/v2.1/os/xliff-core-v2.1-os.html#inlineelements @@ -38,7 +52,7 @@ For example, many of the [XLIFF 2 inline element] attributes don't really make s ### User Story: Formatting Context Override As a message author, I want to override values in the _formatting context_ for a specific _expression_. -I would like to do this in a consistent, effective manner that does not require a change to the +I would like to do this in a consistent, effective manner that does not require a change to the _function_ or _markup_ support code in order to be effective. As far as the code is concerned, it just reads the value from the _formatting context_ normally. @@ -83,11 +97,11 @@ Some examples include: These may include an example, which is best represented in MF2 as an `@example=...` attribute. - In #772, @eemeli calls out: - > While working on [moz.l10n](https://github.com/mozilla/moz-l10n/), - > a new Python localization library that uses the MF2 message and - > [resource data model](https://github.com/eemeli/message-resource-wg/pull/16) to represent messages - > from a number of different current syntaxes, - + > While working on [moz.l10n](https://github.com/mozilla/moz-l10n/), + > a new Python localization library that uses the MF2 message and + > [resource data model](https://github.com/eemeli/message-resource-wg/pull/16) to represent messages + > from a number of different current syntaxes, + Apple's Xcode supports localization of plural messages via `.stringsdict` XML files, which encode the plural variable's name as a `NSStringLocalizedFormatKey` value, where it appears as e.g. `%#@countOfFoo@` or similar. @@ -97,6 +111,35 @@ Some examples include: ### General Use Cases At least the following expression attributes should be considered: +- Attributes with a formatting runtime impact: + + - `id` — An identifier for the expression or markup. + This is included in the formatted part, + and allows each part of a message to be explicitly addressed. + + > Example identifying two literal numbers: + > + > ``` + > The first number was {1234 :number u:id=first} and the second {56789 :number u:id=second}. + > ``` + + - `locale` — An override for the locale used to format the expression. + + > Example embedding a French date in an English message: + > + > ``` + > In French, this date would be displayed as {|2024-05-06| :date u:locale=fr} + > ``` + + - `dir` — An override for the LTR/RTL/auto directionality of the expression. + + > Example explicitly isolating the directionality of a placeholder + > for a custom user-defined function: + > + > ``` + > Welcome, {$user :x:username u:dir=auto} + > ``` + - Attributes relevant for translators, tools, and other message operations, but with no runtime impact: @@ -148,6 +191,10 @@ including expressions without an annotation. Attributes are distinct from function options. +Common options or attributes should work the same way in different functions. + +Special options or attributes should not conflict with other option names. + Users may define their own attributes. Implementations may define their own attributes. @@ -168,26 +215,115 @@ the reserved/private-use rules will need to be adjusted to support attributes. ## Proposed Design -Add support for `@key` attributes at the end of any expression or markup. -These may consist only of an attribute name, -or an option-like `@key=value` pair with a literal value. +Solve the two disparate use cases separately, +so that their namespaces are not comingled. + +### Contextual options + +Define the expected values and handling for the following options +wherever they are used: + +- `u:id` — A string value that is included as an `id` or other suitable value + in the formatted part(s) for the placeholder, + or any other structured formatted results. + Ignored when formatting to a string, but could show up in error messages. +- `u:locale` — A comma-delimited list of BCP 47 language tags, + or an implementation-defined list of such tags. + The tags are parsed, and they replace the _locale_ + defined in the _formatting context_ for this expression or markup. +- `u:dir` — One of the string values `ltr`, `rtl`, or `auto`. + Replaces the character directionality + defined in the _formatting context_ for this expression or markup. + +Error handling should be well defined for invalid values. + +Additional restrictions could be imposed, +e.g. requiring that each `u:id` is unique within a formatted message. + +### Attributes + +Add support for standalone `@key` as well as +option-like `@key=value` attribute pairs with a literal value +at the end of any expression or markup. -To distinguish expression attributes from options, +To distinguish attributes from options, require `@` as a prefix for each attribute asignment. Examples: `@translate=yes` and `@xliff:canCopy`. Do not allow expression or markup attributes to influence the formatting context, or pass them to function handlers. +Drop variable values from the `attribute` rule: + +```diff +-attribute = "@" identifier [[s] "=" [s] (literal / variable)] ++attribute = "@" identifier [[s] "=" [s] literal] +``` + ## Alternatives Considered -### Do not support expression attributes +### Do nothing + +Continue to [caution](https://github.com/unicode-org/message-format-wg/blob/d38ff326d2381b3ef361e996c3431d1b251518d6/spec/syntax.md#attributes) +function authors and other implementers away from creating function-specific or implementation-specific option values +for the use cases presented above. + +As should be obvious, the current situation is not tenable in the long term, and should be resolved. + +### Do not provide any guidance + +Do not include in the spec rules or guidance for declaring formatted part identifiers, +or overriding the message locale or directionality. + +Do not define a common way to communicate information +about an expression or markup to translators or tools. + +This would mean not defining anything for default registry functions either, +effectively requiring implementation-specific options like `icu:locale`. + +Other functions could use their own definitions and handling for similar options, +such as `locale` or `x:lang`. + +Formatted parts for markup would not be able to directly include an identifier. If not explicitly defined, less information will be provided to translators. Function options may be used as a workaround, but each implementation and user will end up with different practices. +### Define options for default registry only + +Define at least `locale` and `dir` as options for default registry functions, +with handling internal to each function implementation. + +Other functions could use their own definitions and handling for similar options, +such as `locale` or `x:lang`. + +Formatted parts for markup would not be able to directly include an identifier. + +Do not define a common way to communicate information +about an expression or markup to translators or tools. + +### Use attributes also for contextual options + +Add support for standalone `@key` as well as +option-like `@key=value` attribute pairs with a literal or variable values +at the end of any expression or markup. + +To distinguish attributes from options, +require `@` as a prefix for each attribute asignment. +Examples: `@translate=yes` and `@locale=$exprLocale`. + +Define the meaning and supported values of some attributes in the specification, +including at least `@dir` and `@locale`. + +To support later extension of the specified set of attributes while allowing user extensibility, +require custom attribute names to be namespaced. +Examples: `@xliff:can-copy=no`, `@note:link=|https://...|`. + +Allow expression attributes to influence the formatting context, +but do not directly pass them to user-defined functions. + ### Use function options, but with some suggested "discard" namespace like `_` Examples: `_:translate=yes` and `_:example=|World|`. @@ -210,17 +346,6 @@ esp. if a similar expression is used in multiple variants. Comments should not influence the runtime behaviour of a formatter. -### Define `@attributes` as above, but explicitly namespace custom attributes - -As namespacing may also be required for function names and function option names, -and because we want to allow at least for custom function options -to be definable on default formatters, -the namespace rules for parts of the specification would end up differing. - -By suggesting instead of requiring, -we rely on our stability policy to guide implementations to keep clear of the namespace -that may be claimed by later versions of the specification. - ### Enable function chaining within a single expression By allowing for multiple annotation functions on a single expression, From affc926fb6eabd859257feb625232a019cbb6c96 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Wed, 22 May 2024 18:27:39 +0300 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Addison Phillips --- exploration/expression-attributes.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index e0dac5d23e..444cbea7c8 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -30,9 +30,10 @@ or other similar factors that influence the formatted result. Such options naturally correspond to function arguments or builder-style function constructors. Each option is specific to the associated API. -Users (message authors, translators, developers) should not expect -that a given option name has the same meaning between functions -or that its behavior stays the same. +Message authors such as translators and developers want consistent ways to do common tasks, +such as providing hints to translation tools or overriding the locale, +but, unless MessageFormat provides otherwise, cannot rely on implementations +to consistently implement these. To reduce the learning curve for users and improve consistency, it would be useful to have common options @@ -44,7 +45,8 @@ it is often useful to attach other information to message expressions and markup For example, presenting how an example value could be formatted can be very useful for the message's translation, and providing the original source representation of a placeholder may be essential for being able to format a non-MF2 message, if it has been transformed to MF2 to provide translators with a unified experience. -As a specific example, many of the [XLIFF 2 inline element] attributes don't really make sense as function options. +As a specific example, many of the [XLIFF 2 inline element] attributes have no meaning +to the function that they appear as options or annotations of. [XLIFF 2 inline element]: http://docs.oasis-open.org/xliff/xliff-core/v2.1/os/xliff-core-v2.1-os.html#inlineelements From c44de1e57f9c1a4252ef144df7a8cc772b32373c Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 27 May 2024 17:12:49 +0300 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Tim Chevalier --- exploration/expression-attributes.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index 444cbea7c8..364fe6ed85 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -42,8 +42,8 @@ shared between all functions. Separately from formatting concerns, it is often useful to attach other information to message expressions and markup. -For example, presenting how an example value could be formatted can be very useful for the message's translation, -and providing the original source representation of a placeholder may be essential for being able to format a non-MF2 message, +For example, presenting how an example value could be formatted can be very useful for the message's translation. +Providing the original source representation of a placeholder may be essential for being able to format a non-MF2 message, if it has been transformed to MF2 to provide translators with a unified experience. As a specific example, many of the [XLIFF 2 inline element] attributes have no meaning to the function that they appear as options or annotations of. @@ -217,7 +217,8 @@ the reserved/private-use rules will need to be adjusted to support attributes. ## Proposed Design -Solve the two disparate use cases separately, +Provide separate solutions for attributes that impact formatting, +and those which do not, so that their namespaces are not comingled. ### Contextual options @@ -309,7 +310,7 @@ about an expression or markup to translators or tools. ### Use attributes also for contextual options Add support for standalone `@key` as well as -option-like `@key=value` attribute pairs with a literal or variable values +option-like `@key=value` attribute pairs with a literal or variable value at the end of any expression or markup. To distinguish attributes from options, From 1c35ab967fa1163890e832487890dd16c33adf3d Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Sun, 9 Jun 2024 20:03:28 +0300 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: Addison Phillips --- exploration/expression-attributes.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index 364fe6ed85..7a98ff98ce 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -30,7 +30,7 @@ or other similar factors that influence the formatted result. Such options naturally correspond to function arguments or builder-style function constructors. Each option is specific to the associated API. -Message authors such as translators and developers want consistent ways to do common tasks, +Message authors, such as translators or developers, want consistent ways to do common tasks, such as providing hints to translation tools or overriding the locale, but, unless MessageFormat provides otherwise, cannot rely on implementations to consistently implement these. @@ -296,7 +296,9 @@ but each implementation and user will end up with different practices. ### Define options for default registry only -Define at least `locale` and `dir` as options for default registry functions, +Do not define a common way to communicate information +about an expression or markup to translators or tools. +Instead, define at least `locale` and `dir` as options for default registry functions, with handling internal to each function implementation. Other functions could use their own definitions and handling for similar options, @@ -337,6 +339,8 @@ Requires cooperation from implementers to ignore all options using the namespace Makes defining namespaced attributes difficult. +Could be combined with the definition of `u:dir`, `u:locale`, and `u:id` contextual options. + At least a no-op function is required for otherwise unannotated expressions. ### Rely on semantic comments From 7509601a0cc262231c50299a50c2539c5fd854f3 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 15 Jul 2024 12:39:27 +0300 Subject: [PATCH 10/10] Add text explaining markup identifier uses --- exploration/expression-attributes.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index 7a98ff98ce..2edde5613a 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -305,6 +305,9 @@ Other functions could use their own definitions and handling for similar options such as `locale` or `x:lang`. Formatted parts for markup would not be able to directly include an identifier. +Implementations and users will need to invent their own practices with +markup option names like `l10n-id`, `mf:id`, or `markupId` +to refer to specific markup parts. Do not define a common way to communicate information about an expression or markup to translators or tools.