diff --git a/spec/attributes/README.md b/spec/attributes/README.md new file mode 100644 index 0000000000..fadbabb78f --- /dev/null +++ b/spec/attributes/README.md @@ -0,0 +1,32 @@ +## Expression, Markup, and Message Attributes + +> [!IMPORTANT] +> This part of the specification is under incubation by the MessageFormat WG, +> and may end up being finalized elsewhere. +> It is non-normative. + +### Expression and Markup Attributes + +- [@can-copy](expression-and-markup.md#can-copy) +- [@can-delete](expression-and-markup.md#can-delete) +- [@can-overlap](expression-and-markup.md#can-overlap) (Markup only) +- [@can-reorder](expression-and-markup.md#can-reorder) (Markup only) +- [@comment](expression-and-markup.md#comment) +- [@example](expression-and-markup.md#example) (Expression only) +- [@term](expression-and-markup.md#term) +- [@translate](mexpression-and-markup.md#translate) + +### Message Attributes + +- [@allow-empty](message.md#allow-empty) +- [@obsolete](message.md#obsolete) +- [@param](message.md#param) +- [@schema](message.md#schema) +- [@translate](message.md#translate) + +### Attribute Values + +_Attributes_ are not required to have a value. +For _attributes_ defined here that explicitly support `yes` as a value, +an _attribute_ with no value is considered synonymous +with the same _attribute_ with the value `yes`. diff --git a/spec/attributes/expression-and-markup.md b/spec/attributes/expression-and-markup.md new file mode 100644 index 0000000000..c346b926d8 --- /dev/null +++ b/spec/attributes/expression-and-markup.md @@ -0,0 +1,139 @@ +## Expression and Markup Attributes + +> [!IMPORTANT] +> This part of the specification is under incubation by the MessageFormat WG, +> and may end up being finalized elsewhere. +> It is non-normative. + +The Unicode MessageFormat syntax and data model allow for _attributes_ +to be defined on _expressions_ and _markup_. +These MUST NOT have any impact on the _formatting_ of a message, +and are intended to inform users, such as translators, and tools +about the specific _expressions_ or _markup_ to which they are attached. +_Attributes_ MAY be stripped from _expressions_ and _markup_ +with no effect on the message's _formatting_. + +As all _attributes_ with _reserved identifiers_ are reserved, +definitions are provided here for common _attribute_ use cases. +Use a _custom identifier_ for other (custom) _attributes_, +preferably one with an appropriate _namespace_. + +### @can-copy + +_Value:_ `yes` or `no`. + +Indicates whether or not the _expression_ or the _markup_ and its contents can be copied. + +This corresponds to +the [XLIFF 2 `canCopy` attribute](https://docs.oasis-open.org/xliff/xliff-core/v2.2/xliff-core-v2.2-part1.html#cancopy). + +> For example: +> +> ``` +> Have a {#span @can-copy}great and wonderful{/span @can-copy} birthday! +> ``` + +### @can-delete + +_Value:_ `yes` or `no`. + +Indicates whether or not the _expression_ or the _markup_ and its contents can be deleted. + +This corresponds to +the [XLIFF 2 `canDelete` attribute](https://docs.oasis-open.org/xliff/xliff-core/v2.2/xliff-core-v2.2-part1.html#candelete). + +### @can-overlap (Markup only) + +_Value:_ `yes` or `no`. + +Indicates whether or not the _markup_ and its contents where this _attribute_ is used +can enclose partial _markup_ +(i.e. a _markup-open_ without its corresponding _markup-end_, +or a _markup-end_ without its corresponding _markup-start_). + +This corresponds to +the [XLIFF 2 `canOverlap` attribute](https://docs.oasis-open.org/xliff/xliff-core/v2.2/xliff-core-v2.2-part1.html#canoverlap). + +### @can-reorder (Markup only) + +_Value:_ `yes` or `no`. + +Indicates whether or not the _markup_ and its contents can be re-ordered. + +This corresponds to +the [XLIFF 2 `canReorder` attribute](https://docs.oasis-open.org/xliff/xliff-core/v2.2/xliff-core-v2.2-part1.html#canreorder). + +### @comment + +_Value_: A non-empty string. + +Associates a freeform comment with an _expression_ or _markup_. + +This corresponds to +the [ITS 2 Localization Note data category](https://www.w3.org/TR/its20/#locNote-datacat), and +the [XLIFF 2 comment annotation](https://docs.oasis-open.org/xliff/xliff-core/v2.2/xliff-core-v2.2-part1.html#commentAnnotation). + +> For example: +> +> ``` +> The {$device @comment=|Possible values: Printer or Stacker|} has been enabled. +> ``` +> +> ``` +> Click {#link @comment=|Rendered as a button|}here{/link} to continue. +> ``` + +### @example (Expression only) + +_Value_: A non-empty string. + +An example of the value the _expression_ might take. + +> For example: +> +> ``` +> Error: {$details @example=|Failed to fetch RSS feed.|} +> ``` + +### @term + +_Value_: A non-empty string, or a URI. + +Identifies a well-defined term. +The value may be a short definition of the term, +or a URI pointing to such a definition. + +This corresponds to +the [ITS 2 Terminology data category](https://www.w3.org/TR/its20/#terminology), and +the [XLIFF 2 term annotation](https://docs.oasis-open.org/xliff/xliff-core/v2.2/xliff-core-v2.2-part1.html#termAnnotation). + +> For example: +> +> ``` +> He saw his {|doppelgänger| @term=|https://en.wikipedia.org/wiki/Doppelg%C3%A4nger|}. +> ``` +> +> ``` +> He saw his {#span @term=|https://en.wikipedia.org/wiki/Doppelg%C3%A4nger|}doppelgänger{/span}. +> ``` + +### @translate + +_Value:_ `yes` or `no`. + +Indicates whether the _expression_ or the _markup_ and its contents are translatable or not. + +This corresponds to +the [HTML `translate` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/translate), +the [ITS 2 Translate data category](https://www.w3.org/TR/its20/#trans-datacat), and +the [XLIFF 2 translate annotation](https://docs.oasis-open.org/xliff/xliff-core/v2.2/xliff-core-v2.2-part1.html#translateAnnotation). + +> For example: +> +> ``` +> He saw his {|doppelgänger| @translate=no}. +> ``` +> +> ``` +> He saw his {#span @translate=no}doppelgänger{/span}. +> ``` diff --git a/spec/attributes/message.md b/spec/attributes/message.md new file mode 100644 index 0000000000..64127dc3ca --- /dev/null +++ b/spec/attributes/message.md @@ -0,0 +1,67 @@ +## Message Attributes + +> [!IMPORTANT] +> This part of the specification is under incubation by the MessageFormat WG, +> and may end up being finalized elsewhere. +> It is non-normative. + +This specification does not define a means of attaching an _attribute_ +to the _message_ as a whole. +In general, resource formats and containers of +Unicode MessageFormat _messages_ provide their own such mechanisms. + +At least for now, the syntax of message attributes is +outside the scope of this specification. + +### @allow-empty + +_Value:_ `yes` or `no`. + +Explicitly mark a message with an empty _pattern_ as valid. + +Most empty messages are mistakes, +so being able to mark ones that can be empty is useful. + +Empty _messages_ SHOULD be accompanied by an explanatory `@comment`. + +### @obsolete + +_Value:_ `yes` or `no`. + +Explicitly mark a _message_ as obsolete. + +This might be used in workflows where messages are not immediately removed +when they are no longer referenced by code, +but kept in to support patch releases for previous versions. +During translation, this can be used to de-prioritize such messages. + +> [!NOTE] +> The value could include a way to note some version or timestamp when the removal happened, +> or be paired with a second `@removed-in` or similar tag. + +### @param + +_Value_: **TBD** + +Documents a _variable_. + +> [!NOTE] +> Having a well-defined structure for this attribute is pretty important, +> at least to identify the variable its description is pertaining to. +> In addition to describing the variable in words, it could include: +> - The variable's type -- is it a string, a number, something else? +> - A default example value to use for the variable. + +### @schema + +_Value:_ A valid URI. + +Identify the _functions_ and _markup_ supported by the _message_ formatter. + +### @translate + +_Value:_ `yes` or `no` + +Indicates whether the _message_ is translatable or not. + +Some _messages_ may be required to have the same value in all locales.