iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To localize a Godot game without breaking variable tags, keep each placeholder in the source string passed to tr(), then format the translated string afterward. Prefer named placeholders such as {character} and {weapon}: translators can move the values into the order their language requires without changing what each value means.
Keep placeholders in the string you translate
Godot must look up a stable source message in its translation catalog. If you insert runtime values first, the resulting text may no longer match the catalog entry. Translate the template first and format the returned translation:
message.text = tr("{character} picked up the {weapon}").format({character = "Ogre", weapon = "Sword"})Here, tr() receives the unchanged template. String.format() inserts the runtime values only after Godot retrieves the localized version. Godot’s Internationalizing games guide recommends named placeholders whenever possible because translators can change their order as well as their positions.
Positional placeholders such as %s can move, but their order cannot change, according to the same guide. That may constrain a translation when a sentence’s grammar requires the character and item to appear in a different order. Keep named identifiers stable and descriptive, and add translator comments when their meaning is unclear.
#1 Best Overall
Make sure Godot extracts the strings you expect
With a gettext workflow, configure the scene and GDScript paths in the editor’s translation template-generation settings, then generate a POT template. Godot’s extractor recognizes common calls such as tr() and tr_n(), selected scene text properties and UI methods, and file-dialog filters. It needs a constant string argument or right-hand expression; dynamically constructed expressions may not be extracted. Check the generated template rather than assuming every string was found. See the Godot 4.4 gettext guide for version-specific details.
Regenerate the POT when localizable strings or relevant scenes and scripts change. Create a PO file for each locale from that template, then merge future template changes into the PO files using gettext tooling or a compatible editor or platform. After a msgmerge, changed source strings are marked fuzzy. Godot skips fuzzy entries until someone reviews the translation and removes the fuzzy marker.
Rank #2
Keep PO source files under version control even if you compile them to MO files for runtime use. Godot’s 4.4 guide says MO can be worth considering for projects with several thousand strings or more; treat that as guidance, not a universal performance threshold. Add translator comments for context, and use recognized NO_TRANSLATE comments for strings that should be excluded from translation.
Choose CSV or gettext for the team’s workflow
Godot supports both CSV translations and gettext PO/MO files. Neither format is inherently safer for placeholders; choose based on how your team edits, reviews, and maintains translations. Godot’s documentation describes CSV support and notes that PO/MO support has been available since Godot 4.0. The latest documentation branch can include features not present in a released stable version, so check the guide for the exact Godot version you use.
Rank #3
| Consideration | CSV | Gettext PO/MO |
|---|---|---|
| Editing and collaboration | Consider whether the spreadsheet-style workflow fits your translators and review process. | PO is a standard text format with per-locale files that work well in version control; maintenance is more complex and may require gettext command-line tools. |
| Multiline strings | Assess how your chosen editor handles multiline entries. | The documentation identifies better support for multiline strings. |
| Contexts and pluralization | Compare the needs of your project with Godot’s extraction workflow. | The extraction workflow supports contexts and pluralization. |
| Runtime files for large projects | Choose according to the project’s loading and maintenance needs. | Compiled MO files may be worth considering at several thousand strings or more, per Godot 4.4 guidance; this is not a universal benchmark. |
The comparison reflects the features and trade-offs described in the current gettext documentation and the Godot 4.4 guide. The current documentation branch is a moving target; verify interface labels and feature availability against your installed release.
Use pseudolocalization to catch missing strings and layout problems
Enable pseudolocalization in project settings or at runtime while developing. Godot can accent characters, simulate text expansion, add a prefix and suffix, fake bidirectional text, and skip formatting placeholders. This helps expose untranslated strings and controls that are too small. The main guide notes that placeholders remain intact in pseudolocalized output, so you can check that formatting tokens survive while the surrounding text changes.
The pseudolocalization guide gives 0.3 as an example expansion ratio for increasing text length by 30%. That is an engine configuration example, not a measurement of how much a particular language will expand.
Pseudolocalization is an early structural check, not a substitute for reviewing actual translations. Godot warns that readable pseudo output does not effectively test font coverage for Chinese, Japanese, Korean, or right-to-left scripts. Test those scripts using real localized text and suitable fonts, then inspect the finished UI in the target locale.
Best Value
Test locale changes and right-to-left layouts in context
Godot recommends starting with the player’s preferred language, configuring a fallback for unavailable translations, and letting players change the language in-game. Locale identifiers are standardized by the engine, and loaded translations apply when the locale changes. Use the internationalization guide to check the relevant project settings and behavior for your Godot version.
Godot’s UI can automatically adapt several layout properties for right-to-left languages, including mirroring left and right anchors and margins, swapping text alignment, and reversing the horizontal order of controls in containers. The coordinate system itself is not mirrored, and non-UI nodes such as sprites are unaffected. Review scene composition and non-UI elements separately instead of assuming the entire game world will flip automatically.
Quick Recap
A practical pre-release checklist
- Pass a stable template containing placeholders to
tr(); format only the translated result. - Use named placeholders when translators may need to reorder values, and explain ambiguous identifiers in translator comments.
- Generate and inspect the POT, then regenerate and merge it when localizable source strings change.
- Review fuzzy PO entries and remove the fuzzy marker only after the translation is checked.
- Run pseudolocalization to find missed strings and layout overflow, then review real target-language text and fonts.
- Test right-to-left UI behavior and inspect non-UI scene elements independently.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches
