|
2 | 2 |
|
3 | 3 | ## Table of Contents |
4 | 4 |
|
5 | | -1. [Introduction](#introduction) |
6 | | - 1. [Conformance](#conformance) |
7 | | - 1. [Terminology and Conventions](#terminology-and-conventions) |
8 | | - 1. [Stability Policy](#stability-policy) |
| 5 | +1. [Introduction](intro.md) |
| 6 | + 1. [Conformance](intro.md#conformance) |
| 7 | + 1. [Terminology and Conventions](intro.md#terminology-and-conventions) |
| 8 | + 1. [Stability Policy](intro.md#stability-policy) |
9 | 9 | 1. [Syntax](syntax.md) |
10 | | - 1. [Productions](syntax.md#productions) |
11 | | - 1. [Tokens](syntax.md#tokens) |
12 | 10 | 1. [`message.abnf`](message.abnf) |
| 11 | +1. [Formatting](formatting.md) |
13 | 12 | 1. [Errors](errors.md) |
14 | | - 1. [Error Handling](errors.md#error-handling) |
15 | | - 1. [Syntax Errors](errors.md#syntax-errors) |
16 | | - 1. [Data Model Errors](errors.md#data-model-errors) |
17 | | - 1. [Resolution Errors](errors.md#resolution-errors) |
18 | | - 1. [Message Function Errors](errors.md#message-function-errors) |
19 | 13 | 1. [Default Function Registry](registry.md) |
20 | 14 | 1. [`u:` Namespace](u-namespace.md) |
21 | | -1. [Formatting](formatting.md) |
22 | 15 | 1. [Interchange data model](data-model/README.md) |
| 16 | +1. [Appendices](appendices.md) |
| 17 | + 1. [Security Considerations](appendices.md#security-considerations) |
| 18 | + 1. [Acknowledgements](appendices.md#acknowledgements) |
23 | 19 |
|
24 | | -## Introduction |
25 | | - |
26 | | -One of the challenges in adapting software to work for |
27 | | -users with different languages and cultures is the need for **_<dfn>dynamic messages</dfn>_**. |
28 | | -Whenever a user interface needs to present data as part of a larger string, |
29 | | -that data needs to be formatted (and the message may need to be altered) |
30 | | -to make it culturally accepted and grammatically correct. |
| 20 | +## What is MessageFormat 2? |
31 | 21 |
|
32 | | -> For example, if your US English (`en-US`) interface has a message like: |
33 | | -> |
34 | | -> > Your item had 1,023 views on April 3, 2023 |
35 | | -> |
36 | | -> You want the translated message to be appropriately formatted into French: |
37 | | -> |
38 | | -> > Votre article a eu 1 023 vues le 3 avril 2023 |
39 | | -> |
40 | | -> Or Japanese: |
41 | | -> |
42 | | -> > あなたのアイテムは 2023 年 4 月 3 日に 1,023 回閲覧されました。 |
| 22 | +Software needs to construct messages that incorporate various pieces of information. |
| 23 | +The complexities of the world's languages make this challenging. |
| 24 | +MessageFormat 2 defines the data model, syntax, processing, and conformance requirements |
| 25 | +for the next generation of dynamic messages. |
| 26 | +It is intended for adoption by programming languages, software libraries, and software localization tooling. |
| 27 | +It enables the integration of internationalization APIs (such as date or number formats), |
| 28 | +and grammatical matching (such as plurals or genders). |
| 29 | +It is extensible, allowing software developers to create formatting |
| 30 | +or message selection logic that add on to the core capabilities. |
| 31 | +Its data model provides a means of representing existing syntaxes, |
| 32 | +thus enabling gradual adoption by users of older formatting systems. |
43 | 33 |
|
44 | | -This specification defines the |
45 | | -data model, syntax, processing, and conformance requirements |
46 | | -for the next generation of _dynamic messages_. |
47 | | -It is intended for adoption by programming languages and APIs. |
48 | | -This will enable the integration of |
49 | | -existing internationalization APIs (such as the date and number formats shown above), |
50 | | -grammatical matching (such as plurals or genders), |
51 | | -as well as user-defined formats and message selectors. |
| 34 | +The goal is to allow developers and translators to create natural-sounding, grammatically-correct, |
| 35 | +user interfaces that can appear in any language and support the needs of diverse cultures. |
52 | 36 |
|
53 | | -The document is the successor to ICU MessageFormat, |
54 | | -henceforth called ICU MessageFormat 1.0. |
| 37 | +## MessageFormat 2 Specification and Syntax |
55 | 38 |
|
56 | | -### Conformance |
| 39 | +The current specification starts [here](#table-of-contents) and may have changed since the publication |
| 40 | +of the Tech Preview version. |
| 41 | +The Tech Preview specification is [here](https://www.unicode.org/reports/tr35/tr35-73/tr35-messageFormat.html) |
57 | 42 |
|
58 | | -Everything in this specification is normative except for: |
59 | | -sections marked as non-normative, |
60 | | -all authoring guidelines, diagrams, examples, and notes. |
| 43 | +The current draft syntax for defining messages can be found in [spec/syntax.md](./syntax.md). |
| 44 | +The syntax is formally described in [ABNF](./message.abnf). |
61 | 45 |
|
62 | | -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL |
63 | | -NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", |
64 | | -"MAY", and "OPTIONAL" in this document are to be interpreted as |
65 | | -described in BCP 14 \[[RFC2119](https://www.rfc-editor.org/rfc/rfc2119)\] |
66 | | -\[[RFC8174](https://www.rfc-editor.org/rfc/rfc8174)\] when, and only when, they |
67 | | -appear in all capitals, as shown here. |
| 46 | +Messages can be simple strings: |
68 | 47 |
|
69 | | -### Terminology and Conventions |
| 48 | + Hello, world! |
70 | 49 |
|
71 | | -A **_term_** looks like this when it is defined in this specification. |
| 50 | +Messages can interpolate arguments: |
72 | 51 |
|
73 | | -A reference to a _term_ looks like this. |
| 52 | + Hello {$user}! |
74 | 53 |
|
75 | | -> Examples are non-normative and styled like this. |
| 54 | +Messages can transform those arguments using _formatting functions_. |
| 55 | +Functions can optionally take _options_: |
76 | 56 |
|
77 | | -> [!IMPORTANT] |
78 | | -> Text marked "Important" like this are normative. |
| 57 | + Today is {$date :datetime} |
| 58 | + Today is {$date :datetime weekday=long}. |
79 | 59 |
|
80 | | -> [!NOTE] |
81 | | -> Notes are non-normative. |
| 60 | +Messages can use a _selector_ to choose between different _variants_, |
| 61 | +which correspond to the grammatical (or other) requirements of the language: |
82 | 62 |
|
83 | | -### Stability Policy |
| 63 | + .input {$count :integer} |
| 64 | + .match $count |
| 65 | + 0 {{You have no notifications.}} |
| 66 | + one {{You have {$count} notification.}} |
| 67 | + * {{You have {$count} notifications.}} |
84 | 68 |
|
85 | | -> [!IMPORTANT] |
86 | | -> The provisions of the stability policy are not in effect until |
87 | | -> the conclusion of the technical preview and adoption of this specification. |
| 69 | +Messages can annotate arguments with formatting instructions |
| 70 | +or assign local values for use in the formatted message: |
88 | 71 |
|
89 | | -Updates to this specification will not make any valid _message_ invalid. |
| 72 | + .input {$date :datetime weekday=long month=medium day=short} |
| 73 | + .local $numPigs = {$pigs :integer} |
| 74 | + {{On {$date} you had this many pigs: {$numPigs}}} |
90 | 75 |
|
91 | | -Updates to this specification will not remove any syntax provided in this version. |
| 76 | +The message syntax supports using multiple _selectors_ and other features |
| 77 | +to build complex messages. |
| 78 | +It is designed so that implementations can extend the set of functions or their options |
| 79 | +using the same syntax. |
| 80 | +Implementations may even support users creating their own functions. |
92 | 81 |
|
93 | | -Updates to this specification will not specify an _error_ for any _message_ |
94 | | -that previously did not specify an _error_. |
| 82 | +See more examples and the formal definition of the grammar in [spec/syntax.md](./syntax.md). |
95 | 83 |
|
96 | | -Updates to this specification will not specify the use of a _fallback value_ for any _message_ |
97 | | -that previously did not specify a _fallback value_. |
| 84 | +## Developer Documentation |
98 | 85 |
|
99 | | -Updates to this specification will not change the syntactical meaning |
100 | | -of any syntax defined in this specification. |
| 86 | +Unofficial documentation for developers on MessageFormat 2 syntax and on using it with |
| 87 | +various programming languages can be found at [messageformat.dev](https://messageformat.dev/), |
| 88 | +which also includes an interactive [playground](https://messageformat.dev/playground/) |
| 89 | +for experimenting with message syntax. |
101 | 90 |
|
102 | | -Updates to this specification will not remove any _functions_ defined in the default function registry. |
| 91 | +## Implementations |
103 | 92 |
|
104 | | -Updates to this specification will not remove any _options_ or _option_ values |
105 | | -defined in the default function registry. |
| 93 | +- Java: [`com.ibm.icu.message2`](https://unicode-org.github.io/icu-docs/apidoc/dev/icu4j/index.html?com/ibm/icu/message2/package-summary.html), part of ICU 76, is a _tech preview_ implementation of the MessageFormat 2 syntax, together with a formatting API. See the [ICU User Guide](https://unicode-org.github.io/icu/userguide/format_parse/messages/mf2.html) for examples and a quickstart guide. |
| 94 | +- C/C++: [`icu::message2::MessageFormatter`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1message2_1_1MessageFormatter.html), part of ICU 76, is a _tech preview_ implementation of MessageFormat 2. |
| 95 | +- JavaScript: [`messageformat`](https://github.com/messageformat/messageformat/tree/main/mf2/messageformat) 4.0 implements the MessageFormat 2 syntax, together with a polyfill of the runtime API proposed for ECMA-402. |
106 | 96 |
|
107 | | -> [!NOTE] |
108 | | -> The foregoing policies are _not_ a guarantee that the results of formatting will never change. |
109 | | -> Even when this specification or its implementation do not change, |
110 | | -> the _function handlers_ for date formatting, number formatting and so on |
111 | | -> can change their results over time or behave differently due to local runtime |
112 | | -> differences in implementation or changes to locale data |
113 | | -> (such as due to the release of new CLDR versions). |
114 | | -
|
115 | | -Updates to this specification will only reserve, define, or require |
116 | | -_function_ _identifiers_ and _function_ _option_ _identifiers_ |
117 | | -which satisfy either of the following two requirements: |
118 | | -- Includes no _namespace_, |
119 | | - and has a _name_ consisting of characters in the ranges a-z, A-Z, and 0-9, |
120 | | - and the characters U+002E FULL STOP `.`, U+002D HYPHEN-MINUS `-`, and U+005F LOW LINE `_`. |
121 | | -- Uses a _namespace_ consisting of a single character in the ranges a-z and A-Z. |
122 | | - |
123 | | -All other _identifiers_ in these categories are reserved for the use of implementations or users. |
| 97 | +The working group is also aware of these implementations in progress or released, but has not evaluated them: |
| 98 | +- [i18next](https://www.npmjs.com/package/i18next-mf2) i18nFormat plugin to use mf2 format with i18next, version 0.1.1 |
124 | 99 |
|
125 | 100 | > [!NOTE] |
126 | | -> Users defining custom _identifiers_ SHOULD include at least one character outside these ranges |
127 | | -> to ensure that they will be compatible with future versions of this specification. |
128 | | -> They SHOULD also use the _namespace_ feature to avoid collisions with other implementations. |
129 | | -
|
130 | | -Future versions of this specification will not introduce changes |
131 | | -to the data model that would result in a data model representation |
132 | | -based on this version being invalid. |
133 | | - |
134 | | -> For example, existing interfaces or fields will not be removed. |
135 | | -
|
136 | | -> [!IMPORTANT] |
137 | | -> This stability policy allows any of the following, non-exhaustive list, of changes |
138 | | -> in future versions of this specification: |
139 | | -> - Future versions may define new syntax and structures |
140 | | -> that would not be supported by this version of the specification. |
141 | | -> - Future versions may add additional structure or meaning to existing syntax. |
142 | | -> - Future versions may define new _keywords_. |
143 | | -> - Future versions may make previously invalid _messages_ valid. |
144 | | -> - Future versions may define additional _functions_ in the default registry |
145 | | -> or may reserve the names of _functions_ for the purposes of interoperability. |
146 | | -> - Future versions may define additional _options_ to existing functions. |
147 | | -> - Future versions may define additional _option_ values for existing _options_. |
148 | | -> - Future versions may deprecate (but not remove) _keywords_, _functions_, _options_, or _option_ values. |
149 | | -> - Future versions of this specification may introduce changes |
150 | | -> to the data model that would result in future data model representations |
151 | | -> not being valid for implementations of this version of the data model. |
152 | | -> - For example, a future version could introduce a new _keyword_, |
153 | | -> whose data model representation would be a new interface |
154 | | -> that is not recognized by this version's data model. |
155 | | -
|
| 101 | +> Tell us about your MessageFormat 2 implementation! |
| 102 | +> Submit a [PR on this page](https://github.com/unicode-org/message-format-wg/edit/main/spec/README.md), file an issue, or send email to have your implementation appear here. |
0 commit comments