Dear ImGui Localization Guide: UTF-8, Widget IDs & Fonts

Dear ImGui localization makes a C++ editor, developer tool or game interface readable in multiple languages while keeping its controls stable. If you are searching for how to translate Dear ImGui labels, show UTF-8 characters in ImGui, stop translated button names from changing widget identity, or configure international fonts with the newer dynamic-font system, this guide explains the choices and tests that matter. The target is a tool whose buttons, warnings and input fields remain trustworthy after people switch languages.

Dear ImGui is an immediate-mode UI library, not an automatic translator. In many widgets the visible label also participates in ID generation, so translating a caption without deliberately preserving an internal ID can change focus, state or interaction. Font loading is a separate layer. The project’s official font documentation describes a newer dynamic font system introduced in version 1.92, which behaves differently from older fixed-atlas guidance. A reliable multilingual interface must account for the exact Dear ImGui version and renderer backend it ships.

Our worked example is Observatory Desk, a fictional desktop tool for inspecting observations, filtering records and confirming whether to discard unsaved annotations. We will follow an English interface into a second language and examine the visible text, hidden widget IDs, UTF-8 strings, font glyph availability, edit fields and packaging. The C++ examples are educational illustrations: real applications must reconcile them with their own object lifetimes, backend version, accessibility needs and supported languages.

Quick answer: how to localize Dear ImGui

Store reviewed UI text outside control logic and retrieve messages by stable keys.
Separate translated visible labels from stable widget identifiers with documented ImGui ID patterns such as ## or ### where appropriate.
Send valid UTF-8 strings to the text API and check source-file/compiler encoding as well as loaded catalog encoding.
Distinguish Dear ImGui 1.92+ dynamic font behavior from older prebuilt glyph-range and atlas instructions, and verify backend support.
Do not infer full complex-script, bidirectional or screen-reader support from rendering a few Unicode characters.
Test focus, input, saved filters, warning meaning and actual release binaries after every language or font change.

Scope, audience and table of contents

This tutorial explains the practical boundary between language catalogs, immediate-mode widget identity and font rendering. It is for C++ tool builders and multilingual reviewers. It is not a general guarantee that Dear ImGui can satisfy every script or accessibility requirement. The correct implementation depends on the library version and renderer backend actually distributed. Readers can follow the implementation chapters and then use the worked cases to recognize problems encountered in a running interface.

Separate stable widget IDs from visible language
Load UTF-8 text and version-compatible fonts
Protect edit fields, popups and table state
Test unusual scripts, high DPI and packaged builds
Troubleshoot 30 concrete cases
Run four-week delivery checks
Review FAQs and official sources

Minimal C++ example: stable identity and visible wording

This example shows the important distinction without pretending to include a complete message-catalog parser or application loop. The translated caption changes while the hidden ID suffix identifies the same logical action. Unique surrounding scopes are still needed for repeated controls.

// Inside a normal Dear ImGui frame, with messages already loaded:
std::string title = translate("action.save");
std::string buttonLabel = title + "##save_observation";
if (ImGui::Button(buttonLabel.c_str())) {
    saveObservation(); // stable command, independent of the language
}
std::string note = translate("help.unsaved");
ImGui::TextUnformatted(note.c_str());
// In repeated table rows, scope IDs by a stable record key.

1. Why ImGui label identity changes the localization design

Many Dear ImGui widgets derive identity from a label and the current ID stack. Changing a visible caption between languages can change the computed ID if code uses that caption directly. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Use stable hidden identifiers in widget labels or a stable PushID scope that is independent of presentation language. Keep translated wording separate from command identifiers and stored data. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not let two buttons share a hidden ID in the same scope, and do not create an ID from a translated string whose spelling will change. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Switch language with a popup open and verify that the intended button, focus and any persistent widget state still refer to the same logical control. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

2. Understand visible text versus ID suffixes

Dear ImGui provides ## and ### label conventions, but their effects on displayed text and ID computation differ. The right pattern depends on whether only the caption or the whole widget identity is meant to remain stable. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Review the ID stack and choose unique identifiers for repeated controls, table rows and popups. Keep each identifier stable across localization, sorting and runtime updates. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not copy a generic ## suffix to every row without including a row-specific identity. ID collisions can make one translated control act like another. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Open debug tools and test two rows with identical visible actions, ensuring each still targets its intended record in every locale. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

3. Catalogs belong outside the immediate-mode frame loop

