Skip to content

MSC4270: Matrix Glossary #4270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

MSC4270: Matrix Glossary #4270

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2103f31
MSC: Matrix Glossary
turt2live Feb 26, 2025
f57cce9
Temporarily remove all definitions
turt2live Feb 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 92 additions & 0 deletions proposals/4270-glossary-spec.md
View file
Open in desktop
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implementation requirements:

  • None feasible

Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# MSC4270: Matrix Glossary

As the Matrix specification continues to grow, it becomes increasingly important to maintain consistent
terms and phrases across clients, servers, and other implementations. Without this consistency, users
may become confused when switching between implementations or potentially be unable to use another
implementation entirely if the terminology is different enough.

The specification already has some terminology contained in the [Appendices](https://spec.matrix.org/v1.13/appendices/),
though the formal recommendation that users are called "users" is missing, for example. This proposal
defines these historical terms in a new specification document on spec.matrix.org, called the Glossary.

The new Glossary document may be further expanded through MSCs to include words or phrases which are
critically needed for cross-implementation consistency. Translations to other languages are maintained
through the MSC process, and published with the specification.

## Proposal

A new specification document titled "Glossary" is established, residing next to or near the existing
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the term "glossary" doesn't make it clear enough that these terms are supposed to be used in a client's UI – especially because the spec currently contains mostly technical requirements and only very few things that impact UI or UX. As somebody implementing the spec I might mistake this section as something that is supposed to help me understand the spec and neglect it. Maybe "End user glossary" or something similar would be better?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tbh reading this so far i assumed that this is going to just be an appendix in spec for the words used in spec... I never even assumed this would be about enduser communication 🤔 so imho its definetly not clear if it is enduser (aka client user, sdk user,...) or people directly implementing from spec (devs building an sdk, writing a hs or similar)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, agreed. I wonder if this whole thing should be renamed "Consistent user-facing terminology" to make it clear on what we're trying to solve? It then means that encryption-specific terminology as per #4161 will also be less out of place.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key thing being that we're trying to define consistent terms so that if users mix clients, they don't get completely lost (how come fluffychat is prompting me to enter a security code, but element x is prompting me to enter a recovery passphrase? or whatever)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sounds better than "glossary" to me. 👍

It'll require two lines in the menu .. but I'm not sure that really matters.

Screenshot 2025-03-04 at 20 11 49

[Appendices](https://spec.matrix.org/v1.13/appendices/) document. This new document has the following
purpose/scope:

* To define words, phrases, and terminology that implementations SHOULD use to provide consistent
user experience, especially when users are switching between implementations.
Comment on lines +22 to +23
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be helpful to clarify whether this includes only end users or everyone interfacing with an implementation (such as server admins). I suppose "user" here is meant to be user as defined in the glossary itself?

* To affect clients, servers, and any other implementations of the Matrix Protocol.
* To be accessible to the widest possible set of languages.

The structure of the document is left as an editorial concern after this MSC is accepted. This MSC
suggests sections covering broad categories with definitions contained within, as later represented
by this proposal.

Removing definitions from the specification requires an MSC, per normal [spec process](https://spec.matrix.org/proposals/).

Adding or updating definitions MUST at minimum affect English definitions, and SHOULD include
translations to the specification's accepted language list (defined later in this proposal). Both
operations require an MSC, again per normal process, though the non-English translations MAY be
affected by one or more follow-on MSCs after the English definitions are added. This is to say that
an MSC which introduces new definitions might first land the English terms, and a future, second,
MSC adds the French definitions for those English words, for example.

The Spec Core Team (SCT) SHOULD consider how well definitions may translate to other languages before
accepting English definitions into the spec, or seek professional external opinion on whether intent
can be maintained through translations.

### Initial definitions

These definitions may be incorporated in a "General" section of the new Glossary document, and are
normative (acceptance of this MSC means accepting the definitions).

**TODO**: Re-add definitions once the remainder of the MSC has been reviewed. 😇

### Initial language support

The SCT does not have expertise in every language, and may be unable to reliably audit translations
for a given language. To support the maximum possible set, within the bounds of professional translation
services, the initial set of supported languages is as follows. A future MSC may add/remove/change this
list. Contributions outside the supported languages list MAY be accepted on a case-by-case basis.

* UK English
* US English (where different from UK English)
* French
* German
Comment on lines +58 to +61
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this list is very much an open question

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe the selection could be supported by usage statistics from clients (where those exist)?


## Potential issues
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The SCT not having native speakers for all supported languages creates the risk of low-quality or, though less likely, harmful translations creeping in. I think this proposal should provide more detail around how the SCT will prevent this. Paid translation services alone don't feel like a great solution because those will most likely not have any understanding of Matrix technicalities. Maybe we could use trusted native community members or a community voting scheme for reviewing the translations.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given updates to translations would need to be done via MSCs, i'd have thought we can require that FCP will only pass once a trusted reviewer who natively speaks the language has signed it off. Trust could mean professional translator, or a community member who's accrued trust, etc.


Some terms may not be easily translated or represented by non-English languages. The SCT is encouraged
to request initial translations (where possible) on MSCs which introduce new English terms to the
glossary.

It's also possible that translations could change rapidly if there's disagreement about a given term's
translation. The SCT is encouraged to review the source of translations for authenticity and trust
before accepting an MSC.

## Alternatives

No notable alternatives.

## Security considerations

Translations may be from untrusted sources and could falsely represent the terms they claim to be
translations for. As noted in the Potential Issues section, the SCT is encouraged to review the source
of translations to avoid "trojan horse" contributions.

## Unstable prefix

Not applicable - this MSC covers text, not implementation.

## Dependencies

This MSC has no direct dependencies, but may be depended upon by other MSCs.

[MSC4161](https://github.com/matrix-org/matrix-spec-proposals/pull/4161) is expected to make use of
this MSC.