Add UI copy and German translation style guides by kongo09 · Pull Request #34852 · element-hq/element-web

kongo09 · 2026-08-27T14:36:16Z

Adds two new documentation guides for translations and UI copy:

docs/ui-copy.md — language-independent guidelines for writing Element's interface copy and for how any translation should relate to the English source (voice, grammatical form by position, punctuation, terminology, placeholders/plurals, key renaming).
docs/translations/de.md — an English → German translation style guide. The new docs/translations/ directory is intended as the home for future per-language guides.
Cross-references added from README.md, docs/translating.md, docs/translating-dev.md and the VitePress sidebar.

Also fixes a pre-existing docs-site bug surfaced while verifying this: the custom link resolver rewrote every relative in-content .md link to a GitHub blob URL missing the docs/ prefix, so cross-doc links (e.g. ./jitsi.md in jitsi-dev.md) rendered as 404s. Links whose target exists within docs/ now pass through to VitePress native resolution; links to repo-root files keep the GitHub fallback. (Separate commit, happy to split it out into its own PR if preferred.)

Verified locally: oxfmt --check passes and vitepress build docs succeeds with the dead-link check enabled.

Checklist

I have read through review guidelines and CONTRIBUTING.md.
Tests written for new code (and old code if feasible). — N/A, documentation-only change
New or updated public/exported symbols have accurate TSDoc documentation. — N/A
Linter and other CI checks pass.
I have licensed the changes to Element by completing the Contributor License Agreement (CLA)

Add two new documentation guides: - docs/ui-copy.md: language-independent guidelines for writing Element's interface copy and how translations should relate to the English source - docs/translations/de.md: English -> German translation style guide; docs/translations/ is the home for future per-language guides Cross-reference them from README.md, docs/translating.md, docs/translating-dev.md and the VitePress sidebar. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The custom link resolver rewrote every relative .md link to a GitHub blob URL missing the docs/ prefix, so in-content links between docs pages (e.g. ./jitsi.md in jitsi-dev.md) rendered as 404s. Let links whose target exists within docs/ pass through to VitePress native resolution; links to repo-root files keep the GitHub fallback. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

florianduros · 2026-08-28T06:38:04Z

+
+Language-independent rules for Element's interface copy: how to write the English source, and how any translation should relate to it.
+
+Applies to Element Web, Element Desktop, shared-components, Element X, Element Call, Element Admin and MAS. Per-language conventions live in the language guides in `docs/translations/` (e.g. the [German translation guidelines](./translations/de.md)).


It only applies to EW/ED et shared components. This repo doesn't rule the other product guidelines

We should nevertheless make clear that language applies cross-product. You cannot change something in Element Web, like renaming a cryptographic concept, without adjusting this in the other places as well.

Should it live in https://github.com/element-hq/element-meta instead? And we keep the exception or EW specialties here?

florianduros · 2026-08-28T06:38:36Z

imo all of this should be in localazy

Can you point me to the place where this would live?

florianduros · 2026-08-28T06:38:46Z

+
+These guidelines keep Element's German UI consistent and familiar—aligned with muscle memory from WhatsApp, Signal, Teams, and Slack.
+
+Applies to Element Web, Element Desktop, shared-components, Element X, Element Call, Element Admin and MAS. Where a rule differs by product, it is called out explicitly.


ditto what?

florianduros · 2026-08-28T06:42:16Z

+
+    - _Admin_ means a **room** admin. "Contact your admin" reads as "ask a moderator here", whatever you intended.
+    - _Session_ means a Megolm session in crypto contexts, and locally stored login state in others.
+    - _Client_ means an OAuth client in MAS and admin surfaces.


Client also means other matrix clients in our translations

Can you point me to an example?

I looked at the strings.

There are 13 strings with the word client in EW and they all refer to the app.

In EX there are zero strings with the word client. This is all app.

MAS has 5 strings and I need to figure out which one of these are actually apps

Admin has 5 strings and makes the important distinction in one of the strings:

Applications are OAuth 2.0 clients that users sign in to.

Proposal: I'll tidy up this string in a better way, so that

App or Application is the consistent word for the software a user runs to chat

Client is only used in the technical context of OAuth

Does that make sense to you?

App or Application is the consistent word for the software a user runs to chat

I wouldn't consider a website an "app" - in the context of Element Web

Element calls the web application "app"

The browser itself calls something like Element an app

Microsoft calls the Teams web app an app

The term "client" is a technical term, as in server-client API. Good for Matrix. Not good for end users.

The browser itself calls something like Element an app

Yes, it is an app if you install the PWA "Progressive Web App" - hence it says "App available"

So we're all aligned now?

florianduros · 2026-08-28T06:46:31Z

+
+- **Name variables for the translator, not for the programmer.** `recipient` tells a translator nothing — is it a person, an email address, a user ID? `recipientEmailAddress` does. The variable name is often the only context a translator gets.
+
+- **Before adding a string, check whether it already exists** in a related project. Reusing a shared string is better than a near-duplicate — but if the existing one is _wrong_, fix it rather than working around it, or the divergence spreads.


Same words have different meaning in different use case. Also the key is also kind of a path of where the translation is used and also a sense.

I agree to use common string for actions which are vastly used and without ambiguity.

Is there a todo here?

Sorry, i don't understand, what todo?

florianduros · 2026-08-28T06:50:50Z