The frame loop runs frequently; loading and parsing translation files every frame wastes work and creates timing hazards. Retrieve already parsed messages, then use them during drawing. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Load a versioned, reviewed UTF-8 catalog at startup or on an intentional locale change. Keep a stable string value alive for the duration of each API call and update cached derived formatting deliberately. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not store a pointer to temporary translated text after its lifetime ends. Use safe std::string ownership and keep lookup failures visible to developers. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Run a stress test of rapid language switching, repeated drawing and opening and closing dialogs without stale pointer behavior. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

4. Use TextUnformatted for user-facing text

ImGui::Text treats its input as a printf-style formatted string. Translated sentences or user data containing a percent sign should not accidentally become formatting instructions. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Use TextUnformatted for plain text and a trusted formatting layer for numeric parameters. Keep the formatting grammar with the language edition rather than building English-shaped fragments. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not pass untrusted or translator-controlled text directly as a format string. This is both a correctness and safety boundary, independent of the language. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Display a sentence containing literal percent signs and multilingual punctuation without unexpected substitution or broken output. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

5. UTF-8 starts in files and compiler settings

A font cannot repair bytes that were encoded incorrectly before reaching ImGui. The official font guide calls out source-file encoding, UTF-8 literals and compiler configuration as common causes of garbled text. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Store catalogs in UTF-8 and validate their decoding. For C++ literals, check compiler encoding settings; be mindful that C++20 u8 literals have char8_t type rather than const char*. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not assume every string literal written in a non-English source file becomes the same bytes on every compiler. A display defect may begin in the build configuration. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Use ImGui’s encoding debug facilities and compare expected code points against the bytes delivered at the UI boundary. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

6. Dear ImGui 1.92 dynamic fonts and older tutorials

The official fonts documentation says dynamic font loading arrived in 1.92 and requires updated renderer backends capable of texture updates. Earlier advice about prebuilding all glyph ranges may be outdated for such builds. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Pin the exact Dear ImGui version and backend commit. For 1.92+ evaluate the dynamic path and font source support; for older versions plan glyph ranges and atlas uploads according to that version’s documentation. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not mix code snippets from different major font approaches and assume one configuration works for every renderer. A backend lacking the required texture feature can make missing glyphs a runtime problem. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Test a non-Latin string that was not visible at initialization, then examine whether its glyphs appear with the actual distributed renderer. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

7. Load fonts, not just Unicode strings

UTF-8 is a representation of characters, while fonts supply glyph shapes and the renderer draws them. A successfully decoded character may still be unavailable in the selected font. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Choose a licensed font set with verified script coverage. Check merging or fallback behavior against the actual font APIs in the pinned version and monitor memory and texture behavior. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not treat a default bitmap font as evidence that your application supports Chinese, Arabic or emoji. Font size and rasterizer differences also affect readability. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Measure real screen output in each claimed language at supported DPI scales rather than comparing glyph names in a font table. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

8. DPI, scaling and translated layout

Translated strings often have different widths, and high-DPI settings can magnify earlier layout weaknesses. The font system and widget dimensions must respond together. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Use appropriate style and font scaling for the pinned version, and let long labels wrap or use a wider layout without shrinking critical warnings to unreadable sizes. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: A language switch can change text width while the button’s visual placement remains fixed. Overlap and clipping may hide required conditions or create misleading click regions. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Open the same dialog at common desktop DPI scales and narrow windows, then verify readable text, stable controls and correct keyboard focus. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

9. Right-to-left and complex-script limitations

Rendering some Unicode characters does not establish reliable shaping, bidirectional layout, caret movement or language-specific typography. Dear ImGui text support should be evaluated for each intended writing system. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Test representative Arabic, Hebrew, Indic and mixed-number strings only if those languages are in scope, and use a proven text-layout solution or an alternate UI for features beyond the library’s capabilities. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not advertise complete support on the strength of isolated glyphs. An apparently legible label can contain reversed punctuation or incorrect joining that alters the meaning. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Have a competent native-language reader use real dialogs and editable fields, not just review static screenshots. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

10. InputText is user data and needs separate care

ImGui::InputText and related controls manage editable text and buffers. User-entered names and notes must survive language switches while placeholder labels and help messages change. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Keep buffer ownership stable, size buffers safely and preserve typed values and selection where possible while redrawing localized labels. Test Unicode composition and copy-paste on supported platforms. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not translate user data or rebuild an input buffer from localized placeholder text. A changed widget ID can also disturb focus and editing state. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Enter an accented note, change language during editing, save it and inspect the exact stored content and current control identity. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

