How to localize

Two ways to localize the WinForms HTML Editor

The WinFormHtmlEditor ships fully localizable. Every toolbar tooltip, context-menu item, dialog label and message comes from a resource table, and there are two complementary ways to control what your users see:

The two options combine: select a built-in language, then override just the handful of strings you want to reword. This page shows both, end to end, and lists every overridable key at the bottom.

Option 1 - Pick a built-in language

Set the Language property on WinFormHtmlEditor (category Behavior, default EnglishUs). It is settable in the Visual Studio designer or in code; assigning it re-localizes the toolbar, context menus, every dialog and all messages immediately. The enum is SpiceLogic.HtmlEditor.Resources.Localization.EditorLanguage and ships these 14 languages:

using SpiceLogic.HtmlEditor.WinForms;
using SpiceLogic.HtmlEditor.Resources.Localization;

// switch the whole editor UI to German
editor.Language = EditorLanguage.German;

Imports SpiceLogic.HtmlEditor.WinForms
Imports SpiceLogic.HtmlEditor.Resources.Localization

' switch the whole editor UI to German
editor.Language = EditorLanguage.German

Inline and dialog spell-checking follow the editor language automatically (SpellCheckOptions.SpellCheckLanguage defaults to SameAsEditorLanguage), so choosing Polish here also switches the spell-check dictionary to Polish.

Option 2 - Override any text with a JSON file

When you need different wording, your own brand terms, or a language the control does not ship, override strings from an external JSON file -- no recompilation. The hub is the static class LocalizationManager in SpiceLogic.HtmlEditor.Resources.Localization.

How it works: create a flat JSON file named EditorStrings.<culture>.json (for example EditorStrings.pl-PL.json -- the culture must match the culture of the language you select, e.g. Polish = pl-PL). Put it in a folder and point the manager at that folder once at start-up:

using SpiceLogic.HtmlEditor.Resources.Localization;

// look for an EditorStrings.*.json in <app>\SpiceLogic.HtmlEditor.Localization\
LocalizationManager.AutoDiscoverJsonOverrides();
// ...or point at any folder explicitly:
var dir = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "SpiceLogic.HtmlEditor.Localization");
LocalizationManager.SetJsonOverrideDirectory(dir);

Imports SpiceLogic.HtmlEditor.Resources.Localization

' look for an EditorStrings.*.json in <app>\SpiceLogic.HtmlEditor.Localization\
LocalizationManager.AutoDiscoverJsonOverrides()
' ...or point at any folder explicitly:
Dim dir = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "SpiceLogic.HtmlEditor.Localization")
LocalizationManager.SetJsonOverrideDirectory(dir)

The JSON is a plain string-to-string map. Include only the keys you want to change -- everything else falls back automatically. Example partial override:

{
  "Toolbar_Bold": "Pogrubienie",
  "Toolbar_Italic": "Kursywa",
  "Dialog_Hyperlink_Title": "Wstaw hiperłącze",
  "Common_OK": "OK"
}

Resolution order for every string: (1) a programmatic SetOverride; (2) the matching key in your EditorStrings.<culture>.json; (3) the built-in translation for that culture; (4) the built-in English text; (5) the raw key itself. Calling LocalizationManager.SetJsonOverrideDirectory(null) turns overrides off again; ClearOverrides() reloads them from disk.

Tip: set the JSON file's Copy to Output Directory to Copy if newer so it ships next to your .exe.

The Localization sample application

A complete, runnable sample ships with the product at src/manual tests/WinForms.Tests/LocalizationTest (C#) and LocalizationTestVB (VB.NET). It is a single window with a language drop-down and an Enable JSON Override check box, so you can watch the whole UI re-localize live.

Next to the executable it carries a SpiceLogic.HtmlEditor.Localization folder containing two important files:

• EditorStrings.pl-PL.json -- the working override the demo loads when you tick Enable JSON Override while Polish is selected (toolbar tooltips gain a [CUSTOM] prefix, proving the JSON wins over the built-in text).
• _OVERRIDABLE-KEYS.reference.json -- a reference listing of every overridable key with its English default. It is intentionally not loaded at runtime (its name does not match the EditorStrings.<culture>.json pattern). Copy the lines you want from it into your own EditorStrings.<culture>.json and edit the values.

To reproduce the demo: run the sample, pick Polish, then tick Enable JSON Override -- the Bold/Italic/Underline tooltips change immediately.

Switching at runtime and overriding a single string in code

Everything works at runtime, not just at start-up. Re-assigning editor.Language re-localizes the editor and any open dialog -- each dialog subscribes to LocalizationManager.LanguageChanged and refreshes itself. You can also subscribe to that event yourself to re-localize your own surrounding UI.

To change just one string from code (no file), use SetOverride(culture, key, value). It takes precedence over both the JSON file and the built-in text:

using SpiceLogic.HtmlEditor.Resources.Localization;

LocalizationManager.SetOverride("de-DE", "Toolbar_Bold", "Fett");
editor.Language = EditorLanguage.German; // re-apply to show the override

Imports SpiceLogic.HtmlEditor.Resources.Localization

LocalizationManager.SetOverride("de-DE", "Toolbar_Bold", "Fett")
editor.Language = EditorLanguage.German ' re-apply to show the override

The culture string passed to SetOverride is the .NET culture name of the target language (the Culture column in the Option 1 table, e.g. de-DE, pl-PL).

Full list of overridable JSON keys

Every key below may appear in an EditorStrings.<culture>.json override file. The left column is the key; the right column is the built-in English (en-US) default. Keys whose name ends in WinForms are used by the WinForms dialogs, where & marks the keyboard access-key character. You only need to include the keys you actually want to change.

Toolbar

Context menu

Common

Hyperlink dialog

Image dialog

Search / Replace dialog

Spell Checker dialog

Symbol dialog

YouTube Video dialog

Table Properties dialog

Table Cell Properties dialog

Style Builder dialog

Font Picker dialog

Spell check (inline)

Messages

Headings, Units, base-directory dialogs, About box