From ec8cddd7eb7596891723f4da27afead409c1297b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 7 Dec 2021 16:52:44 -0700 Subject: [PATCH 1/5] Extensible Events - Translatable Text --- ...extensible-events-translatable-messages.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 proposals/3554-extensible-events-translatable-messages.md diff --git a/proposals/3554-extensible-events-translatable-messages.md b/proposals/3554-extensible-events-translatable-messages.md new file mode 100644 index 00000000000..649d0d700b3 --- /dev/null +++ b/proposals/3554-extensible-events-translatable-messages.md @@ -0,0 +1,70 @@ +# MSC3553: Extensible Events - Translatable Messages + +[MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767) describes Extensible Events in detail, +though deliberately does not include schemas for non-text messaging types. This MSC covers only support +for translations on the `m.message` type. + +*Rationale*: Splitting the MSCs down into individual parts makes it easier to implement and review in +stages without blocking other pieces of the overall idea. For example, an issue with the way images +are represented should not block the overall schema from going through. + +## Proposal + +A new field is added to the `m.message` type definition to denote which language is being represented +by the `body`: `lang`. + +An example: + +```json5 +{ + "type": "m.message", + "content": { + "m.message": [ + { + "body": "Je suis un poisson", + "lang": "fr" + }, + { + "body": "I am a fish", + "lang": "en" + } + ] + } +} +``` + +*Note*: `m.message`'s support for `mimetype` has been excluded from the example for brevity. It is still +supported in events. + +As already covered by Extensible Events, the first element in the array would be the representation that +unaware clients would use, which in the example above would be French. Clients which are aware of language +support might end up picking the English version instead. + +By default, messages are assumed to be sent in English (`en`). + +`lang` must be a valid language code under [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). This is +in line with the HTML specification which uses a similar attribute on the `` node. + +There is no specific guidance for when to use translation support, though cases can include automatic machine +translation, bots with internationalization support, and possibly some bridges. + +## Potential issues + +The language code spec might not encompass all of the possible language code combinations, but should cover +plenty given its popularity in HTML. + +This does not apply to `m.text` or `m.html`, necessitating the use of the longer form `m.message` when sending +translated messages. + +## Alternatives + +No significant alternatives known. + +## Security considerations + +No specific considerations are required for this proposal. + +## Unstable prefix + +This MSC does not introduce anything which should conflict with stable usage. Implementations are encouraged +to review [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767)'s unstable prefixing approach. From 632f9b9695daa63a6584be8650682a9fafa8dbbd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 7 Dec 2021 16:53:16 -0700 Subject: [PATCH 2/5] remove evidence that this was copy/pasted --- proposals/3554-extensible-events-translatable-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3554-extensible-events-translatable-messages.md b/proposals/3554-extensible-events-translatable-messages.md index 649d0d700b3..59395a7cbc5 100644 --- a/proposals/3554-extensible-events-translatable-messages.md +++ b/proposals/3554-extensible-events-translatable-messages.md @@ -1,4 +1,4 @@ -# MSC3553: Extensible Events - Translatable Messages +# MSC3554: Extensible Events - Translatable Messages [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767) describes Extensible Events in detail, though deliberately does not include schemas for non-text messaging types. This MSC covers only support From 8a8cd61b1400348e8306d25f0a843da83afdfd8e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sat, 12 Nov 2022 19:02:50 +0000 Subject: [PATCH 3/5] Adjust MSC based on new content blocks system and `m.markup` --- ...extensible-events-translatable-messages.md | 43 +++++++++++++------ 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/proposals/3554-extensible-events-translatable-messages.md b/proposals/3554-extensible-events-translatable-messages.md index 59395a7cbc5..a4cc92f0adf 100644 --- a/proposals/3554-extensible-events-translatable-messages.md +++ b/proposals/3554-extensible-events-translatable-messages.md @@ -1,17 +1,33 @@ # MSC3554: Extensible Events - Translatable Messages [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767) describes Extensible Events in detail, -though deliberately does not include schemas for non-text messaging types. This MSC covers only support -for translations on the `m.message` type. +though deliberately does not include schemas for some messaging types. This MSC covers translations +on `m.markup` content blocks specifically. *Rationale*: Splitting the MSCs down into individual parts makes it easier to implement and review in stages without blocking other pieces of the overall idea. For example, an issue with the way images are represented should not block the overall schema from going through. +**Note**: As a second priority MSC in the Extensible Events series, this MSC is not proposed to be a +blocker on extensible events entering the specification - this can mean that when extensible events +are available, translations might not be (in stable form). Readers should consider the unstable prefix +section for early support of this MSC. + ## Proposal -A new field is added to the `m.message` type definition to denote which language is being represented -by the `body`: `lang`. +As defined by MSC1767, `m.markup` currently specifies an array with "representations" for the text +on the event. Clients are expected to find the first representation they can render based on mimetype, +which can be implicit. + +Sender-provided translations can be useful in contexts where the sender knows multiple languages are +used in a room, such as announcements or other prepared communications. Less common in instant messaging +(at least without a translation service on the sender's side), the receiving client can use the message +which matches the user's preferred language. + +This MSC adds an additional key, `lang`, to the `m.markup` representation schema and adjusts how a +client decides upon a representation to include the language in that consideration. The array overall +is still ordered, which means the sender should also supply the language which fits the scenario best +as the first item. An example: @@ -19,7 +35,7 @@ An example: { "type": "m.message", "content": { - "m.message": [ + "m.markup": [ { "body": "Je suis un poisson", "lang": "fr" @@ -33,13 +49,9 @@ An example: } ``` -*Note*: `m.message`'s support for `mimetype` has been excluded from the example for brevity. It is still +*Note*: `m.markup`'s support for `mimetype` has been excluded from the example for brevity. It is still supported in events. -As already covered by Extensible Events, the first element in the array would be the representation that -unaware clients would use, which in the example above would be French. Clients which are aware of language -support might end up picking the English version instead. - By default, messages are assumed to be sent in English (`en`). `lang` must be a valid language code under [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). This is @@ -53,8 +65,9 @@ translation, bots with internationalization support, and possibly some bridges. The language code spec might not encompass all of the possible language code combinations, but should cover plenty given its popularity in HTML. -This does not apply to `m.text` or `m.html`, necessitating the use of the longer form `m.message` when sending -translated messages. +If a sending client supports several languages, receiving clients could spend extra time attempting to find +a suitable representation to render. This is considered a non-issue, though clients should consider how to +efficiently search an array. ## Alternatives @@ -66,5 +79,7 @@ No specific considerations are required for this proposal. ## Unstable prefix -This MSC does not introduce anything which should conflict with stable usage. Implementations are encouraged -to review [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767)'s unstable prefixing approach. +While this MSC is not considered stable, implementations should use `org.matrix.msc3554.lang` instead of `lang` +when sending events. + +Note that extensible events should only be used in an appropriate room version as well. From 5464232bd409ce94fe516a0015c7e5e3afa8a6f2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 18 Apr 2023 14:32:56 -0600 Subject: [PATCH 4/5] Update for MSC1767 --- .../3554-extensible-events-translatable-messages.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/3554-extensible-events-translatable-messages.md b/proposals/3554-extensible-events-translatable-messages.md index a4cc92f0adf..25d2883f9a6 100644 --- a/proposals/3554-extensible-events-translatable-messages.md +++ b/proposals/3554-extensible-events-translatable-messages.md @@ -2,7 +2,7 @@ [MSC1767](https://github.com/matrix-org/matrix-doc/pull/1767) describes Extensible Events in detail, though deliberately does not include schemas for some messaging types. This MSC covers translations -on `m.markup` content blocks specifically. +on `m.text` content blocks specifically. *Rationale*: Splitting the MSCs down into individual parts makes it easier to implement and review in stages without blocking other pieces of the overall idea. For example, an issue with the way images @@ -15,7 +15,7 @@ section for early support of this MSC. ## Proposal -As defined by MSC1767, `m.markup` currently specifies an array with "representations" for the text +As defined by MSC1767, `m.text` currently specifies an array with "representations" for the text on the event. Clients are expected to find the first representation they can render based on mimetype, which can be implicit. @@ -24,7 +24,7 @@ used in a room, such as announcements or other prepared communications. Less com (at least without a translation service on the sender's side), the receiving client can use the message which matches the user's preferred language. -This MSC adds an additional key, `lang`, to the `m.markup` representation schema and adjusts how a +This MSC adds an additional key, `lang`, to the `m.text` representation schema and adjusts how a client decides upon a representation to include the language in that consideration. The array overall is still ordered, which means the sender should also supply the language which fits the scenario best as the first item. @@ -35,7 +35,7 @@ An example: { "type": "m.message", "content": { - "m.markup": [ + "m.text": [ { "body": "Je suis un poisson", "lang": "fr" @@ -49,7 +49,7 @@ An example: } ``` -*Note*: `m.markup`'s support for `mimetype` has been excluded from the example for brevity. It is still +*Note*: `m.text`'s support for `mimetype` has been excluded from the example for brevity. It is still supported in events. By default, messages are assumed to be sent in English (`en`). From c8c3143b3f725b0831f0a5d69a893062e3b947f1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 17 Apr 2023 21:33:45 -0600 Subject: [PATCH 5/5] Remove excess artifact --- themes/docsy | 1 - 1 file changed, 1 deletion(-) delete mode 160000 themes/docsy diff --git a/themes/docsy b/themes/docsy deleted file mode 160000 index 5023a291452..00000000000 --- a/themes/docsy +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 5023a2914528e012ecf3ec85a56028c00ee97dd2