11. Numeric displays and grammatical messages

An observatory tool may show one observation, many observations or none. The target language can require plural categories or reordered sentence components. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Use a message formatter capable of whole-sentence patterns and pass typed numeric data. Format units, decimals, dates and time zones deliberately instead of concatenating English fragments. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not turn 1.5 into an unrelated value while adapting separators, or assume that the grammatical form for two is the same as for five. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Test counts, negative values if applicable, scientific notation and local date formats with real translated sentence context. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

12. Tables, sorting and stable row identity

Interactive tables present a special challenge because sorting or filtering changes visible position. Translation can change column headers and displayed categories while row identity must remain fixed. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Use stable record IDs to define row scope and preserve selection. Localize headers and values without serializing translated labels as data identifiers. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: A row keyed by its display title may move or change after translation and accidentally carry the wrong selection or context menu. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Sort a table, switch language, filter it and confirm that the selected observation ID stays unchanged. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

13. Popups, destructive warnings and action clarity

Deleting an annotation or discarding a session may be irreversible. A correct translation requires the condition, object and consequence to be readable in the active language. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Show a complete localized warning and distinct Cancel and Discard actions. Keep popup identity stable and preserve pending action state during locale changes. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not abbreviate away a negation or condition to fit a small dialog; nor should a translated caption be allowed to change the pending command by changing widget identity. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Switch locale while the popup is open, then use Cancel and verify no data was lost. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

14. Accessibility beyond visual glyphs

A developer tool can be multilingual but still unusable for some people because of keyboard focus, contrast, small fonts or missing assistive-technology semantics. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Test navigation and legibility with keyboard and different DPI settings; evaluate whether the platform and product require accessible native alternatives for features the toolkit cannot supply. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not claim a screen-reader-compliant interface solely because every visible English string has a translation. That requires separate technical evidence. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Ask representative users to locate controls and complete a critical action without relying on mouse precision or developer knowledge. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

15. Packaging, fonts and release resources

An editor launched from its source tree may have access to local fonts and language files that disappear after distribution. Runtime working directories and platform paths vary. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Bundle approved catalogs and fonts, verify licenses and test clean installs on each supported operating system and renderer backend. Keep diagnostic messages separate from user-facing wording. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not count compilation as proof of localization. Missing fonts and malformed asset paths can appear only on another developer’s or customer’s machine. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Install the actual release package without development resources and complete one full multilingual workflow. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

16. Maintain changes without corrupting meaning

A new version of the tool may rename a command, alter a data-loss condition or add a setting. Existing translations can become incorrect even when the old key still resolves. In this immediate-mode interface, the effect is visible on the next frame, but that does not imply the persistent state or the intended user action is correct.

Practical implementation: Track source revisions, catalog revisions and reviewer signoff. Reopen affected translations when the underlying action changes and audit stable widget IDs during UI refactors. Keep the first test small: one ordinary button, one dangerous confirmation, one edit field and one table with repeated actions. If those survive switching, you have evidence that the architecture is sound.

Failure to avoid: Do not silently reuse a previously approved translated phrase for a different action just because the English wording appears similar. Distinguish presentation from control identity and user data before altering the code. A localized string that prints successfully can still point to the wrong object or hide essential wording.

Acceptance evidence: Compare the updated dialog and its action with the previous release in every language that remains supported. Capture the actual build, selected language and exact interaction steps so that a teammate can repeat the result. Test both the visible wording and the command executed by the control.

Thirty practical Dear ImGui localization troubleshooting cases

The following cases are designed as small experiments. Start with what the user sees. Identify the technical boundary that could cause it, repair that boundary and confirm the outcome in the final build. A code review alone cannot detect every multilingual text-width or input problem.

1. Translated button stops responding

What you notice: A button works in English but behaves inconsistently after the label changes. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The visible caption participated in the widget ID and altered persistent identity. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Attach a stable hidden ID or stable PushID scope separate from the translated caption. Test the result this way: The same button triggers the same command in both languages. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

2. Two Save buttons interfere

What you notice: Saving row A seems to activate row B after translation. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Repeated widgets used identical hidden IDs within one scope. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Include stable record identity in the ID stack for each row. Test the result this way: Both rows retain independent click and focus behavior. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

