Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
/**
* Trilium-authored editor strings, and the bridge that gets them translated.
*
* Plugins localize with CKEditor's own `editor.t`, passing the English text itself as the message
* id — no host configuration, no translation keys in plugin code. When nothing supplies a
* dictionary (a test, a standalone editor), the message id is what gets rendered, so the UI is
* always correct English rather than a raw key.
*
* To actually translate those strings, the host builds a message dictionary and `i18n.ts` appends
* it to the editor's `translations` config. The i18next key is *derived* from the English text by
* {@link slugify}, so there is no message-id-to-key mapping to maintain, and there is no list of
* messages either: the English catalog under `text-editor.ck` **is** the registry, and
* {@link buildMessageDictionary} turns it into the dictionary CKEditor wants. Adding a string means
* writing it at the call site and adding its English entry — nothing else, and the client's
* `i18n.spec.ts` fails if the entry is missing, because it gathers the translation calls from this
* package's source.
*
* The same mechanism can reword CKEditor's own strings: an entry whose English text matches an
* upstream message id overrides the built-in translation for every locale, because our dictionary
* is merged after the core one.
*/
/** Prefix for the i18next keys this package's messages resolve to. */
export const MESSAGE_KEY_PREFIX = "text-editor.ck.";
/**
* Derive the i18next key for a message id: lowercase, with every run of non-alphanumeric
* characters collapsed into a single dash. Punctuation that would otherwise be significant in an
* i18next key (`.` separates key paths) or awkward in a catalog (`"`, `%0`) disappears, so message
* ids can be written as natural English.
*
* `"Insert a table."` becomes `text-editor.ck.insert-a-table`.
*/
export function slugify(message: string): string {
return message
.toLowerCase()
.replace(/[^a-z0-9]+/g, "-")
// The collapse above leaves at most one dash at each end, so trimming a single one is
// enough — and matching `-+$` instead would rescan the whole string from every position.
.replace(/^-|-$/g, "");
}
/**
* CKEditor's own strings that Trilium renames, mapping the upstream message id to the English
* wording we show instead. Trilium calls CKEditor's bookmarks "anchors", so every string the
* upstream `Bookmark` plugin renders is relabelled here, and the code block button is named after
* the block, as the block quote button is.
*
* This is the one case where a message id and its English text differ, which is why the pairs are
* declared rather than discovered: the dictionary has to be keyed by the *upstream* id for CKEditor
* to find it, while the text shown comes from our catalog entry for the replacement. Both halves of
* a pair therefore live here, and the replacement needs its own English entry like any other
* message — which is what makes the rename translatable per locale instead of English-only. A
* replacement CKEditor translates itself (`Code block`) needs no entry: CKEditor's translation of it
* stands in.
*
* A plugin Trilium owns never belongs here: rename its message id at the call site instead.
*/
export const MESSAGE_OVERRIDES: Record<string, string> = {
"Bookmark": "Anchor",
"Bookmarks": "Anchors",
"Bookmark name": "Anchor name",
"Bookmark must not be empty.": "Anchor name must not be empty.",
"Bookmark name already exists.": "Anchor name already exists.",
"Bookmark name cannot contain space characters.": "Anchor name cannot contain space characters.",
"Edit bookmark": "Edit anchor",
"Remove bookmark": "Remove anchor",
"Enter the bookmark name without spaces.": "Enter the anchor name without spaces.",
"Bookmark toolbar": "Anchor toolbar",
"bookmark widget": "anchor widget",
"No bookmarks available.": "No anchors available.",
"Scroll to bookmark": "Scroll to anchor",
"Insert code block": "Code block"
};
/**
* Build the CKEditor dictionary from the host's English catalog and translator.
*
* @param englishMessages the `text-editor.ck` section of the English catalog, mapping each derived
* key to the English text — which is the message id plugins pass to the
* editor's translation function.
* @param translate resolves a full i18next key to the localized string.
* @param upstreamDictionary CKEditor's own dictionary for the locale, which translates a
* replacement our catalog has no entry for.
*/
export function buildMessageDictionary(
englishMessages: Record<string, string>,
translate: (key: string) => string,
upstreamDictionary: Record<string, string | readonly string[]> = {}
): Record<string, string> {
const dictionary: Record<string, string> = {};
for (const [ derivedKey, message ] of Object.entries(englishMessages)) {
const key = MESSAGE_KEY_PREFIX + derivedKey;
const translated = translate(key);
// i18next echoes the key back for a missing entry; that would render `text-editor.ck.…` at
// the user, where falling back to the message id renders correct English.
if (translated && translated !== key) {
dictionary[message] = translated;
}
}
// Renames are applied last, so an upstream id resolves to our wording rather than CKEditor's.
// Unlike a translation, a rename applies even when the locale has no entry: the English
// replacement is itself the point, so it stands in until a translator supplies the rest.
for (const [ upstreamMessage, replacement ] of Object.entries(MESSAGE_OVERRIDES)) {
const upstream = upstreamDictionary[replacement];
dictionary[upstreamMessage] = dictionary[replacement]
?? (typeof upstream === "string" ? upstream : replacement);
}
return dictionary;
}
/**
* Translate a single message id outside an editor, for code that builds editor content before an
* editor exists — the slash-command definitions, for instance. Inside a plugin use the editor's own
* translation function instead; this is the same lookup, minus the editor.
*
* Falls back to the message id, which is the English text, so a missing entry renders English
* rather than a raw key.
*
* @param values substituted for the `%0`, `%1`, … placeholders, as {@link interpolate} describes.
*/
export function translateMessage(
translate: (key: string) => string,
message: string,
values: readonly string[] = []
): string {
const key = MESSAGE_KEY_PREFIX + slugify(message);
const translated = translate(key);
return interpolate(translated && translated !== key ? translated : message, values);
}
/**
* Substitute `%0`, `%1`, … in a translated message, which is how CKEditor's own translation function
* interpolates. A message therefore reads the same whether it was translated by the editor or by
* {@link translateMessage}, and translators see one placeholder convention.
*
* A placeholder with no corresponding value is left as written, rather than blanked.
*/
function interpolate(message: string, values: readonly string[]): string {
return message.replace(/%(\d+)/g, (placeholder, index) => values[Number(index)] ?? placeholder);
}