Localization Checker Manual, part 2: your project, the Console, and known limits

Manual part 1 (Manual-Checks.md) explains checks and results. This part separates Edit mode scans, temporary Scene previews and Play mode patrols, then describes Console output, operating assumptions and known limitations.

Scan, preview and project safety

Edit mode scan
  Original scene objects or saved prefab asset
    ↓ copy into a hidden preview scene
  Remove project scripts; isolate external references
  Replace fonts and materials with in-memory copies
    ↓ apply translations and measure with the engine
  Destroy the copies

Scene preview
  Temporarily display a translation on an original scene component
    ↓ selection changes or preview ends
  Restore the original value

Scans. The scanner does not edit, mark dirty, record Undo for, or save your original scenes, prefabs and assets. It leaves Game view resolution settings unchanged. This applies to the scanner’s own operations; Unity asset loading and project serialization callbacks can still have effects, as described below.

• Scripts on copies. Project scripts are removed before normal wake callbacks run. Events are disabled and references outside the copy are cleared. Copying itself uses serialization: constructors and serialization callbacks can still run, as they can when Unity duplicates an object. Do not treat scans as a sandbox for code with serialization side effects.
• Fonts and materials. TextMeshPro can add characters to dynamic fonts and modify materials during layout. The scan substitutes in-memory copies of reachable font assets and materials, protecting originals from those measurement changes. It does not write TMP Settings.
• Unity Localization. Scans use read-only access without changing Localization Settings or requesting translated strings through the localization runtime. The Play mode patrol separately reads and changes the selected locale.
• Player builds. The checker is editor-only, has no Resources folder and adds no runtime code or assets to a build.
• Stored settings and results. Project settings go to ProjectSettings/LocalizationChecker.json. Window language, patrol toggles, list columns, side-by-side options and the last export folder use per-user Editor preferences. Scan results are not saved. Completed patrol pages use editor-session storage; their screenshots go to Temp/LocalizationChecker/Patrol, outside Unity’s imported assets. Exports cannot target Assets, Packages or package folders.
• Clipboard access. While its window is open, the checker reads clipboard text when the Editor regains focus to recognize commands copied by an HTML report’s Select in Unity action. It writes to the clipboard only when you click a copy action.

Scene preview. Selecting an overflow issue temporarily writes the translation onto the original scene text component. This is separate from scanning. It records no Undo and marks nothing dirty. The checker restores the original when you select another row, leave or close the window, start a scan, save or close a scene, enter Play mode, recompile or quit. Side by side renders copies without making this temporary change to the original.

Unused-asset unloading. After a scan completes, fails or is cancelled, the checker unloads unused assets through EditorUtility.UnloadUnusedAssetsImmediate. This prevents localization tools from later rewriting prefab assets left loaded by the scan. Unloading can discard unsaved in-memory changes made by scripts to assets that were not marked dirty. Mark those changes dirty or save them before scanning.

Unity asset loading. Reading a prefab asset can run its scripts’ constructors and serialization callbacks, just as selecting it in the Project window can. TextMeshPro may upgrade font or sprite assets saved before version 1.1.0 when first loaded; a later project save may persist that upgrade. These Unity behaviors are outside the scanner’s copy isolation. Scan data instead reads saved ScriptableObject text without loading the assets.

What the patrol changes, and how it puts it back

The patrol operates only in Play mode. Your game and localization code continue running while it switches languages.

The patrol cannot undo unrelated effects of your game’s language-switching code. Review that code before using a custom switch that writes persistent settings.

The Console

• A normal scan produces no Console messages. During copied-UI layout, the checker suppresses TextMeshPro and uGUI warnings such as missing-character warnings. Errors and exceptions remain visible.
• Unreadable tables appear under Sources with their reasons rather than generating Console logs.
• A scan-stopping error appears in the window as The scan stopped: followed by the reason.
• An unreadable settings file produces one warning and falls back to defaults.
• TextMeshPro may print a harmless “Units Per EM” message when first reading a font asset saved with an older TextCore version.
• Patrol failures appear in the bar as The last patrol ended on a failure: with details. If stored session pages cannot be read, the checker logs one warning and discards those pages; otherwise the patrol produces no Console messages of its own.
• TextMeshPro warnings from the running game’s original UI are not suppressed by the patrol.
• Command-line scans write their summary, notes and verdict to the Editor log.

Scan prerequisites