3. Popup closes after language switching

What you notice: The discard confirmation disappears and cannot be reopened normally. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The translated popup title changed the identifier used by OpenPopup or BeginPopupModal. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Use stable popup identifiers and localize only visible content. Test the result this way: The popup remains open and Cancel preserves data. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

4. A percent sign corrupts text

What you notice: A translated note containing % produces unexpected output. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Untrusted or translator-controlled text was passed to a printf-style formatting API. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Use TextUnformatted for complete plain strings and a safe formatter for data parameters. Test the result this way: Literal percent signs appear as written. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

5. A Chinese heading shows boxes

What you notice: The label contains valid UTF-8 but renders no glyphs. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The selected font lacks the required characters. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Load and license a suitable font and verify runtime glyph loading for the pinned ImGui version. Test the result this way: A native reader sees the complete text in a release build. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

6. Font guidance from an old tutorial fails

What you notice: An atlas call from a previous release no longer matches current behavior. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Legacy prebuilt glyph instructions were mixed with 1.92+ dynamic-font APIs. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Read the versioned official FONTS documentation and align renderer backend and font setup. Test the result this way: Unseen glyphs can load through the supported path at runtime. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

7. Non-Latin text works in debug but not release

What you notice: A translated menu renders correctly in a development executable but not the installer. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Font paths or font sources were not bundled for the installation layout. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Add packaged assets and validate actual runtime resource paths. Test the result this way: A clean machine shows the same approved wording. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

8. A Cyrillic string becomes mojibake

What you notice: Letters appear as nonsensical symbols. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Compiler source encoding or catalog decoding is inconsistent. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Validate UTF-8 bytes and compiler flags, then inspect text with the encoding debug tool. Test the result this way: The bytes entering ImGui represent the intended code points. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

9. An Arabic word appears in reverse order

What you notice: The script’s code points exist but reading order and joining look wrong. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Glyph availability was mistaken for a full shaping and bidirectional text engine. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Use tested shaping and layout support where needed, or limit the advertised language feature honestly. Test the result this way: Native readers confirm full sentences, punctuation and mixed numbers. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

10. One screen is too narrow in German

What you notice: A translated option covers the control beside it. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Fixed English geometry and no wrapping policy were retained. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Reflow the interface and measure the actual rendered phrase at the supported font size. Test the result this way: All actions remain visible in narrow windows. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

11. Keyboard focus jumps on locale change

What you notice: An editor loses its selected InputText field after language switching. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The edit control’s ID changed with its translated label. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Keep a stable ID and preserve the existing data buffer. Test the result this way: Typing continues in the correct logical field. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

12. A string disappears after a frame

What you notice: A translated tooltip sometimes contains garbage characters. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The UI received a pointer into destroyed temporary storage. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Keep the std::string alive through the ImGui call and avoid persisting invalid pointers. Test the result this way: Repeated rendering and rapid locale switches show stable text. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

13. The user note changes language unexpectedly

What you notice: Typed observations are rewritten or replaced. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: User text was passed through the application translation catalog. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Translate only interface copy, not user data. Test the result this way: The note is byte-consistent after locale switching and saving. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

14. Decimal values mislead readers

What you notice: A measurement uses an ambiguous comma or period. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Display formatting used the English locale regardless of the chosen interface. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Use an appropriate locale-aware numeric formatter and label the unit. Test the result this way: Readers understand the same numeric value in every edition. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

15. One observation has plural grammar

What you notice: The UI states a malformed phrase for 1 observation. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The number was concatenated into a fixed English sentence. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Use complete grammar-aware messages with tested quantity forms. Test the result this way: Zero, one and multiple values read naturally. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

16. A filter selection switches records

What you notice: Changing language selects another observation. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Table state or row IDs were tied to translated titles or display order. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Scope rows by stable record identity and retain selection by ID. Test the result this way: Sorting and switching preserve the same selected record. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

17. An icon says the opposite of a label

What you notice: The button text means Reject but the icon suggests Accept. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Review covered strings without adjacent visual context. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Review the whole control and adjust iconography or label semantics. Test the result this way: A new user predicts the intended action. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

18. A warning loses its condition

What you notice: The translation omits ‘if changes are unsaved’. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Reviewers were given fragments without risk context. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Supply full action conditions and ask for fluent in-context review. Test the result this way: Users know exactly when data would be lost. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