+
+| Change                                                                        | Rename the key?                                                                        |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| **The meaning changes** — the string now says something different             | **Yes.** Renaming forces every language to retranslate, which is what should happen    |


I don't agree:

You can force the re-translation in localazy without changing the key

We have a lot of key like: example_of_a_dialog|description. Even if the meaning change, the key is still valid. Forcing the re-translation in localazy is enough

Right, you can force from localazy. Changing the key is not necessary. I'll remove this

florianduros · 2026-08-28T06:52:51Z

+
+- **When referencing another system's UI** — iOS Settings, Android, another Element app — match that system's wording exactly, in every language. Some names (Apple's alert-tone names) are untranslated in every locale.
+
+- **Name variables for the translator, not for the programmer.** `recipient` tells a translator nothing — is it a person, an email address, a user ID? `recipientEmailAddress` does. The variable name is often the only context a translator gets.


This is for the dev, should be in translating-dev.md

What rule would you propose to distinguish what goes into what file? My impression was that the dev file is less about content but more about the dev mechanics, the project, the process. In that case, above language advise would sit here and not there.

florianduros · 2026-08-28T06:54:16Z

This guide is for developers or translators?

It seems to combine technical guidelines (how our internalization framework works) and wording guidelines(which are provided by the design team in Figma)

It should be for whoever writes initial language strings. That can be a designer, a product manager, a contributors, a developer, etc... It should not contain technicalities, like how placeholders work or what the process is overall, but guide on UI copy content.

Okay make sense thanks

florianduros · 2026-08-28T06:57:22Z

+
+- **Prefer full repeated sentences over shared fragments.** Several near-identical strings that differ by a word or two look like waste, but they translate faster and more accurately than fewer strings assembled from pieces. This is the opposite of the instinct that serves you well in code.
+
+- **Use the framework's plural mechanism, never an `if`.** Choosing between a singular and a plural string in code assumes two forms; some languages have up to six. Pass the count and let the translation declare its own forms.


This is for the dev, should be in translating-dev.md

florianduros · 2026-08-28T06:59:49Z

+
+## 10. Working practice
+
+- **Run the machine checks whenever the files change.** Key coverage, placeholder and markup parity, plural completeness, whitespace, and translation-identical-to-source are all mechanical, cost seconds, and catch regressions that reading does not.


Is it running the tests? I don't think we have anything to catch plural completeness?

Fair point. I've run my own tooling when I worked through the clean-up which did all of the above and discovered loads of problems. But we don't have that in CI. I'll reword.

kongo09 and others added 2 commits August 27, 2026 16:33

kongo09 requested a review from a team as a code owner August 27, 2026 14:36

kongo09 requested review from Half-Shot and dbkr August 27, 2026 14:36

github-actions Bot deployed to SharedComponentStorybook August 27, 2026 14:38 View deployment

github-actions Bot deployed to Netlify August 27, 2026 14:38 View deployment

Use default import for node:path to satisfy oxlint

4e0b350

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions Bot deployed to SharedComponentStorybook August 27, 2026 14:51 View deployment

github-actions Bot deployed to Netlify August 27, 2026 14:51 View deployment

dbkr added the T-Task Tasks for the team like planning label Aug 27, 2026

github-actions Bot deployed to EndToEndTests August 27, 2026 15:11 View deployment

florianduros requested changes Aug 28, 2026

View reviewed changes


		Language-independent rules for Element's interface copy: how to write the English source, and how any translation should relate to it.

		Applies to Element Web, Element Desktop, shared-components, Element X, Element Call, Element Admin and MAS. Per-language conventions live in the language guides in `docs/translations/` (e.g. the [German translation guidelines](./translations/de.md)).


		These guidelines keep Element's German UI consistent and familiar—aligned with muscle memory from WhatsApp, Signal, Teams, and Slack.

		Applies to Element Web, Element Desktop, shared-components, Element X, Element Call, Element Admin and MAS. Where a rule differs by product, it is called out explicitly.


		- Name variables for the translator, not for the programmer. `recipient` tells a translator nothing — is it a person, an email address, a user ID? `recipientEmailAddress` does. The variable name is often the only context a translator gets.

		- Before adding a string, check whether it already exists in a related project. Reusing a shared string is better than a near-duplicate — but if the existing one is _wrong_, fix it rather than working around it, or the divergence spreads.


		- When referencing another system's UI — iOS Settings, Android, another Element app — match that system's wording exactly, in every language. Some names (Apple's alert-tone names) are untranslated in every locale.

		- Name variables for the translator, not for the programmer. `recipient` tells a translator nothing — is it a person, an email address, a user ID? `recipientEmailAddress` does. The variable name is often the only context a translator gets.


		- Prefer full repeated sentences over shared fragments. Several near-identical strings that differ by a word or two look like waste, but they translate faster and more accurately than fewer strings assembled from pieces. This is the opposite of the instinct that serves you well in code.

		- Use the framework's plural mechanism, never an `if`. Choosing between a singular and a plural string in code assumes two forms; some languages have up to six. Pass the count and let the translation declare its own forms.


		## 10. Working practice

		- Run the machine checks whenever the files change. Key coverage, placeholder and markup parity, plural completeness, whitespace, and translation-identical-to-source are all mechanical, cost seconds, and catch regressions that reading does not.

Uh oh!

Uh oh!

Conversation

kongo09 commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t3chguy Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kongo09 commented Aug 27, 2026 •

edited

Loading

t3chguy Aug 28, 2026 •

edited

Loading