• Open scenes use their current loaded state. They must have been saved at least once, but current unsaved changes are included. A Unity Localization editor preview or [ExecuteAlways] script may already have changed a component’s value; clear the preview language before scanning.
• Prefab scans use the saved asset. Save Prefab Mode edits first if they should be included. Scanning, Scene preview and manual mapping require scenes with a saved path; never-saved scenes are unsupported.
• Keep the Editor stable during a scan. Closing the window or deleting scanned objects while progress is shown is unsupported. Cancel stops after the current step and produces no results.
• EditorOnly differs by scope. Scene scans omit these objects; prefab scans include them. A prefab may therefore report text that is stripped from a scene build.
• Each scan has one source language.

Patrol prerequisites

• Focus Localization Checker before shortcuts. Its tab must be in front for F8 and the arrow keys. These are not global shortcuts. After interacting with the Game view, click the checker window, then press F8. Use the button if another shortcut intercepts the key.
• Keep the Game view visible. Dock the checker in a separate tab group. A hidden Game view does not draw and cannot provide a screenshot.
• Allow enough frames after switching. Except for waiting on Unity Localization’s displayed LocalizeStringEvents, the patrol relies on the configured frame count. This is measured in frames, not seconds. A late update may leave the previous language on screen without a warning. Increase the wait and recheck if screenshots show stale values.
• Let Play mode advance. Checks stall while paused. In Unity 6 they also stall when the Editor is in the background and Run In Background is off. Keep Unity in front or enable Run In Background before entering Play mode.
• Keep the page and language stable. Your language-reporting method must return the selected code, ignoring case. An external language change or departure from the page ends the check and discards the unfinished page.
• Closing the window does not stop the patrol. Reopen it to stop the patrol, or leave Play mode.
• Completed and unfinished pages differ. Completed pages remain across leaving Play mode and domain reloads until cleared or the Editor exits. An interrupted check loses only its current unfinished page. Clear patrol results removes retained pages and screenshots.
• Domain reload may be on or off. With it off, scan results also survive Play mode. With it on, scan results are cleared on entry and the window rescans after exit.

Known limits

Overflow and layout

• A scan reveals all hidden objects in a Canvas together. Mutually exclusive tabs may crowd each other in the copy. Code that fills or resizes a panel when shown does not execute there; check those screens with the patrol.
• Project scripts and engine components that execute in Edit mode are removed from copies. Their runtime changes to dimensions, fonts and children are absent, as are list items or other content created by code.
• An axis controlled by layout is excluded from text overflow checks, including cases using Force Expand or flexible space. Wrapped text grows in whole lines, which can prevent a near-overflow finding.
• Screen Space - Camera Canvases use the camera viewport configured in the editor at scan time; later runtime camera changes are not included.
• Conflicting fitters, such as Aspect Ratio Fitter and Content Size Fitter, may never settle. Their roots report “its layout does not settle”.
• Text auto-sized too small compares the rendered size with the component’s configured maximum. An unrealistically large maximum can flag every language. Set a maximum that fits the source-language design.
• Grid Layout Group cells are not checked. Possible false positives include an input field squeezed by its value, a space-reserving object, intentional overhang and panels positioned by code.
• Scan pseudo-localization estimates expansion; it does not predict every translation.

Overlapping texts

• Scans use scene placement. They cannot reproduce components shown together, moved or spawned by runtime code.
• Rendered text bounds form one rectangle around all characters. A short final line leaves empty space inside that rectangle. Scans do not apply masks, so content scrolled out of a viewport can still participate in comparisons.
• Different Canvases are not compared in scans. Patrol pages compare only within each root Canvas, excluding overlaps with a popup on a separate root Canvas.
• A pair already overlapping in the source scene is excluded, even if a translation increases the overlap.
• Patrol comparisons use readings taken at different times. Enable Freeze game time before checking an animated screen.

Line breaks

• Japanese and Chinese checks follow the strict W3C jlreq and clreq rules. Thai checks recognize syllable structure but do not segment words. An unmarked break between Thai letters is therefore a possible word split, even when it happens to fall between words.
• Korean checks are scan-only. TextMeshPro reports the disabled Use Modern Hangul Line Breaking Rules setting once per checked Korean language. From Unity 6000.3, UI Toolkit checks each element for word splits. Legacy Text already breaks Korean at spaces.
• Scans and patrols check TextMeshPro and legacy Text line breaks. Scans from Unity 6000.3 also check UI Toolkit, excluding strings with rich-text tags or escape sequences and counting those exclusions in scan notes. Patrols do not check UI Toolkit line breaks.