19. A font suddenly grows memory usage

What you notice: A large multilingual dataset causes excessive texture churn. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Dynamic font behavior and renderer texture updates were not profiled under realistic glyph loads. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Test expected scripts and workloads on the pinned 1.92+ backend, profiling font memory responsibly. Test the result this way: Text remains readable within an acceptable resource budget. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

20. High DPI makes text and hit areas disagree

What you notice: A label appears large but the control target is cramped. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Font scaling and widget geometry were not validated together. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Apply version-appropriate DPI scaling and retest input dimensions. Test the result this way: Keyboard and pointer actions remain easy to reach. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

21. A font file cannot legally ship

What you notice: The release contains an unlicensed redistributable font. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Font selection was made without asset provenance review. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Select a properly licensed alternative and record attribution requirements. Test the result this way: Every bundled font has documented rights. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

22. Tooltip content truncates

What you notice: A long translated hint disappears at the right edge of the application window. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The tooltip used a width suitable only for the English string. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Use measured wrapping and window constraints. Test the result this way: All instructions are readable at supported window sizes. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

23. The wrong Save button activates twice

What you notice: A translated list has duplicate action labels in repeated rows. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The ID stack does not include unique row identity. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Push stable record IDs, then draw localized captions. Test the result this way: Each row executes exactly once on its own object. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

24. An input field mishandles emoji

What you notice: A note containing combining characters edits unexpectedly. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Buffer policy or input path assumes byte length equals character count. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Use documented UTF-8 buffer handling and test real composition. Test the result this way: Input survives edit, copy, paste and reload. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

25. A debug key reaches customers

What you notice: A label shows dialog.discard_key instead of the user-facing warning. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The catalog lookup lacks a reviewed fallback and missing-key gate. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Log the missing ID privately and show an approved safe message, blocking ambiguous destructive actions. Test the result this way: No raw keys appear in the shipped tool. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

26. Language selector is unreadable

What you notice: A user chooses an unfamiliar language and cannot return. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Language names and settings navigation are themselves hidden behind translation. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Keep recognizable language names and a consistent recovery path. Test the result this way: A tester can change back without instructions. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

27. A stale translation survives a feature change

What you notice: A new Save behavior is described with the old word choice. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Catalog approval was not invalidated when the command semantics changed. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Track changed source context and reopen those messages for review. Test the result this way: The new behavior and each translation agree. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

28. A font file path works only in an IDE

What you notice: Fonts load from a relative dev directory but fail from a customer launcher. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Working-directory assumptions are embedded in font loading code. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Resolve asset paths relative to the packaged installation intentionally. Test the result this way: Launching from a different directory still finds the font. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

29. The renderer backend lacks dynamic texture support

What you notice: A new language shows missing glyphs until restart. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: The selected Dear ImGui dynamic-font path requires a newer compatible renderer backend. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Update or select a compatible backend and test texture updates at runtime. Test the result this way: A newly encountered script draws without relaunch. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

30. No accessible alternative exists for a critical control

What you notice: A screen looks translated but assistive users cannot operate the action. Record the current locale, font configuration and the exact control involved. The goal is to distinguish an unreadable label from a control that now points to the wrong underlying action.

What to investigate: Visual localization was mistaken for complete accessibility. Inspect identifiers, lifetime of strings, catalog encoding, rendering and state as separate layers before guessing that a translation itself is wrong.

What to change: Provide separately verified navigation and accessible alternatives where the toolkit or product needs them. Test the result this way: Representative users can complete the same critical workflow. Validate on the intended release backend and capture an exact, repeatable before-and-after sequence rather than relying on an isolated screenshot.

Four-week implementation plan

Week 1 — Message and identity inventory

Map every label, tooltip, popup, table column and input field. Record the underlying command and stable object identity for each. Audit controls whose identifiers are implicitly derived from visible labels and decide where hidden IDs or PushID scopes are needed. Choose a complete two-language vertical slice containing a destructive action and a retained edit buffer. Deliver a translation catalog with context notes and a widget identity inventory.

Week 2 — UTF-8, fonts and UI refresh

Wire catalog lookup to visible text while keeping stable control IDs. Validate encoded bytes in actual program builds and use the project’s encoding debug tools when needed. Pin the Dear ImGui version, renderer backend and intended font implementation. Load suitable font assets and test one target-language string not encountered at startup. Deliver a bilingual running screen in which focus, popup state and table selection survive language changes.

