Skip to content

Build your personal knowledge base with Trilium Notes

docs(i18n): write multi-paragraph text as one message with blank lines

Elian Dorana70d6e368689
diff --git a/.claude/skills/working-with-translations/SKILL.md b/.claude/skills/working-with-translations/SKILL.md
index 4916044e53..94fe03f9ce 100644
--- a/.claude/skills/working-with-translations/SKILL.md
+++ b/.claude/skills/working-with-translations/SKILL.md
@@ -125,6 +125,25 @@ There is no base key — `find --key space_usage.my_notes` shows only the suffix
`{{var}}` normally, `{{- var}}` to skip HTML-escaping when the value contains quotes. When a string embeds **components** whose order varies by language (links, note references), use `<Trans>` from `react-i18next` rather than `t()`, so translators can reorder them.
+### Multi-paragraph text
+
+Text that runs to several paragraphs is **one message with a blank line (`\n\n`) between paragraphs**,
+never one key per paragraph. The translator then sees the whole text and decides where its paragraphs
+fall — a language can merge two or split one — and a translation that drops the blank line still
+renders, as a single paragraph. Some 18 English strings already work this way
+(`toast.critical-error.message`, `call_to_action.new_layout_message`, the `breadcrumb_badges.*_description`
+tooltips, `llm.antigravity_agent_description`).
+
+Pass real newlines to `add` — in bash, `$'First paragraph.\n\nSecond paragraph.'`. Then render it so
+the breaks survive, by one of:
+
+- **`white-space`** — put the text in one element with the shared `.pre-wrap-text` class
+ (`stylesheets/style.css`), as the call-to-action dialog does. Tooltips (`pre-line`), toasts and
+ `confirm()` dialogs already keep line breaks on their own.
+- **Split into `<p>`** — when each paragraph should get paragraph spacing:
+ `text.split(/\n\s*\n/).map((p) => <p key={p}>{p}</p>)`, as the add-provider wizard does for
+ `connectionDescription`.
+
## Auditing
`missing` is the one that catches real bugs — a `t("…")` whose key is in no catalogue renders the raw key to the user:
diff --git a/CLAUDE.md b/CLAUDE.md
index 7b10b68817..935991b9d6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -157,6 +157,7 @@ SQLite (`better-sqlite3` on Node, `@sqlite.org/sqlite-wasm` on OPFS in standalon
- Client: `import { t } from "../services/i18n"`; everywhere else: `import { t } from "i18next"`. Never hardcode user-facing text, including in Electron dialogs/tray/IPC.
- **The `en` catalogues are US English** — `color`, `center`, `meter`, `recognize`, `labeled`, `canceled`. `en-GB` is a locale of its own and carries only the strings whose British spelling differs, so when a new or edited string contains one of those words, add the British form there too (`node .claude/skills/translating-locales/locale.mjs merge en-GB <catalog> <file>`). Leave `en-GB` alone when the spelling is the same in both.
- `{{var}}` interpolates escaped; `{{- var}}` unescaped (values with quotes etc.). Interpolated **components** whose order can vary by language (links, note references) use `<Trans>` from `react-i18next`, not `t()`.
+- **Multi-paragraph text is one message with `\n\n` between paragraphs**, never a key per paragraph, so the translation decides where paragraphs fall. Render it with `.pre-wrap-text` or split it on blank lines into `<p>` — see the `working-with-translations` skill.
- Third-party components (mind-map context menu, …) still go through `t()` with their strings under a dedicated namespace (e.g. `"mind-map"`).
- **Text editor (`packages/ckeditor5`)**: plugins call `editor.t("English text")` — the English text *is* the message id, the entry lives under `text-editor.ck` keyed by its slug, and `apps/client/src/services/i18n.spec.ts` fails on a missing or stale one. Rules (name it `t`, literal argument, don't shadow upstream strings, `MESSAGE_OVERRIDES`, `renderShortcut`): **`ckeditor5-plugin-development` skill**.
- New locale: `docs/Developer Guide/Developer Guide/Concepts/Internationalisation Translations/Adding a new locale.md`.