Missing glyphs

• Scan glyph checks exclude characters inside <font=…> tags, style definitions, escape sequences, Smart String branches, variable samples and generated pseudo-translations.
• Case conversion is culture-independent. Device-specific casing, such as Turkish uppercase i becoming İ in TextMeshPro, is not reproduced.
• I2 secondary-term font swaps and custom-code font swaps are not detected. Configure Fonts by language for them.
• A dynamic font configured to clear its atlas at build time is checked in its current Editor state.
• Tuanjie’s Advance Text Processing shapes through the source font file, while these checks look up individual characters.
• Intentional characters can trigger encoding warnings: Persian zero-width non-joiners, zero width spaces used as line-break hints outside Thai translations or in scene text, and private-use icon-font characters.

UI Toolkit (Unity 6)

• The checker cannot distinguish clipping through overflow: hidden without an ellipsis from overflow, and does not account for ancestor clipping.
• Overlap checks use the full element box rather than rendered letters. Separate documents are never compared.
• The engine does not expose text auto-size configuration; measurement uses the font size already laid out.
• Global fallbacks come from the panel’s Text Settings. The engine’s built-in default Text Settings are not exposed.
• Scans cannot see bindings assigned by code, code-assigned strings or runtime-created elements. Use the patrol for displayed runtime UI.

Placeholders, tags and translations

• Removing a Smart String plural format in a language without plurals can still produce a count mismatch.
• Asset-name checks search the whole project. A matching font, sprite or style name does not prove TextMeshPro can resolve it at runtime.
• A non-Latin tag value, such as an intentionally Chinese style name, can still receive Critical severity. Review the actual reference.
• Same as the source text includes proper names, OK and regional language variants. TODO is not treated as a marker in Spanish, Portuguese or Galician.
• Mojibake recognition covers UTF-8 misread as Windows-1252, Latin-1, GBK, Windows-1250, Windows-1251, Shift-JIS or CP949. Other encodings are not covered. Very short corruption can be missed. GBK corruption can also escape individual-value detection when uncommon characters occur alone or in pairs among common ones; broader table-level corruption is still checked.
• Punctuation, whitespace, bracket pairing and numeric checks identify differences, not linguistic errors. Spanish changing ! to . or a converted unit may be correct. Review such findings with the language’s conventions in mind.
• Translation may be too long uses text units, counting wide East Asian characters as two and combining marks as zero. It knows neither font nor bounds. Use the patrol to measure dialogue and runtime text.

Texts outside localization

• Undetected localization systems may appear as Hard-coded text or May be set by a script when a script field references the component.
• If keys are identical to English source strings, the values also match translations and may be reported as hard-coded.
• May be set by a script includes any script field referencing the component, even if the script only changes its color.

Translation files, Unity Localization and bindings

• CSV and TSV require UTF-8; GBK is unsupported. A duplicate key prevents the whole file from being read.
• Quoted TSV cells retain their quotes as content. Export CSV when the originating tool quotes TSV. Google Sheets TSV downloads flatten cell line breaks to spaces; download CSV to preserve them.
• XLIFF inline codes are unsupported. Export rich-text tags as plain text, as Unity Localization does.
• Excel values are read without cell display formats. Whole numbers of up to 15 digits are normalized to digits, including values stored as 100001.0. Other numbers retain their stored representation; dates usually become serial numbers. Formulas use their last saved results. Keep keys and translations in text cells.
• PO plural counts come from Plural-Forms without checking that the count suits the language. With msgid language empty, msgid is only a key and forms are compared by index with the source language. Thus source form 0 One apple can report an extra number placeholder in Russian or Japanese form 0. A header specifying a count without plural= requires all placeholders in every form. Files arranged as de/LC_MESSAGES/messages.po are grouped separately by folder when dragged or suggested; add them together with Choose… to create one table.
• Nested JSON uses dotted keys such as menu.start. Different key-joining conventions can produce missing-key bindings.
• Language codes identify distinct languages: zh-CN and zh-Hans are not aliases here.
• Unity Localization entries with duplicate key names or Id 0 are skipped. Smart Strings are compared as stored. Only locales listed in the Editor are read; Add All under Available Locales adds others. Versions outside 1.5.2 to below 2.0 are rejected under Sources.
• Manual mappings belong to individual objects. Prefab assets and their scene instances require separate mappings.
• Exports include full paths for translation files outside the project. Those paths may contain a user name.

Preview, side by side, heat map, comparison

• Scene preview and side-by-side scan rendering support open scenes saved at least once, excluding prefab assets. The Scene view uses the Game view size rather than the scan resolution.
• Side-by-side images are limited to 8192 pixels per side and remain in memory until exported.
• Heat maps cover objects in the displayed scenes. Hierarchy marks require the classic Hierarchy. From Unity 6.6, the new Hierarchy replaces it and does not show these marks.
• Since the last scan is temporary. Closing the window or reloading scripts discards the comparison baseline. Tables are identified by name, so renaming a table makes its findings appear new.
• HTML Select in Unity requires the checker window to be open and the report to belong to the current project. Closed scenes are pinged rather than opened.

Patrol

• A component can count as displayed even when it is off screen, behind a stencil Mask, covered by other graphics, or invisible through its own color or alpha.
• The patrol does not inspect legacy Text glyphs. Scans cannot see strings assigned only at runtime, so missing characters in such legacy components may escape both. Screenshots reflect the Editor computer’s available fonts because legacy dynamic fonts can use them.
• Dynamic OS font rendering depends on the Editor computer’s fonts. A missing character there may be available on a target device.
• World Space Canvases without either an assigned camera or a main camera receive no outlines.
• Runtime-created objects have IDs valid only for their Play session. Objects in DontDestroyOnLoad or never-saved scenes have no persistent IDs, so they cannot supersede scan issues or be selected later.
• Runtime string changes, including Smart String formatting, trimming, I2 spacing and right-to-left processing, prevent overflow supersession when the displayed value differs from the scan’s measured value.
• Retained pages remain evidence of their capture time. Recheck after screen, layout or font changes, or use Clear patrol results.
• Pseudo-language detection relies only on brackets. Intentional literal player names, language names and codes can be reported; use applicable ignore rules. Content combined before localization adds its brackets, including Smart String variables and nested localized strings, appears as one string and is not detected as concatenation.
• If the game also requests a Unity screenshot in the capture frame, one of the two screenshot files may not be written.
• Reading displayed text every frame adds Editor overhead, which grows with the number of components. Review performance on large screens; development measurements around 1,000 components were approximately 7–8 ms per frame on one machine and are not a performance guarantee.
• With domain reload disabled, Unity Localization can fail to finish initialization on repeated Play mode entries, including without the checker. The patrol refuses to switch and reports the reason in that state.

I2 Localization

• I2 Localization 2.8.22 is the documented verification version, using small projects and one game project. This does not establish compatibility with every I2 configuration.
• Conflicting translations for a term across language sources prevent that language’s text from being measured.
• Scans combine sources from all scoped files. The running game can combine only sources loaded together, so its lookup context may differ.
• Scans do not apply translation-changing callbacks or events, joined-language character spacing, right-to-left fixes or secondary-term font swaps. Check the affected screens with the patrol.

Editors and packages

Documented development checks cover Unity 2022.3 LTS, Unity 6 versions 6000.3–6000.6, and Tuanjie Engine 2022.3 versions 1.5 and 1.10, with TextMeshPro 3.0 and 3.2, uGUI 1.0 and 2.x, and Unity Localization 1.5.2 or later below 2.0. TextMeshPro 3.2.0 previews pre.1 and pre.2 interpret some rich-text cases differently and have known check failures; prefer stable package versions.

Documented patrol coverage includes Play mode on Unity 2022.3 and Unity 6 versions 6000.3, 6000.4 with I2, and 6000.6, with domain reload enabled and disabled, plus Device Simulator. Tuanjie 1.5 and 1.10 received limited patrol probes; full Play mode compatibility is not established by those probes.

• Without the Unity UI package (uGUI), the checker compiles but exposes no menu and checks no text components.
• Without TMP Essential Resources, TextMeshPro Canvases are not measured; results explain the omission.
• Without the Test Framework package, the included tests are excluded from compilation.

Scans do not cover UI Toolkit on Unity 2022.3 or Tuanjie, UI text outside a Canvas, code-assigned runtime strings or runtime-created UI. A 3D TextMeshPro outside a Canvas has no layout or overlap check and no side-by-side image. Use the patrol for runtime strings and UI on the screens you visit; it does not establish coverage for unvisited screens or target-device rendering.