Localization: from catalog to UI — documentation

First translation, CSV or PO selection, language switching, fallback and UI checks before release.

Localize the game

Message translation, language selection, font rendering and localized resources are separate parts of the work. This section concerns the game language. Changing the portal language does not change your project settings.

Get the first translation

Prepare an RU/EN catalog. Use CSV for a shared table, or PO for per-language files, context and plural forms. Both guides provide complete input files.
Import and register translations in Project Settings → Localization → Translations. Register generated .translation resources for CSV, or the .po itself for PO. Loading a resource through ResourceLoader alone does not add it to translation lookup. See catalog setup.
Use the CSV example key PLAY for a check. After TranslationServer.SetLocale("en"), TranslationServer.Translate("PLAY").ToString() yields Play; after SetLocale("ru"), it yields Играть.
Put the key in a static Label Text and enable automatic translation. Text retains the source key; the displayed translation changes separately. For calculated captions, translate a complete template and refresh it on NotificationTranslationChanged. See the complete localized UI example.

Do not register multiple catalogs with the same key/context/language combination and rely on accidental override order. Choose stable keys and preserve formatting parameters in every translation.

Choose the next step

Task	Guide and outcome
Translate collaboratively in a table	CSV: locale headers, delimiters, quotes, context and plurals
Give translators separate catalogs	PO/gettext: Language header, context, plural forms and skipped entries
Select the player language	Locale codes: shipped-language lists, region and explicit language fallback
Refresh UI on a language change	Game internationalization: static/computed text, assets, fonts and UI direction
Find clipped or untranslated messages	Pseudolocalization: text expansion and C# placeholder limitations

Language changes and missing messages

Offer only languages whose catalogs ship with the game. An engine-recognized code does not mean a translation exists. TranslationServer.SetLocale() changes the current process locale and notifies UI; save the player preference separately, for example through settings and saves.

Set the fallback language through internationalization/locale/fallback and check a missing entry. If neither the selected nor fallback catalog has the message, lookup can return the source key. Text and resource fallback have different rules: without a matching localized resource replacement, the original resource is used, not automatically the text fallback-language alternative.

Plural lookup selects a template rather than inserting a number: format the complete message after TranslatePlural. Do not assemble a sentence from separately translated words. Player names and chat should not automatically become translation keys.

Check the result and export

Check	Expected result
Switch en → ru with UI already open	Static captions refresh; your handler recalculates computed captions
Leave a translation empty	The intended fallback text appears; an entirely unknown key appears as the key
Display a player name equal to a key	It remains player text when automatic translation is disabled
Show a long message at minimum window size	Text fits or wraps and controls remain accessible
Check required characters and RTL	The real font covers the text; direction and element layout are checked separately
Launch the exported game	Catalogs and localized assets are present, and language switching works outside the editor

Pseudolocalization does not replace real-language, CJK font, Arabic shaping or RTL checks. Label.Language does not select a translation catalog; Control.LayoutDirection does not select a message language. Also check resource removal by the export preset separately.

Examples in the linked guides were checked on the installed Windows runtime. This entry route reuses only the catalog, switching, fallback and format checks listed in its technical report. That report does not attest visual font coverage, RTL layout or exports on every platform.