From c40fb7555c5db6436636758888dfce77bda315a3 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 13 May 2024 17:01:22 -0700 Subject: [PATCH 1/4] [DESIGN] Add user stories and other build-out of the expression attribute design Add user-stories and examples to the expression attributes design. --- exploration/expression-attributes.md | 40 ++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index b1eb3e0f95..c7b8ac6c9c 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -33,6 +33,46 @@ For example, many of the [XLIFF 2 inline element] attributes don't really make s ## Use-Cases +### 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 the `function` +inside the `expression` to do special things in their code. +As far as the `function` is concerned, they just read the value from the `formatting context` +normally. + +A common example of this is the `locale`. +Overriding the `locale` used by a function might be needed if I want a specific locale chosen: +>``` +>You format {42 :number @locale=fr} like this in French. +>``` +Or if I want to supply it in a variable: +>``` +> You format {42 :number @locale=$userSpecified} like this in {$userSpecified} +>``` + +Other examples include `direction` or `time zone`: +>``` +> The MAC address is always LTR: {$mac :string @dir=ltr} +> I don't want the system default time zone or the one in $d: {$d :date @timezone=|America/Phoenix|} +>``` + +An implemenation might want to override a custom contextual value: +>``` +> You format this specially: {42 :number @amzn:marketplace=US} +>``` + +### User Story: Translation Tooling +As a translator or developer, I want to ensure that instructions to CAT tools, +including information for human translators or that help MT can be included into +the message and preserved through the translation process. + +In general, such instructions, metadata, etc. do not effect the runtime formatting of the message. +Implementers of functions or markup do not wish to access these and might be annoyed if +the names of translation-related fields conflict with the normal naming of options. +Message compilers might remove these expression attributes when creating messages for use by the runtime. + + +### General Use Cases At least the following expression attributes should be considered: - Attributes with a formatting runtime impact: From 280716d6c7fd96fedc84aef326a322ba043132ea Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 13 May 2024 17:02:34 -0700 Subject: [PATCH 2/4] Update expression-attributes.md --- exploration/expression-attributes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index c7b8ac6c9c..9b07e2212d 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -7,6 +7,7 @@ Status: **Proposed**
Contributors
@eemeli
+
@aphillips
First proposed
2023-08-27
Pull Requests
From da7742502b89c47fc287df3d8eca10b650b5b628 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 13 May 2024 17:04:17 -0700 Subject: [PATCH 3/4] English fluent should be --- exploration/expression-attributes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index 9b07e2212d..7983939b45 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -37,8 +37,8 @@ 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 the `function` -inside the `expression` to do special things in their code. -As far as the `function` is concerned, they just read the value from the `formatting context` +inside the `expression` to do special things in its code. +As far as the `function` is concerned, it just reads the value from the `formatting context` normally. A common example of this is the `locale`. From f5b6bd0ba2ecfea32adcdcdc6235908f53442b83 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 14 May 2024 16:35:50 -0700 Subject: [PATCH 4/4] Address comments --- exploration/expression-attributes.md | 66 ++++++++++++++++++---------- 1 file changed, 43 insertions(+), 23 deletions(-) diff --git a/exploration/expression-attributes.md b/exploration/expression-attributes.md index 7983939b45..7fe3a5b3df 100644 --- a/exploration/expression-attributes.md +++ b/exploration/expression-attributes.md @@ -13,6 +13,7 @@ Status: **Proposed**
Pull Requests
#458
#772
+
#792
@@ -35,32 +36,31 @@ For example, many of the [XLIFF 2 inline element] attributes don't really make s ## Use-Cases ### 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 the `function` -inside the `expression` to do special things in its code. -As far as the `function` is concerned, it just reads the value from the `formatting context` -normally. - -A common example of this is the `locale`. -Overriding the `locale` used by a function might be needed if I want a specific locale chosen: ->``` ->You format {42 :number @locale=fr} like this in French. ->``` +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 +_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. + +A common example of this is the _locale_. +Overriding the locale used by a function might be needed if I want a specific locale chosen: +``` +You format {42 :number @locale=fr} like this in French. +``` Or if I want to supply it in a variable: ->``` -> You format {42 :number @locale=$userSpecified} like this in {$userSpecified} ->``` +``` +You format {42 :number @locale=$userSpecified} like this in {$userSpecified} +``` -Other examples include `direction` or `time zone`: ->``` -> The MAC address is always LTR: {$mac :string @dir=ltr} -> I don't want the system default time zone or the one in $d: {$d :date @timezone=|America/Phoenix|} ->``` +Other examples include _direction_ or the _time zone_: +``` +The MAC address is always LTR: {$mac :string @dir=ltr} +I don't want the system default time zone or the one in $d: {$d :date @timezone=|America/Phoenix|} +``` -An implemenation might want to override a custom contextual value: ->``` -> You format this specially: {42 :number @amzn:marketplace=US} ->``` +An implementation might want to override a custom contextual value: +``` +You format this specially: {42 :number @amzn:marketplace=US} +``` ### User Story: Translation Tooling As a translator or developer, I want to ensure that instructions to CAT tools, @@ -72,6 +72,26 @@ Implementers of functions or markup do not wish to access these and might be ann the names of translation-related fields conflict with the normal naming of options. Message compilers might remove these expression attributes when creating messages for use by the runtime. +Some examples include: +- In addition to supporting a limited set of HTML elements, + Android String Resources use `` to wrap + [nontranslatable content](https://developer.android.com/guide/topics/resources/localization#mark-message-parts). + This is best represented in MF2 with a `@translate=no` attribute. +- Web extension `messages.json` files allow for named [placeholders](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/i18n/Locale-Specific_Message_reference#placeholders) + that are mapped to indexed arguments. + 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, + + 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. + To display only the relevant "countOfFoo" name of this variable to localizers as context, + it's best to use a `@source=...` attribute on the selector. ### General Use Cases At least the following expression attributes should be considered: