UI wording and localization

Documentation index · Styling

Hosts can replace editor-owned UI wording independently of CSS in the browser, ASP.NET and WinForms. English defaults cover review cards, tooltips, accessibility names, action progress/results, suggestion empty states, code/image controls, preview resizing, native search and built-in messages. Article text, comment/reply bodies, author names, token labels, language identifiers, host menu labels and AI/provider content remain host/document data. Localize those when supplying them. Developer exceptions retain their diagnostic English at the JavaScript API boundary; built-in messages are localized when shown in the component UI or returned through the native bridge.

JavaScript

Load the scripts from the authoritative asset manifest; editing/ui-strings.js loads first. Supply uiStrings at creation or through configure({uiStrings}), or use the runtime methods:

const editor = CODEEditor.create(element, {
  value: '# An article',
  uiStrings: {
    locale: 'en',
    values: { 'review.comment': 'Editorial note', 'review.reply': 'Respond' }
  }
});
editor.setUIStrings({
  locale: 'de',
  values: {
    'review.comment': 'Notiz',
    'review.reply': 'Antworten',
    'review.closeComment': 'Notiz schließen',
    'text.expandCommentByAuthor': '{author}: Notiz öffnen',
    'text.countMatches.one': '{count} Treffer',
    'text.countMatches.other': '{count} Treffer'
  }
});
const current = editor.getUIStrings(); // defensive copy
const defaults = editor.getUIStringCatalog(); // stable keys -> English defaults
// CODEEditor.getUIStringCatalog() also works before creating an editor.
editor.setUIStrings(); // reset to English defaults

Each call replaces the previous configuration rather than merging. Omitted keys fall back to English; empty string overrides are permitted. Unknown keys, non-string values and invalid locale tags are rejected without changing the active configuration. uiStringsChange notifies host code. Two instances may use different wording/locales, including floating panes and menus.

The complete string catalog is also available through the APIs. review.comment, for example, changes the card title; review.title changes the pane heading. Treat catalog keys as the public contract rather than editing the runtime's English literals. New strings must be added to this catalog and bound in their component.

Parameters and plural forms

Strings use named placeholders such as {author}, {text}, {label}, {index} and {count}. Keep the placeholders needed by the message; translations may reorder them. Values are substituted as literal text, never HTML. For a counted message, add .zero, .one, .two, .few, .many or .other to its base key. Selection uses Intl.PluralRules(locale); unspecified forms fall back to the base override, then English. Review timestamps use the same locale with the browser's local time zone; review.timestamp contains {date}.

WinForms

The native host uses the same keys and catalog, including its embedded Find/Replace UI:

editor.Options.UIStrings = new EditorUIStrings(Values: new()
{
    ["review.comment"] = "Editorial note",
    ["review.reply"] = "Respond",
    ["text.find"] = "Search"
});
await editor.SetUIStringsAsync(new EditorUIStrings(Locale: "de", Values: new()
{
    ["review.comment"] = "Notiz",
    ["review.closeComment"] = "Notiz schließen"
}));
EditorUIStrings current = await editor.GetUIStringsAsync();
Dictionary<string, string> catalog = await editor.GetUIStringCatalogAsync();
await editor.SetUIStringsAsync(); // reset

UIStringsChanged reports changes. Assign a new Options.UIStrings value to update options; mutating its dictionary in place does not raise the options notification. The awaited setter validates the change before replacing the control's accepted options. Sample toolbar UI wording buttons demonstrate alternate editorial terminology in both hosts. Application-owned toolbars and OS dialogs remain controlled by the application/Windows.

Runtime behavior and styling

Existing UI text and accessibility labels update in place, preserving focused fields, selection, unsent drafts, discussion state and document/review history. Newly created controls inherit the active configuration. Wording is per editor and is not saved in article/review packages; persist it in application settings. CSS controls presentation separately through uiTheme. Longer translations can change layout; review geometry is remeasured automatically. UI strings support terminology/localization rather than changing document direction or implementing a complete translated application.

Comment marker positioning uses the editor's client edge, excluding borders and its scrollbar gutter, with space for the count badge. This applies with review open or closed, in Source/Visual and the panel fallback. Resize, theme changes and scrollbar changes recalculate the lane. The rendered regressions cover classic scrollbars and larger marker sizes; overlay scrollbars use the same inset, with platform-specific pointer behavior left to browser testing on that platform.

Previous
Next