Lines Matching +full:formatting +full:- +full:error +full:- +full:messages
6 |-------|------------------------|
13 …odel, syntax, processing, and conformance requirements for the next generation of dynamic messages.
19 <!-- _This is a draft document which may be updated, replaced, or superseded by other documents at …
21 …a stable document; it is inappropriate to cite this document as other than a work in progress._ -->
28 …her comments with the CLDR bug reporting form [[Bugs](https://cldr.unicode.org/index/bug-reports)].
31 For more information see [About Unicode Technical Reports](https://www.unicode.org/reports/about-re…
39 * Part 2: [General](tr35-general.md#Contents) (display names & transforms, etc.)
40 * Part 3: [Numbers](tr35-numbers.md#Contents) (number & currency formatting)
41 * Part 4: [Dates](tr35-dates.md#Contents) (date, time, time zone formatting)
42 * Part 5: [Collation](tr35-collation.md#Contents) (sorting, searching, grouping)
43 * Part 6: [Supplemental](tr35-info.md#Contents) (supplemental data)
44 * Part 7: [Keyboards](tr35-keyboards.md#Contents) (keyboard mappings)
45 * Part 8: [Person Names](tr35-personNames.md#Contents) (person names)
46 * Part 9: [MessageFormat](tr35-messageFormat.md#Contents) (message format)
52 * [Terminology and Conventions](#terminology-and-conventions)
53 * [Stability Policy](#stability-policy)
55 * [Design Goals](#design-goals)
56 * [Design Restrictions](#design-restrictions)
57 * [Messages and their Syntax](#messages-and-their-syntax)
58 * [Well-formed vs. Valid Messages](#well-formed-vs.-valid-messages)
59 * [The Message](#the-message)
61 * [Complex Body](#complex-body)
63 * [Quoted Pattern](#quoted-pattern)
76 * [Other Syntax Elements](#other-syntax-elements)
79 * [Names and Identifiers](#names-and-identifiers)
80 * [Escape Sequences](#escape-sequences)
82 * [Complete ABNF](#complete-abnf)
85 * [Error Handling](#error-handling)
86 * [Syntax Errors](#syntax-errors)
87 * [Data Model Errors](#data-model-errors)
88 * [Variant Key Mismatch](#variant-key-mismatch)
89 * [Missing Fallback Variant](#missing-fallback-variant)
90 * [Missing Selector Annotation](#missing-selector-annotation)
91 * [Duplicate Declaration](#duplicate-declaration)
92 * [Duplicate Option Name](#duplicate-option-name)
93 * [Duplicate Variant](#duplicate-variant)
94 * [Resolution Errors](#resolution-errors)
95 * [Unresolved Variable](#unresolved-variable)
96 * [Unknown Function](#unknown-function)
97 * [Bad Selector](#bad-selector)
98 * [Message Function Errors](#message-function-errors)
99 * [Bad Operand](#bad-operand)
100 * [Bad Option](#bad-option)
101 * [Bad Variant Key](#bad-variant-key)
102 * [Function Registry](#function-registry)
103 * [String Value Selection and Formatting](#string-value-selection-and-formatting)
104 * [The `:string` function](#the-string-function)
108 * [Formatting](#formatting)
109 * [Numeric Value Selection and Formatting](#numeric-value-selection-and-formatting)
110 * [The `:number` function](#the-number-function)
113 * [Default Value of `select` Option](#default-value-of-select-option)
114 * [Percent Style](#percent-style)
116 * [The `:integer` function](#the-integer-function)
119 * [Default Value of `select` Option](#default-value-of-select-option)
120 * [Percent Style](#percent-style)
122 * [Number Operands](#number-operands)
123 * [Digit Size Options](#digit-size-options)
124 * [Number Selection](#number-selection)
125 * [Rule Selection](#rule-selection)
126 * [Determining Exact Literal Match](#determining-exact-literal-match)
127 * [Date and Time Value Formatting](#date-and-time-value-formatting)
128 * [The `:datetime` function](#the-datetime-function)
131 * [Style Options](#style-options)
132 * [Field Options](#field-options)
133 * [The `:date` function](#the-date-function)
136 * [The `:time` function](#the-time-function)
139 * [Date and Time Operands](#date-and-time-operands)
140 * [Formatting](#formatting)
141 * [Formatting Context](#formatting-context)
142 * [Expression and Markup Resolution](#expression-and-markup-resolution)
143 * [Literal Resolution](#literal-resolution)
144 * [Variable Resolution](#variable-resolution)
145 * [Function Resolution](#function-resolution)
146 * [Option Resolution](#option-resolution)
147 * [Markup Resolution](#markup-resolution)
148 * [Fallback Resolution](#fallback-resolution)
149 * [Pattern Selection](#pattern-selection)
150 * [Resolve Selectors](#resolve-selectors)
151 * [Resolve Preferences](#resolve-preferences)
152 * [Filter Variants](#filter-variants)
153 * [Sort Variants](#sort-variants)
155 * [Example 1](#example-1)
156 * [Example 2](#example-2)
157 * [Example 3](#example-3)
158 * [Formatting](#formatting)
160 * [Formatting Fallback Values](#formatting-fallback-values)
161 * [Handling Bidirectional Text](#handling-bidirectional-text)
162 * [Interchange Data Model](#interchange-data-model)
163 * [Messages](#messages)
170 * [Security Considerations](#security-considerations)
176 users with different languages and cultures is the need for **_<dfn>dynamic messages</dfn>_**.
181 > For example, if your US English (`en-US`) interface has a message like:
200 as well as user-defined formats and message selectors.
208 sections marked as non-normative,
214 described in BCP 14 \[[RFC2119](https://www.rfc-editor.org/rfc/rfc2119)\]
215 \[[RFC8174](https://www.rfc-editor.org/rfc/rfc8174)\] when, and only when, they
224 > Examples are non-normative and styled like this.
236 Updates to this specification MUST NOT specify an error for any message
237 that previously did not specify an error.
251 > The foregoing policies are _not_ a guarantee that the results of formatting will never change.
253 > the functions for date formatting, number formatting and so on
260 consisting of characters in the ranges a-z, A-Z, and 0-9.
275 > This stability policy allows any of the following, non-exhaustive list, of changes
277 > - Future versions may define new syntax and structures
279 > - Future versions may add additional structure or meaning to existing syntax.
280 > - Future versions may define new keywords.
281 > - Future versions may make previously invalid messages valid.
282 > - Future versions may define additional functions in the default registry
284 > - Future versions may define additional options to existing functions.
285 > - Future versions may define additional option values for existing options.
286 > - Future versions may deprecate (but not remove) keywords, functions, options, or option values.
287 > - Future versions of this specification may introduce changes
290 > - For example, a future version could introduce a new keyword,
302 _This section is non-normative._
309 … [pain points of ICU MessageFormat 1.0](https://github.com/unicode-org/message-format-wg/blob/main…
311 - _Non-Goal_: Be backwards-compatible with the ICU MessageFormat 1.0 syntax.
318 - _Non-Goal_: Make the syntax intuitive enough for non-technical translators to hand-edit.
329 - _Non-Goal_: Support unnecessary escape sequences, which would theirselves require
338 _This section is non-normative._
347 Note that this necessitates extra care when presenting messages for human consumption,
351 private-use code points (U+E000 through U+F8FF, U+F0000 through U+FFFFD, and
354 ## Messages and their Syntax
361 MessageFormat calls the template for a given formatting operation a _message_.
370 during the [formatting](#formatting) of a _message_ at runtime.
374 ### Well-formed vs. Valid Messages
376 A _message_ is **_<dfn>well-formed</dfn>_** if it satisfies all the rules of the grammar.
377 Attempting to parse a _message_ that is not _well-formed_ will result in a _Syntax Error_.
379 A _message_ is **_<dfn>valid</dfn>_** if it is _well-formed_ and
387 A **_<dfn>message</dfn>_** is the complete template for a specific message formatting request.
407 … a _message_. While many of the examples in this spec are written on multiple lines, the formatting
427 > with a left-to-right display order
429 > The syntax permits the use of right-to-left characters in _identifiers_,
436 > strongly-directional markers in both optional and required _whitespace_
447 message = simple-message / complex-message
451 with restrictions on its first non-whitespace character.
458 simple-message = o [simple-start pattern]
459 simple-start = simple-start-char / escaped-char / placeholder
474 complex-message = o *(declaration o) complex-body o
481 _Declarations_ are optional: many messages will not contain any _declarations_.
483 An **_<dfn>input-declaration</dfn>_** binds a _variable_ to an external input value.
484 The _variable-expression_ of an _input-declaration_
487 A **_<dfn>local-declaration</dfn>_** binds a _variable_ to the resolved value of an _expression_.
490 declaration = input-declaration / local-declaration
491 input-declaration = input o variable-expression
492 local-declaration = local s variable o "=" o expression
497 _Duplicate Declaration_ error during processing:
498 - A _declaration_ MUST NOT bind a _variable_
500 - An _input-declaration_ MUST NOT bind a _variable_
501 that appears anywhere within the _function_ of its _variable-expression_.
502 - A _local-declaration_ MUST NOT bind a _variable_ that appears in its _expression_.
504 A _local-declaration_ MAY overwrite an external input value as long as the
519 > (See the [Errors](#errors) section for examples of invalid messages)
527 complex-body = quoted-pattern / matcher
533 Unless there is an error, resolving a _message_ always results in the formatting
537 pattern = *(text-char / escaped-char / placeholder)
542 during the formatting process.
552 quoted-pattern = o "{{" pattern "}}"
572 In the ABNF, _text_ is represented by non-empty sequences of
573 `simple-start-char`, `text-char`, `escaped-char`, and `s`.
574 The production `simple-start-char` represents the first non-whitespace in a _simple message_
575 and matches `text-char` except for not allowing U+002E FULL STOP `.`.
576 The ABNF uses `content-char` as a shared base for _text_ and _quoted literal_ characters.
579 be preserved during formatting.
582 simple-start-char = content-char / "@" / "|"
583 text-char = content-char / ws / "." / "@" / "|"
584 quoted-char = content-char / ws / "." / "@" / "{" / "}"
585 content-char = %x01-08 ; omit NULL (%x00), HTAB (%x09) and LF (%x0A)
586 / %x0B-0C ; omit CR (%x0D)
587 / %x0E-1F ; omit SP (%x20)
588 / %x21-2D ; omit . (%x2E)
589 / %x2F-3F ; omit @ (%x40)
590 / %x41-5B ; omit \ (%x5C)
591 / %x5D-7A ; omit { | } (%x7B-7D)
592 / %x7E-2FFF ; omit IDEOGRAPHIC SPACE (%x3000)
593 / %x3001-D7FF ; omit surrogates
594 / %xE000-10FFFF
600 Otherwise, care must be taken to ensure that pattern-significant whitespace is preserved.
615 and which will be replaced during the formatting of a _message_.
624 of the _pattern_ to use for formatting.
632 as the template for the formatting process.
637 - _Variant Key Mismatch_:
639 - _Missing Fallback Variant_:
640 At least one _variant_ MUST exist whose _keys_ are all equal to the "catch-all" key `*`.
641 - _Missing Selector Annotation_:
644 - _Duplicate Variant_:
650 matcher = match-statement s variant *(o variant)
651 match-statement = match 1*(s selector)
674 which _pattern_ will be used during formatting.
723 variant = key *(s key) quoted-pattern
731 A _key_ can be either a _literal_ value or the "catch-all" key `*`.
733 The **_<dfn>catch-all key</dfn>_** is a special key, represented by `*`,
745 during the _message_'s formatting.
753 A **_<dfn>literal-expression</dfn>_** contains a _literal_,
756 A **_<dfn>variable-expression</dfn>_** contains a _variable_,
759 A **_<dfn>function-expression</dfn>_** contains a _function_ without an _operand_.
762 expression = literal-expression
763 / variable-expression
764 / function-expression
765 literal-expression = "{" o literal [s function] *(s attribute) o "}"
766 variable-expression = "{" o variable [s function] *(s attribute) o "}"
767 function-expression = "{" o function *(s attribute) o "}"
773 1. The value of a _local-declaration_
776 Additionally, an _input-declaration_ can contain a _variable-expression_.
793 > This placeholder contains a function expression with a variable-valued option: {:function option=…
798 An **_<dfn>operand</dfn>_** is the _literal_ of a _literal-expression_ or
799 the _variable_ of a _variable-expression_.
805 values during formatting.
835 An **_<dfn>option</dfn>_** is a key-value pair
848 and will produce a _Duplicate Option Name_ error during processing.
875 that can be used to represent non-language parts of a _message_,
884 **_<dfn>Markup-open</dfn>_** starts with U+0023 NUMBER SIGN `#` and
889 **_<dfn>Markup-standalone</dfn>_** starts with U+0023 NUMBER SIGN `#`
891 representing a self-closing or standalone element within the _message_.
894 **_<dfn>Markup-close</dfn>_** starts with U+002F SOLIDUS `/` and
912 …=|bold,italic|}Bold and italic{/ansi attr=|bold|} italic only {/ansi attr=|italic|} no formatting.}
915 A _markup-open_ can appear without a corresponding _markup-close_.
916 A _markup-close_ can appear without a corresponding _markup-open_.
925 During formatting, _attributes_ have no effect,
955 > Have a {#span @can-copy}great and wonderful{/span @can-copy} birthday!
981 as the _operand_ of a _literal-expression_,
1013 _Unquoted literals_ can contain a _name_ or consist of a _number-literal_.
1014 A _number-literal_ uses the same syntax as JSON and is intended for the encoding
1018 literal = quoted-literal / unquoted-literal
1019 quoted-literal = "|" *(quoted-char / escaped-char) "|"
1020 unquoted-literal = name / number-literal
1021 number-literal = ["-"] (%x30 / (%x31-39 *DIGIT)) ["." 1*DIGIT] [%i"e" ["-" / "+"] 1*DIGIT]
1031 to aid in presenting names that contain right-to-left or neutral characters.
1044 > Comparisons of _name_ values only need be done "as-if" normalization
1052 [NCName](https://www.w3.org/TR/xml-names/#NT-NCName).
1053 This is different from XML's [Name](https://www.w3.org/TR/xml/#NT-Name)
1068 Built-in _functions_ and their _options_ do not have a _namespace_ identifier.
1086 > An add-on function from the `icu` namespace:
1090 > An option and an add-on option:
1095 Support for _namespaces_ and their interpretation is implementation-defined
1104 name = [bidi] name-start *name-char [bidi]
1105 name-start = ALPHA / "_"
1106 / %xC0-D6 / %xD8-F6 / %xF8-2FF
1107 / %x370-37D / %x37F-61B / %x61D-1FFF / %x200C-200D
1108 / %x2070-218F / %x2C00-2FEF / %x3001-D7FF
1109 / %xF900-FDCF / %xFDF0-FFFC / %x10000-EFFFF
1110 name-char = name-start / DIGIT / "-" / "."
1111 / %xB7 / %x300-36F / %x203F-2040
1116 An **_<dfn>escape sequence</dfn>_** is a two-character sequence starting with
1124 escaped-char = backslash ( backslash / "{" / "|" / "}" )
1129 > The `escaped-char` rule allows escaping some characters in places where
1158 These can assist users in presenting _messages_ that contain right-to-left
1162 _Messages_ that contain right-to-left (aka RTL) characters SHOULD use one of the
1163 following mechanisms to make messages display intelligibly in plain-text editors:
1165 1. Use paired isolating bidi controls `U+2066 LEFT-TO-RIGHT ISOLATE` ("LRI")
1168 - _inside_ of _placeholder_ markers `{` and `}`
1169 - _outside_ _quoted-pattern_ markers `{{` and `}}`
1170 - _outside_ of _variable_, _function_, _markup_, or _attribute_,
1172 2. Use the 'local-effect' bidi marks
1173 `U+061C ARABIC LETTER MARK`, `U+200E LEFT-TO-RIGHT MARK` or
1174 `U+200F RIGHT-TO-LEFT MARK` as permitted by the ABNF before or after _identifiers_,
1183 > - do not put them inside of a _literal_ except when they are part of the value,
1185 > - do not put them inside quoted _patterns_ except when they are part of the text,
1187 > - do not put them outside _placeholders_,
1202 > encouraged to provide paired isolates around any right-to-left
1206 [UAX#31 Requirement R3a-2](https://www.unicode.org/reports/tr31/#R3a-2).
1207 It is a profile of R3a-1 in that specification because:
1208 - The following pattern whitespace characters are not allowed:
1214 - The character `U+3000 IDEOGRAPHIC SPACE`
1216 - The following directional marks and isolates
1219 `U+200E LEFT-TO-RIGHT MARK`,
1220 `U+200F RIGHT-TO-LEFT MARK`,
1221 `U+2066 LEFT-TO-RIGHT ISOLATE`,
1222 `U+2067 RIGHT-TO-LEFT ISOLATE`,
1242 bidi = %x061C / %x200E / %x200F / %x2066-2069
1251 using the ABNF notation [[STD68](https://www.rfc-editor.org/info/std68)],
1252 including the modifications found in [RFC 7405](https://www.rfc-editor.org/rfc/rfc7405).
1254 RFC7405 defines a variation of ABNF that is case-sensitive.
1256 [RFC 5234](https://www.rfc-editor.org/rfc/rfc5234).
1269 message = simple-message / complex-message
1271 simple-message = o [simple-start pattern]
1272 simple-start = simple-start-char / escaped-char / placeholder
1273 pattern = *(text-char / escaped-char / placeholder)
1276 complex-message = o *(declaration o) complex-body o
1277 declaration = input-declaration / local-declaration
1278 complex-body = quoted-pattern / matcher
1280 input-declaration = input o variable-expression
1281 local-declaration = local s variable o "=" o expression
1283 quoted-pattern = o "{{" pattern "}}"
1285 matcher = match-statement s variant *(o variant)
1286 match-statement = match 1*(s selector)
1288 variant = key *(s key) quoted-pattern
1292 expression = literal-expression
1293 / variable-expression
1294 / function-expression
1295 literal-expression = "{" o literal [s function] *(s attribute) o "}"
1296 variable-expression = "{" o variable [s function] *(s attribute) o "}"
1297 function-expression = "{" o function *(s attribute) o "}"
1310 literal = quoted-literal / unquoted-literal
1311 quoted-literal = "|" *(quoted-char / escaped-char) "|"
1312 unquoted-literal = name / number-literal
1313 ; number-literal matches JSON number (https://www.rfc-editor.org/rfc/rfc8259#section-6)
1314 number-literal = ["-"] (%x30 / (%x31-39 *DIGIT)) ["." 1*DIGIT] [%i"e" ["-" / "+"] 1*DIGIT]
1316 ; Keywords; Note that these are case-sensitive
1322 ; identifier matches https://www.w3.org/TR/REC-xml-names/#NT-QName
1323 ; name matches https://www.w3.org/TR/REC-xml-names/#NT-NCName but excludes U+FFFD and U+061C
1326 name = [bidi] name-start *name-char [bidi]
1327 name-start = ALPHA / "_"
1328 / %xC0-D6 / %xD8-F6 / %xF8-2FF
1329 / %x370-37D / %x37F-61B / %x61D-1FFF / %x200C-200D
1330 / %x2070-218F / %x2C00-2FEF / %x3001-D7FF
1331 / %xF900-FDCF / %xFDF0-FFFC / %x10000-EFFFF
1332 name-char = name-start / DIGIT / "-" / "."
1333 / %xB7 / %x300-36F / %x203F-2040
1336 simple-start-char = content-char / "@" / "|"
1337 text-char = content-char / ws / "." / "@" / "|"
1338 quoted-char = content-char / ws / "." / "@" / "{" / "}"
1339 content-char = %x01-08 ; omit NULL (%x00), HTAB (%x09) and LF (%x0A)
1340 / %x0B-0C ; omit CR (%x0D)
1341 / %x0E-1F ; omit SP (%x20)
1342 / %x21-2D ; omit . (%x2E)
1343 / %x2F-3F ; omit @ (%x40)
1344 / %x41-5B ; omit \ (%x5C)
1345 / %x5D-7A ; omit { | } (%x7B-7D)
1346 / %x7E-2FFF ; omit IDEOGRAPHIC SPACE (%x3000)
1347 / %x3001-D7FF ; omit surrogates
1348 / %xE000-10FFFF
1351 escaped-char = backslash ( backslash / "{" / "|" / "}" )
1362 bidi = %x061C / %x200E / %x200F / %x2066-2069
1375 Other errors might be detected during selection or formatting of a given _message_.
1379 ## Error Handling
1383 The other error categories are only emitted during formatting,
1386 During selection and formatting,
1394 When formatting a _message_ with one or more errors,
1397 The exact form of error signaling is implementation defined.
1399 returning an error code,
1405 such as when a _placeholder_'s _expression_ produced an error
1406 during formatting.
1408 The two above requirements MAY be fulfilled by a single formatting method,
1411 When a message contains more than one error,
1412 or contains some error which leads to further errors,
1416 When an error occurs while resolving a _selector_
1418 the _selector_ MUST NOT match any _variant_ _key_ other than the catch-all `*`
1419 and a _Bad Selector_ error MUST be emitted.
1423 **_<dfn>Syntax Errors</dfn>_** occur when the syntax representation of a message is not _well-forme…
1425 > Example invalid messages resulting in a _Syntax Error_:
1453 > Example invalid messages resulting in a _Variant Key Mismatch_ error:
1473 A **_<dfn>Missing Fallback Variant</dfn>_** error occurs when the message
1474 does not include a _variant_ with only catch-all keys.
1476 > Example invalid messages resulting in a _Missing Fallback Variant_ error:
1495 A **_<dfn>Missing Selector Annotation</dfn>_** error occurs when the _message_
1499 > Examples of invalid messages resulting in a _Missing Selector Annotation_ error:
1523 A **_<dfn>Duplicate Declaration</dfn>_** error occurs when a _variable_ is declared more than once.
1525 so explicitly declaring it after such use is also an error.
1527 > Examples of invalid messages resulting in a _Duplicate Declaration_ error:
1547 > .local $var = {$error}
1548 > .local $var2 = {$var2 :error}
1554 A **_<dfn>Duplicate Option Name</dfn>_** error occurs when the same _identifier_
1555 appears on the left-hand side of more than one _option_ in the same _expression_.
1557 > Examples of invalid messages resulting in a _Duplicate Option Name_ error:
1570 A **_<dfn>Duplicate Variant</dfn>_** error occurs when the
1573 > Examples of invalid messages resulting in a _Duplicate Variant_ error:
1599 An **_<dfn>Unresolved Variable</dfn>_** error occurs when a variable reference cannot be resolved.
1601 > For example, attempting to format either of the following messages
1602 > would result in an _Unresolved Variable_ error if done within a context that
1618 An **_<dfn>Unknown Function</dfn>_** error occurs when an _expression_ includes
1621 > For example, attempting to format either of the following messages
1622 > would result in an _Unknown Function_ error if done within a context that
1638 A **_<dfn>Bad Selector</dfn>_** error occurs when a message includes a _selector_
1642 > would result in a _Bad Selector_ error:
1645 > .local $day = {|2024-05-01| :date}
1652 A **_<dfn>Message Function Error</dfn>_** is any error that occurs
1657 (or cause to be emitted) any of the types of error defined in this section.
1658 Implementations MAY also provide implementation-defined _Message Function Error_ types.
1660 > For example, attempting to format any of the following messages
1691 A **_<dfn>Bad Operand</dfn>_** error is any error that occurs due to the content or format of the _…
1693 expected implementation-defined types for that function;
1695 and thus cannot be processed into one of the expected implementation-defined types
1698 > For example, the following _messages_ each produce a _Bad Operand_ error
1699 > because the literal `|horse|` does not match the `number-literal` production,
1716 A **_<dfn>Bad Option</dfn>_** error is an error that occurs when there is
1717 an implementation-defined error with an _option_ or its value.
1719 - A required _option_ is missing.
1720 - Mutually exclusive _options_ are supplied.
1721 - An _option_ value provided to a _function_ during _function resolution_
1722 does not match one of the implementation-defined types or values for that _function_;
1725 implementation-defined types for that specific _function_.
1727 > For example, the following _message_ might produce a _Bad Option_ error
1728 > because the literal `foo` does not match the production `digit-size-option`,
1737 A **_<dfn>Bad Variant Key</dfn>_** error is an error that occurs when a _variant_ _key_
1738 does not match the expected implementation-defined format.
1740 > For example, the following _message_ produces a _Bad Variant Key_ error
1742 > does not match the `number-literal` production,
1764 > The [Stability Policy](/spec#stability-policy) allows for updates to
1767 > it is possible to write messages using options not defined below
1768 > which currently format with no error, but which could produce errors
1772 ## String Value Selection and Formatting
1776 The function `:string` provides string selection and formatting.
1780 The _operand_ of `:string` is either any implementation-defined type
1783 All other values produce a _Bad Operand_ error.
1788 > as the "implementation-defined types".
1806 When implementing [`MatchSelectorKeys(resolvedSelector, keys)`](#resolve-preferences)
1826 > See also: [String Matching](https://www.w3.org/TR/charmod-norm)
1842 #### Formatting subsubsection
1846 ## Numeric Value Selection and Formatting
1854 The function `:number` requires a [Number Operand](#number-operands) as its _operand_.
1859 The defaults for these options are implementation-dependent.
1865 > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/N…
1869 - `select`
1870 …- `plural` (default; see [Default Value of `select` Option](#default-value-of-select-option) belo…
1871 - `ordinal`
1872 - `exact`
1873 - `compactDisplay` (this option only has meaning when combined with the option `notation=compact`)
1874 - `short` (default)
1875 - `long`
1876 - `notation`
1877 - `standard` (default)
1878 - `scientific`
1879 - `engineering`
1880 - `compact`
1881 - `numberingSystem`
1882 …- valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html…
1883 (default is locale-specific)
1884 - `signDisplay`
1885 - `auto` (default)
1886 - `always`
1887 - `exceptZero`
1888 - `negative`
1889 - `never`
1890 - `style`
1891 - `decimal` (default)
1892 - `percent` (see [Percent Style](#percent-style) below)
1893 - `useGrouping`
1894 - `auto` (default)
1895 - `always`
1896 - `never`
1897 - `min2`
1898 - `minimumIntegerDigits`
1899 - ([digit size option](#digit-size-options), default: `1`)
1900 - `minimumFractionDigits`
1901 - ([digit size option](#digit-size-options))
1902 - `maximumFractionDigits`
1903 - ([digit size option](#digit-size-options))
1904 - `minimumSignificantDigits`
1905 - ([digit size option](#digit-size-options))
1906 - `maximumSignificantDigits`
1907 - ([digit size option](#digit-size-options))
1916 - `currency`
1917 - `unit`
1922 - `currency`
1923 …- valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#Unic…
1925 - `currencyDisplay`
1926 - `symbol` (default)
1927 - `narrowSymbol`
1928 - `code`
1929 - `name`
1930 - `currencySign`
1931 - `accounting`
1932 - `standard` (default)
1933 - `unit`
1934 - (anything not empty)
1935 - `unitDisplay`
1936 - `long`
1937 - `short` (default)
1938 - `narrow`
1964 MUST be multiplied by 100 for the purposes of formatting.
1975 The _function_ `:number` performs selection as described in [Number Selection](#number-selection) b…
1979 The function `:integer` is a selector and formatter for matching or formatting numeric
1984 The function `:integer` requires a [Number Operand](#number-operands) as its _operand_.
1990 The defaults for these options are implementation-dependent.
1996 > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/N…
2001 - `select`
2002 - `plural` (default)
2003 - `ordinal`
2004 - `exact`
2005 - `numberingSystem`
2006 …- valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html…
2007 (default is locale-specific)
2008 - `signDisplay`
2009 - `auto` (default)
2010 - `always`
2011 - `exceptZero`
2012 - `negative`
2013 - `never`
2014 - `style`
2015 - `decimal` (default)
2016 - `percent` (see [Percent Style](#percent-style) below)
2017 - `useGrouping`
2018 - `auto` (default)
2019 - `always`
2020 - `min2`
2021 - `minimumIntegerDigits`
2022 - ([digit size option](#digit-size-options), default: `1`)
2023 - `maximumSignificantDigits`
2024 - ([digit size option](#digit-size-options))
2033 - `currency`
2034 - `unit`
2039 - `currency`
2040 …- valid [Unicode Currency Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#Unic…
2042 - `currencyDisplay`
2043 - `symbol` (default)
2044 - `narrowSymbol`
2045 - `code`
2046 - `name`
2047 - `currencySign`
2048 - `accounting`
2049 - `standard` (default)
2050 - `unit`
2051 - (anything not empty)
2052 - `unitDisplay`
2053 - `long`
2054 - `short` (default)
2055 - `narrow`
2081 MUST be multiplied by 100 for the purposes of formatting.
2092 The _function_ `:integer` performs selection as described in [Number Selection](#number-selection) …
2096 The _operand_ of a number function is either an implementation-defined type or
2097 a literal whose contents match the `number-literal` production in the [ABNF](/spec/message.abnf).
2098 All other values produce a _Bad Operand_ error.
2102 > might be considered as the "implementation-defined numeric types".
2109 > contents match the `number-literal` production in the [ABNF](/spec/message.abnf).
2112 > `-1234.567`, it would behave identically to the local
2115 > .local $example = {|-1234.567| :number}
2121 > that provide additional semantic meaning to the formatting of number-like values.
2139 encodes the value as a non-negative integer.
2140 Implementations MAY also accept implementation-defined types as the value.
2143 > digit-size-option = "0" / (("1"-"9") [DIGIT])
2146 If the value of a digit size option does not evaluate as a non-negative integer,
2147 or if the value exceeds any implementation-defined upper limit
2148 or any option-specific lower limit, a _Bad Option Error_ is emitted.
2153 - `exact` selection matches the operand to explicit numeric keys exactly
2154 - `plural` selection matches the operand to explicit numeric keys exactly
2156 - `ordinal` selection matches the operand to explicit numeric keys exactly
2159 When implementing [`MatchSelectorKeys(resolvedSelector, keys)`](#resolve-preferences)
2165 (See [Determining Exact Literal Match](#determining-exact-literal-match) for details)
2166 1. Let `keyword` be a string which is the result of [rule selection](#rule-selection) on `resolvedS…
2170 1. If the value of `key` matches the production `number-literal`, then
2176 1. Else, emit a _Bad Variant Key_ error.
2188 If the _option_ `select` is set to `exact`, rule-based selection is not used.
2197 The meaning of the keywords is locale-dependent and implementation-defined.
2198 A _key_ that matches the rule-selected keyword is a stronger match than the fallback key `*`
2233 > |---|---|---|
2244 > The exact behavior of exact literal match is currently only well defined for non-zero-filled
2247 > implementation-defined ways.
2252 [format defined for a JSON number](https://www.rfc-editor.org/rfc/rfc8259#section-6).
2259 > [open issues](https://github.com/unicode-org/message-format-wg/issues/675)
2262 > and since the effect of formatting options, such as the number of fraction
2266 > [being considered](https://github.com/unicode-org/message-format-wg/pull/859).
2268 > Users should avoid creating messages that depend on exact matching of non-integer
2272 ## Date and Time Value Formatting
2274 This subsection describes the functions and options for date/time formatting.
2286 the ability to compose user-specified combinations of fields.
2289 - `{$d :datetime}` is the same as `{$d :datetime dateStyle=medium timeStyle=short}`
2292 > The default formatting behavior of `:datetime` is inconsistent with `Intl.DateTimeFormat`
2299 an implementation-defined date/time type
2300 or a _date/time literal value_, as defined in [Date and Time Operand](#date-and-time-operands).
2301 All other _operand_ values produce a _Bad Operand_ error.
2309 If both are specified, a _Bad Option_ error MUST be emitted
2314 > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/D…
2320 - `dateStyle`
2321 - `full`
2322 - `long`
2323 - `medium`
2324 - `short`
2325 - `timeStyle`
2326 - `full`
2327 - `long`
2328 - `medium`
2329 - `short`
2345 > The value `2-digit` for some _field options_ **must** be quoted
2347 > but does not match the `number-literal` production in the ABNF.
2349 > .local $correct = {$someDate :datetime year=|2-digit|}
2350 > .local $syntaxError = {$someDate :datetime year=2-digit}
2354 - `weekday`
2355 - `long`
2356 - `short`
2357 - `narrow`
2358 - `era`
2359 - `long`
2360 - `short`
2361 - `narrow`
2362 - `year`
2363 - `numeric`
2364 - `2-digit`
2365 - `month`
2366 - `numeric`
2367 - `2-digit`
2368 - `long`
2369 - `short`
2370 - `narrow`
2371 - `day`
2372 - `numeric`
2373 - `2-digit`
2374 - `hour`
2375 - `numeric`
2376 - `2-digit`
2377 - `minute`
2378 - `numeric`
2379 - `2-digit`
2380 - `second`
2381 - `numeric`
2382 - `2-digit`
2383 - `fractionalSecondDigits`
2384 - `1`
2385 - `2`
2386 - `3`
2387 - `hourCycle` (default is locale-specific)
2388 - `h11`
2389 - `h12`
2390 - `h23`
2391 - `h24`
2392 - `timeZoneName`
2393 - `long`
2394 - `short`
2395 - `shortOffset`
2396 - `longOffset`
2397 - `shortGeneric`
2398 - `longGeneric`
2402 > as overrides for locale-and-value dependent implementation-defined defaults.
2407 - `calendar` (default is locale-specific)
2408 …- valid [Unicode Calendar Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#Unic…
2409 - `numberingSystem` (default is locale-specific)
2410 …- valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html…
2411 - `timeZone` (default is system default time zone or UTC)
2412 - valid identifier per [BCP175](https://www.rfc-editor.org/rfc/rfc6557)
2419 - `{$d :date}` is the same as `{$d :date style=medium}`
2424 an implementation-defined date/time type
2425 or a _date/time literal value_, as defined in [Date and Time Operand](#date-and-time-operands).
2426 All other _operand_ values produce a _Bad Operand_ error.
2431 - `style`
2432 - `full`
2433 - `long`
2434 - `medium` (default)
2435 - `short`
2442 - `{$t :time}` is the same as `{$t :time style=short}`
2447 an implementation-defined date/time type
2448 or a _date/time literal value_, as defined in [Date and Time Operand](#date-and-time-operands).
2449 All other _operand_ values produce a _Bad Operand_ error.
2454 - `style`
2455 - `full`
2456 - `long`
2457 - `medium`
2458 - `short` (default)
2464 an implementation-defined date/time type
2466 All other _operand_ values produce a _Bad Operand_ error.
2468 A **_<dfn>date/time literal value</dfn>_** is a non-empty string consisting of an ISO 8601 date,
2476 …!0000)[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])(T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](…
2488 > a _Bad Operand_ error at runtime.
2496 > `2024-02-06T16:40:00Z`, it would behave identically to the local
2499 > .local $example = {|2024-02-06T16:40:00Z| :datetime}
2507 > Support for these extensions is expected to be required in the post-tech preview.
2508 > See: https://datatracker.ietf.org/doc/draft-ietf-sedate-datetime-extended/
2511 ## Formatting section in Unicode Locale Data Markup Language (LDML)<br/>Part 9: Message Format
2514 when formatting a message for display in a user interface, or for some later processing.
2518 If the resulting _message_ is not _well-formed_, a _Syntax Error_ is emitted.
2519 If the resulting _message_ is _well-formed_ but is not _valid_, a _Data Model Error_ is emitted.
2521 The formatting of a _message_ is defined by the following operations:
2523 - **_<dfn>Pattern Selection</dfn>_** determines which of a message's _patterns_ is formatted.
2527 - **_<dfn>Formatting</dfn>_** takes the resolved values of the selected _pattern_,
2532 - **_<dfn>Expression and Markup Resolution</dfn>_** determines the value of an _expression_ or _mar…
2535 such as looking up the value of a variable and calling formatting functions.
2539 by the eventual formatting.
2559 > parsing, processing, or formatting.
2562 > selection or formatting process.
2568 ## Formatting Context
2570 A message's **_<dfn>formatting context</dfn>_** represents the data and procedures that are required
2575 - Information on the current **_locale_**,
2577 This will be passed on to formatting functions.
2579 - Information on the base directionality of the _message_ and its _text_ tokens.
2583 - An **_<dfn>input mapping</dfn>_** of string identifiers to values,
2585 This is often determined by a user-provided argument of a formatting function call.
2587 - The _function registry_,
2590 - Optionally, a fallback string to use for the message if it is not _valid_.
2604 In an _input-declaration_, the _variable_ operand of the _variable-expression_
2606 but also the _variable_ to which the resolved value of the _variable-expression_ is bound.
2610 The form that resolved values take is implementation-dependent,
2660 > .local $aDate = {|2023-08-30| :datetime}
2672 or on the right-hand side of an _option_,
2673 the formatting function MUST treat its resolved value the same
2690 If this happens, an _Unresolved Variable_ error is emitted.
2705 emit an _Unknown Function_ error
2715 - The current _locale_.
2716 - The resolved mapping of _options_.
2717 - If the _expression_ includes an _operand_, its resolved value.
2719 The form that resolved _operand_ and _option_ values take is implementation-defined.
2745 Such an interface SHOULD define an implementation-specific
2750 _Bad Operand_ error for _operands_ whose resolved value
2755 > currently implementation-dependent. Supposing that
2766 > is currently implementation-dependent.
2797 Function access to the _formatting context_ MUST be minimal and read-only,
2800 Implementation-defined _functions_ SHOULD use an implementation-defined _namespace_.
2812 the _function_ might cause a _Bad Operand_ error to be emitted.
2822 - Resolve the _identifier_ of the _option_.
2823 - If the _option_'s right-hand side successfully resolves to a value,
2825 - Otherwise, bind the _identifier_ of the _option_ to an unresolved value in the mapping.
2827 (Note that an _Unresolved Variable_ error will have been emitted.)
2839 - The type of the markup: open, standalone, or close
2840 - The _identifier_ of the _markup_
2841 - The resolved _options_ values after _option resolution_.
2851 - A _variable_ used as an _operand_ (with or without a _function_) fails to resolve.
2853 - A _function_ fails to resolve.
2857 - _expression_ with a _literal_ _operand_ (either quoted or unquoted)
2868 - _expression_ with _variable_ _operand_ referring to a local _declaration_ (with or without a _fun…
2885 - _expression_ with _variable_ _operand_ not referring to a local _declaration_ (with or without a …
2896 - _function_ _expression_ with no _operand_:
2903 - Otherwise: the U+FFFD REPLACEMENT CHARACTER `�`
2913 If the _message_ being formatted is not _well-formed_ and _valid_,
2923 to provide the _pattern_ for the formatting operation.
2975 The remaining _variants_ are sorted according to the _selector_'s _key_-ordering preference.
2979 the earliest-sorted _variant_ in the remaining list of _variants_ is selected.
2997 1. Emit a _Bad Selector_ error.
3011 1. If `key` is not the catch-all key `'*'`:
3024 The most-preferred key is first,
3030 If calling MatchSelectorKeys encounters any error,
3031 a _Bad Selector_ error is emitted
3043 1. If `key` is the catch-all key `'*'`:
3060 1. Let `tuple` be a new tuple (-1, `var`).
3063 1. Let `i` be `len` - 1.
3070 1. If `key` is not the catch-all key `'*'`:
3076 1. Set `i` to be `i` - 1.
3095 _This section is non-normative._
3101 and a formatting context in which
3128 The catch-all keys of the third variant `* *` always match, and this is added to `vars`,<br>
3136 Alternatively, with the same implementation and formatting context as in Example 1,
3160 The keys of all variants either match each selector exactly, or via the catch-all key,<br>
3178 A more-complex example is the matching found in selection APIs
3198 The value of the selector is resolved to an implementation-defined value
3205 The keys of all variants are included in the list of matching keys, or use the catch-all key,<br>
3217 ## Formatting section in Unicode Locale Data Markup Language (LDML)<br/>Part 9: Message Format
3223 When such an error occurs during _formatting_,
3225 a _fallback value_ is used for the _placeholder_ with the error.
3230 - A single string concatenated from the parts of the resolved _pattern_.
3231 - A string with associated attributes for portions of its text.
3232 - A flat sequence of objects corresponding to each resolved value.
3233 - A hierarchical structure of objects that group spans of resolved values,
3234 such as sequences delimited by _markup-open_ and _markup-close_ _placeholders_.
3237 including situations that require further processing of formatted messages.
3241 When formatting to a string, the default representation of all _markup_
3244 such as by emitting XML-ish tags for each _markup_.
3248 _This section is non-normative._
3260 ### Formatting Fallback Values argument
3263 and the formatting result is a concatenated string or a sequence of strings,
3270 > a _message_ that is not _well-formed_ would format to a string as `{�}`,
3277 [bidirectional text](https://www.w3.org/TR/i18n-glossary/#dfn-bidirectional-text).
3278 That is, the text can can consist of a mixture of left-to-right and right-to-left spans of text.
3287 > and the syntax of _message_ prior to formatting.
3298 [spillover effects](https://www.w3.org/TR/i18n-glossary/#dfn-spillover-effects).
3299 Applying [bidi isolation](https://www.w3.org/TR/i18n-glossary/#dfn-bidi-isolation)
3304 If an implementation supports formatting to something other than a string
3312 > For example, an implementation could provide a `:currency` formatting function
3313 > which inserts strongly directional characters, such as U+200F RIGHT-TO-LEFT MARK (RLM),
3314 > U+200E LEFT-TO-RIGHT MARK (LRM), or U+061C ARABIC LETTER MARKER (ALM),
3316 > An example of this is formatting the value `-1234.56` as the currency `AED`
3317 > in the `ar-AE` locale. The formatted value appears like this:
3319 > -1,234.56 د.إ.
3332 It is primarily intended for use in plain-text strings, where markup or other mechanisms
3345 These correspond to the message having left-to-right directionality,
3346 right-to-left directionality, and to the message's directionality not being known.
3355 prefix `fmt` with U+2066 LEFT-TO-RIGHT ISOLATE
3359 prefix `fmt` with U+2067 RIGHT-TO-LEFT ISOLATE
3373 …lementations are not required to use this data model for their internal representation of messages.
3379 This includes mapping legacy formatting syntaxes (such as MessageFormat 1)
3388 - any MessageFormat 2.0 message can be parsed into this representation
3389 - this data model representation can be serialized as a well-formed
3391 - parsing a MessageFormat 2.0 message into a data model representation
3395 - parse a non-MessageFormat 2 message into a data model
3396 (and therefore re-serialize it as MessageFormat 2).
3398 - re-serialize a MessageFormat 2 message into some other format
3399 including (but not limited to) other formatting syntaxes
3406 - `common/dtd/messageFormat/message.json` is a JSON Schema definition,
3408 - `common/dtd/messageFormat/message.dtd` is a document type definition (DTD),
3417 > Users relying on XML representations of messages should note that
3418 > XML 1.0 does not allow for the representation of all C0 control characters (U+0000-U+001F).
3419 > Except for U+0000 NULL , these characters are allowed in MessageFormat 2 messages,
3421 > might need to supply an alternate escape mechanism to support messages
3434 ## Messages section in Unicode Locale Data Markup Language (LDML)<br/>Part 9: Message Format
3505 Each element of the `Pattern` MUST either be a non-empty string, an `Expression`, or a `Markup` obj…
3574 `Options` is a key-value mapping containing options,
3593 The `options` for markup use the same key-value mapping as `FunctionRef`.
3607 `Attributes` is a key-value mapping
3629 This is intended to allow for the representation of "junk" or invalid content within messages.
3658 Bidirectional text containing right-to-left characters (such as used for Arabic or Hebrew)
3661 keywords and symbols that are left-to-right or consist of neutral characters
3663 it is possible to create messages that,
3670 MessageFormat 2.0 implementations might allow end-users to install
3671 _selectors_, _functions_, or _markup_ from third-party sources.
3676 In addition, end-users need to be aware of the risks involved.
3732 This publication is provided “AS-IS” without charge as a convenience to users.