Week 3 — Meaning, typography and accessibility

Review long translations, mixed numbers, punctuation, plural examples and the exact consequences of buttons with native-language readers. Exercise high DPI and narrow windows. Test real input fields with Unicode composition and ensure user data is not translated. Investigate accessibility and keyboard navigation independently from visual correctness, providing suitable alternatives if necessary. Deliver reviewer-approved critical paths and a transparent list of unsupported behaviors.

Week 4 — Reproducible release checks

Install the application from the actual packaged artifact on each supported operating system and renderer backend. Test missing resources, fonts, unfamiliar locale preferences, stable row identities and destructive dialogs after a live switch. Record catalog revision, Dear ImGui version, backend, platform and build ID. Publish only language editions with correct behavior and a named owner for later content changes.

Final release checklist

Every translated visible widget label retains a deliberate and unique internal identity.
Popup, table and InputText state survive language switches and sorting.
Catalog bytes and compiler string encodings are valid UTF-8.
Plain translator-controlled text is not used as a printf-style format string.
Fonts and renderer backends are compatible with the pinned Dear ImGui version.
Newly encountered glyphs are tested in the actual font-loading implementation.
Claims for complex scripts follow native-speaker and text-input validation.
Long translations remain legible at narrow windows and high-DPI scales.
Variables, numeric formatting, dates and plural messages preserve meaning.
User-entered data is unchanged by presentation-language selection.
Critical confirmations state the true action and consequence.
Release packages include font assets and applicable redistribution rights.
Keyboard and accessibility behavior have independent acceptance evidence.
Missing catalogs or raw keys never expose an unsafe ambiguous command.
A defined owner reopens affected translations when product behavior changes.

Frequently asked questions

Does Dear ImGui provide translations automatically?

No. It displays the text your program supplies. You must build a catalog, select language, review wording and ensure each translated message reaches the correct widget. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Why can a translated label break a button?

ImGui may use the label as part of widget identity. Separate visible translated text from a stable internal ID with the appropriate ## or ### convention or a stable ID scope. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

What is the difference between ## and ###?

Both are documented ID label conventions, but they have different semantics for visible labels and identity. Read the exact Dear ImGui ID documentation and choose a consistent stable-ID design. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Should plain translations go through ImGui::Text?

Prefer ImGui::TextUnformatted for plain translator-controlled or user-supplied sentences. Formatting APIs should receive trusted format strings and appropriately typed arguments. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

What changed in Dear ImGui fonts in version 1.92?

A newer dynamic font system can load previously unseen glyphs with compatible backends, reducing the need to prebuild fixed ranges. Verify your installed version and renderer before adopting its APIs. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Does UTF-8 guarantee Chinese, Arabic or Hindi support?

No. Encoding, font coverage, shaping, bidirectional text, line breaking and input editing are different requirements. Test every intended language on the actual display and edit path. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Why do fonts work on my machine but fail for a user?

The installed program may have different working directories, fonts and render backends. Package approved font sources and exercise a clean install. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

How should plurals and dynamic values be translated?

Use complete locale-aware message patterns rather than English sentence fragments. Pass typed quantities, dates and units, then test representative combinations. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Can language switching keep popup state?

Yes, if popup and widget identities are stable and the application updates presentation without rebuilding pending actions. Test while a confirmation remains open. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Should user-entered notes be translated automatically?

Not as part of ordinary interface localization. Preserve user text and translate labels, status descriptions and help content around it. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Is a multilingual ImGui tool accessible by default?

Not necessarily. Accessibility needs independent keyboard, readability and assistive-technology validation; for some requirements a separately accessible UI may be necessary. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

When should we release a language pack?

After wording, font coverage, ID stability, controls, input, error recovery, packaging and target-language review pass for the exact versions being distributed. Confirm this behavior against your pinned Dear ImGui version and backend; the shipped interface, rather than a code snippet, is the final evidence.

Official documentation and further reading

Continue with the wider translation architecture

This child guide addresses Dear ImGui’s unusual connection between labels and widget identity, plus UTF-8 and version-specific fonts. Read the translation master for meaning and quality principles, or use the series index for another platform’s implementation.

Master Art of Translation · Translate Like a Pro index · Previous: Kivy localization

Translate Like a Pro | 7300 — Dear ImGui C++ Localization, UTF-8 Labels, Stable Widget IDs, Dynamic Fonts and QA