GDevelop Localization Guide

GDevelop localization means designing and testing a multilingual game experience, not just translating a few labels. This complete GDevelop game translation guide explains JSON language resources, event-sheet variables, text objects, font coverage, locale selection and release quality assurance for independent game creators and international teams.

The crucial distinction is between what GDevelop itself documents, what an experimental or community extension supplies, and what a developer builds from events. The documented JSON Resource Loading extension is experimental. A separate community Translate extension describes its own JSON files and browser-language fallback features, which should not be presented as universal GDevelop behavior. The safest approach is to choose one compatible implementation and verify it in the exported game.

Our running example is a seaside rescue game with a harbour, a radio operator, an equipment shop, a storm warning and a rescue debrief. Players must understand when it is unsafe to launch, what a radio upgrade costs and whether accepting a mission is reversible. We will follow these decisions from their source English text through translated catalogs, actual game states, visible screens and the released game, so that a multilingual edition communicates the same meaning and consequences.

Quick answer: GDevelop translation checklist

Inventory every player-visible string, image and conditional message.
Choose one localization architecture and record the version of any extension used.
Keep stable keys and game logic separate from translated presentation text.
Define language preference, fallback, loading and persistence deliberately.
Check real sentences, numbers, plurals, fonts, warnings and line wrapping.
Test every supported language in the actual exported artifact.
Keep a reproducible build and a record of what was reviewed.

Why localization is a player-action problem
A worked harbour rescue route
Practical implementation decisions
Diagnosing visible failures
Three complete release approaches
A four-week improvement plan
Frequently asked questions and primary documentation

Why the whole player journey matters

A language review can say a sentence is fluent while a game test reveals the player pressed the wrong button. The two kinds of evidence answer different questions. A fluent reviewer can decide whether a warning is a warning rather than an invitation; a tester can verify whether the radio upgrade changes the right state variable and whether a purchase has the same cost in every language. Both are necessary. Comparing translations in a spreadsheet alone cannot expose text clipped by a button or a conditional branch never seen by the translator.

Start with the source-language route: title, language menu, harbour briefing, unsafe launch warning, equipment purchase, mission acceptance, mid-mission hazard and debrief. Record the player’s state at each stage. Then ask a target-language reader to take the same route without coaching. Before every consequential action, ask them what they expect to happen. An excellent translation allows the person to form an accurate expectation, even though its wording may differ structurally from English.

Source keys should identify purpose, not an English word. A key named action.go is ambiguous in a game that has Resume, Launch and Continue controls. A key named mission.launch.confirm tells a developer and translator which consequence matters. A location or screenshot note explains whether a concise imperative is friendly, dangerous or irreversible. Treat the dictionary as a map between meaning and program state, not a list of words to exchange.

Thirty practical GDevelop localization decisions

1. Inventory the full visible game

The title, settings, equipment shop, weather warning, rescue briefing, tutorial overlays and endings each need a resource entry. Walking through one successful route will not expose every conditional or failure message.

Record the scene, object, triggering event, text, screenshot and consequence. Inventory words embedded in sprites separately because a JSON text dictionary cannot modify them.

Test successful and failed launches, item purchase and refusal, pause, restart and the rescue debrief in two languages.

The useful check for inventory the full visible game is to watch a real player rather than merely look at a clean source file. In the harbour game the same screen may contain a warning, an available action and a cost. Record what the player believes will happen before pressing anything. If the next state surprises them, examine the text and the game rule together. A beautifully translated word in an unusable interaction is not a finished product.

2. Choose a documented text architecture

GDevelop supports event logic and extensions, but a project-specific JSON dictionary, an extension-based translation workflow and manually assigned strings are not interchangeable.

Select one lookup process and identify exactly which plugin or project events supply loading, fallback, formatting and switching. Note required versions.

Change one key and trace the resulting label from source JSON to live preview and exported web build.

This issue often hides until the project reaches a second language. English may have shorter labels, familiar punctuation and grammar that happens to match the original event structure. A reliable review repeats the relevant state with an extreme value or a longer sentence. Keep the original and target screenshots, a source revision and the actual expected result. Another person should be able to reproduce the check without opening the developer’s notes.

3. Treat JSON loading as a build dependency

The documented JSON Resource Loading extension is experimental and community provided. Its availability and precise action signatures are not guaranteed across unrelated GDevelop versions.

Pin the reviewed extension and make language resources part of the build review. Avoid presenting a third-party extension as a built-in universal i18n API.

Test missing file, invalid JSON and delayed load conditions in a clean environment.

Do not solve this by allowing a translation to become an internal game condition. Text is for the player; IDs, variables and event rules are for the program. If the two are confused, a harmless copy edit can produce a different mission. In a good multilingual build the displayed phrase can evolve while the underlying radio purchase, rescue branch or inventory condition remains verifiably stable.

4. Keep stable keys independent from copy

A label such as Go may mean resume, launch the boat or confirm a purchase. Translating one shared string for those different actions loses context.

Create intent-revealing keys like rescue.launch.confirm, shop.radio.buy and menu.resume, keeping names fixed between locale files.

Change English wording without renaming the key; verify the corresponding non-English entry still appears in the correct state.

The timing of a message is as important as its spelling. A translated warning that appears too late, is replaced too quickly or covers a control may lead to a different decision. Test both a first launch and a resumed run. When the problem is presentation, fix the layout or timing at the appropriate layer rather than erasing a crucial condition to make the sentence shorter.

5. Separate natural language from game state

A rescue attempt can depend on fuel, weather, equipment and a mission flag. None should be inferred from the translated wording of an on-screen label.

Keep numeric amounts and event conditions in typed data and variables. Display translations only at the presentation boundary.

Rename the radio upgrade in Spanish and confirm purchase conditions, item ownership and mission access stay identical.

Think of the source text, target text, visible widget and consequential player action as four parts of one contract. A failure in any one of them can mislead. Keep the test small enough to repeat: set the scene, choose the locale, trigger the text, observe it and make the decision. This gives a precise repair task rather than a vague request to improve translations.

6. Define locale precedence before coding

A browser may prefer Canadian French, then English, while the game ships only fr and en. An exact-match-only selection could choose a surprising language.

Specify user choice, saved preference, exact regional match, general language fallback and default locale in an explicit order.

Test en-US, en-GB, fr-CA, fr-FR and an unsupported locale, including a deliberately reordered browser preference list.

The useful check for define locale precedence before coding is to watch a real player rather than merely look at a clean source file. In the harbour game the same screen may contain a warning, an available action and a cost. Record what the player believes will happen before pressing anything. If the next state surprises them, examine the text and the game rule together. A beautifully translated word in an unusable interaction is not a finished product.

7. Never trap users in the wrong language

Automatic system-language detection is useful for a first guess but cannot know which language a visitor wants to read in a shared home or classroom.

Provide a discoverable selector even on the title screen and avoid labels that can be understood only in the incorrectly chosen language.

Start the game with an unsupported browser locale and find the selector without help from an English-speaking tester.

8. Persist preference separately from progress

A player can resume at the harbour after a browser refresh, while the language mysteriously reverts if the setting was only a scene variable.

Store selected locale deliberately and keep it independent from rescue progress. Document exactly when initialization may override saved preference.

Change language, save, refresh and enter another scene while checking both the words and the inventory state.

9. Understand scene versus global scope

A scene variable belongs to a scene context while a global variable can be shared. Copying a language-update event may silently reset the locale during a transition.

Keep the authoritative language code in one declared scope and pass only the state that genuinely belongs to individual scenes.

Move from harbour to shop to debrief and back, then check consistent labels without relying on an editor restart.

10. Account for asynchronous initialization

A text object can be drawn before the dictionary becomes available, causing raw keys, empty text or mixed-language menus to flash.

Use an initialization state and show a readable loading screen or default-safe UI until required resources have been resolved.

Throttle network conditions and inspect the first rendered frame of a fresh exported build.

11. Refresh every active text object

A settings choice that updates its own button but not a shop label or pause instruction gives a misleading impression of a successful language switch.

Keep all translatable text connected to one selected language and refresh on a controlled event or explicit lookup flow.

Switch language with the shop open, then visit every scene without restarting and inspect long and short labels.

The useful check for refresh every active text object is to watch a real player rather than merely look at a clean source file. In the harbour game the same screen may contain a warning, an available action and a cost. Record what the player believes will happen before pressing anything. If the next state surprises them, examine the text and the game rule together. A beautifully translated word in an unusable interaction is not a finished product.

12. Preserve named substitutions

A message such as You have three ropes combines a quantity with a sentence. A careless literal replacement can leave the count hardcoded or misordered.

Define supported placeholders and protected syntax, then provide full-sentence variants where target grammar demands different arrangements.

Test zero, one, two and the maximum equipment count, including character names containing punctuation.

13. Design plural grammar intentionally

English singular and plural logic is not a universal linguistic model. Some languages need multiple forms or contexts.

A simple JSON map is storage, not automatically a locale-aware pluralization engine. Choose rules suited to each supported language.

Ask a fluent reviewer to check counts 0, 1, 2, 5 and 21 where relevant, without relying on English intuition.

14. Stop building phrases from English fragments

Joining the English strings You have and equipment assumes every target language can use the same order and inflection.

Prefer whole messages with named variables or explicitly designed phrase templates rather than runtime concatenation of unrelated fragments.

Compare the shop receipt, warning and inventory label across all count values and check whether they read like native sentences.

15. Treat safety warnings as decisions

The difference between storm watch, unsafe launch and absolute prohibition changes what a player understands they may do in a rescue game.

Give translators a screenshot and the actual consequences. Preserve urgency, conditions, uncertainty and the option to cancel.

Ask a new player whether launch is permitted before they press the button, then compare that prediction with the game rule.

16. Treat translated prices as presentation

The shop can display a formatted price but must still calculate purchases using a numeric amount, not a translated currency-shaped string.

Keep balance, tax or discount rules in data and format the display for the intended audience without silently changing value.

Purchase the radio upgrade in each language and compare starting balance, deduction and resulting inventory.

The useful check for treat translated prices as presentation is to watch a real player rather than merely look at a clean source file. In the harbour game the same screen may contain a warning, an available action and a cost. Record what the player believes will happen before pressing anything. If the next state surprises them, examine the text and the game rule together. A beautifully translated word in an unusable interaction is not a finished product.

17. Check font glyph repertoire early

A readable English font can lack accented vowels, combining marks or non-Latin characters needed for an intended locale.

Build a corpus containing full real messages, names, punctuation and numerals; select a font licensed and tested for those glyphs.

Open the actual web and desktop packages and check that no words contain boxes, gaps or broken accents.

18. Test text-object measurement not guesses

An English button of six characters may become a twenty-character translation. Fixed dimensions can cover an adjacent touch control.

Test bounding boxes, line wrapping and responsive placement at actual target sizes, allowing complete meaning instead of arbitrary clipping.

Run a small phone viewport, a wide browser window and a high-DPI display with the longest label.

19. Handle right-to-left scripts as a system

Simply reversing letters is not the same as shaping and laying out bidirectional text correctly; icon alignment and button order also matter.

Review engine rendering, mixed-direction numbers, input labels and appropriate mirroring for the actual language and target platform.

Use a complete realistic sentence with a radio call sign and numeral, reviewed by a fluent speaker on a shipped build.

20. Localize embedded text in art

A warning painted on a poster or texture will not be changed by updating a text object or JSON dictionary.

List visual assets with embedded words, decide where to replace art or overlay translatable objects, and maintain an asset edition list.

Compare screenshots of every scene in the target edition and identify every source-language image.

21. Localize audio and captions together

A mission radio can speak a warning while the onscreen caption changes. Contradictory cues make the player’s decision harder.

Inventory spoken dialogue, timed subtitles, sound-only instructions and accessibility alternatives as separate assets tied to the same scenario.

Play the mission muted and unmuted; confirm the instructions, timing and consequences agree.

The useful check for localize audio and captions together is to watch a real player rather than merely look at a clean source file. In the harbour game the same screen may contain a warning, an available action and a cost. Record what the player believes will happen before pressing anything. If the next state surprises them, examine the text and the game rule together. A beautifully translated word in an unusable interaction is not a finished product.

22. Capture translators’ working context

The word Launch could refer to the boat, game startup or an uploaded application. Dictionary-only translation requests invite avoidable errors.

Attach screenshot, speaker, action, technical placeholders, register and maximum screen space to the translation request.

Ask a new reviewer to explain the game action associated with a randomly selected message key.

23. Distinguish missing text from a safe fallback

A missing locale entry may render a raw key, empty region or default-language sentence depending on code. Neither outcome should be accidental.

Specify fallback behavior and log omissions; critical warnings should block release if they lack complete approved wording.

Delete one harmless test key in staging and observe the documented fallback without damaging the public game.

24. Control resource revisions

A game update might add a new rescue objective while its Spanish dictionary still belongs to the previous release.

Record source and catalog revision together, report added and removed keys, and keep approval tied to the intended game state.

Introduce a new source message and confirm the release gate detects its missing translation.

25. Review error and recovery paths

Network or storage failures might display English-only exceptions because ordinary play does not trigger them.

Write localizable errors that tell players what happened, whether work is saved and which safe action they can take.

Simulate unavailable resources, storage rejection and restart, without pretending the game has saved when it has not.

26. Test all planned publishing formats

The development preview can resolve assets from an editor environment that an exported package does not contain.

Build the actual web or desktop version and verify resource paths, extensions, fonts, controls and initialization after clean installation.

Open a fresh browser profile, then retry with slow loading and offline conditions appropriate to the product.

The useful check for test all planned publishing formats is to watch a real player rather than merely look at a clean source file. In the harbour game the same screen may contain a warning, an available action and a cost. Record what the player believes will happen before pressing anything. If the next state surprises them, examine the text and the game rule together. A beautifully translated word in an unusable interaction is not a finished product.

27. Make touch controls readable

A localized pause label may collide with directional buttons, and a tooltip may be impossible to reach with touch input.

Review input affordances alongside translated text, especially at minimum viewport width and different device orientations.

Complete the rescue route using only the supported target input method, without developer keyboard shortcuts.

28. Keep accessibility cues independent

A red siren image and radio noise alone cannot tell every player that the boat is unsafe to launch.

Pair visual or audio signals with meaningful text or accessible symbols, and ensure translated warnings remain readable under contrast changes.

Mute audio and remove color cues in a test session; the important next action should remain understandable.

29. Define translator permissions and review

A volunteer should not need permission to modify game event conditions, server settings or unrelated project assets simply to translate a catalog.

Exchange limited source entries and reference screenshots, then review approved strings before integration into a locked project revision.

A new language edition can be built without a translator altering mission switches or shop prices.

30. Keep reproducible release evidence

When a player reports a clipped warning, an editor preview is insufficient to prove what the shipped game showed.

Archive the source revision, dictionary revisions, exported package, reproduction steps, screenshots and a tested rollback candidate.

A second tester can identify the precise build and recreate the same warning without needing the author’s machine.

Troubleshooting by visible symptom

A reliable defect report describes what the player saw, where it happened, which language was active, what the player expected and which build produced the result. Beginning with the symptom avoids blaming a translator for an asset problem or a developer for wording that was never linguistically reviewed. These twelve cases illustrate how to isolate, repair and prove a real issue.

1. Raw dictionary keys appear

Likely cause: An event requests a label before the locale data loads, or the resource key is misspelled.

Repair: Inspect the initialization gate and key inventory, then rebuild with the intended resource included.

Verification: A clean exported build displays the sentence from its first appearance, never a key.

Try the same test with a clean user state, then again after moving to a second scene. Capture both the visible sentence and the actual result. These two observations help distinguish a missing catalog entry from a cached scene object or a changed mission flag. Do not accept a fix that only improves the development preview.

2. The shop remains English

Likely cause: A text object uses an English literal while neighboring labels use lookups.

Repair: Find the object-setting event, move that label into the selected lookup system and check scene transitions.

Verification: Visit shop, harbour and pause screen after changing language.

A single corrected sentence is not enough when the user journey depends on it. Repeat the surrounding action before and after the repair; inspect the resource file, event scope and target-language presentation in that order. Record whether the failure also occurs in the source-language version.

3. Language resets on scene change

Likely cause: Selection is held only in a local scene variable or a startup event overwrites global state.

Repair: Define one authoritative preference and reset only according to the documented precedence rule.

Verification: Refresh the browser and move among scenes while checking the same selection.

Use a real target-language reviewer for the final acceptance. Ask what action the sentence permits, how certain it is and what risk it describes. A technically correct event can still deliver the wrong practical instruction. Keep the corrected scenario as a regression test for later updates.

4. A warning overlays Cancel

Likely cause: Long translated text exceeds its assigned region and visually covers a consequential control.

Repair: Adjust layout first, then edit wording with a fluent reviewer while preserving the full safety instruction.

Verification: Use the smallest supported screen and tap both controls.

If the fault appears only after export, freeze and inspect the deployed package rather than the editor project. Asset paths and extension expectations matter. A good defect record includes the actual URL or package, selected locale, expected resource and the earliest state where the two editions differ.

5. Accents render as boxes

Likely cause: The installed font lacks required glyphs or an export omitted the chosen font asset.

Repair: Verify actual character coverage and file packaging for the text objects that draw the message.

Verification: Open the final export and inspect complete names and warnings.

6. The radio costs different amounts

Likely cause: A condition reads formatted display text instead of the numeric purchase value.

Repair: Separate UI labels from amounts and keep numeric calculations and item IDs stable.

Verification: Compare inventory and balance before and after a purchase in every language.

7. Plural wording sounds broken

Likely cause: The project uses English one-versus-many grammar for a language with different categories.

Repair: Review the target grammar and implement tested message variants or compatible formatting.

Verification: Check zero, one, two, five and larger counts in full sentences.

8. A mission choice has swapped meaning

Likely cause: The translation labels for two actions were reversed, while the event branches remained unchanged.

Repair: Trace each displayed label to its original consequence and correct the wording rather than rewire game logic.

Verification: Ask new players to predict outcomes, then execute both choices.

9. A source-language poster survives

Likely cause: Words were painted inside an image that the resource inventory did not cover.

Repair: Include text-bearing visual assets in the translation plan or redesign as translatable text objects.

Verification: Inspect every harbour and shop art asset in the released edition.

10. Captions contradict radio audio

Likely cause: The text was changed without updating recorded sound or timed cue assets.

Repair: Review caption, audio and timing as one consequential communication.

Verification: Play muted and unmuted, checking the player’s interpretation of the warning.

11. Browser export is missing locale JSON

Likely cause: A resource path relied on the editor or an extension was not configured for the release build.

Repair: Inspect exported files and runtime errors, then retest the exact documented loading approach.

Verification: Open the deployed game in a fresh browser profile.

12. Old save loads the wrong language

Likely cause: The stored language code or catalog version is incompatible with the newly published package.

Repair: Define compatible fallback and migration rules without changing mission progress.

Verification: Load a previous-version save and inspect both locale and game state.

Three worked publication journeys

One independent creator

A solo developer chooses French as the first additional language and makes a complete pilot route rather than translating every piece of harbour scenery. They identify twelve labels and six pieces of dialogue tied to the launch, radio purchase and rescue decision. The early task is to select a consistent dictionary workflow, verify the JSON resource and draw the full phrases using the intended font. They should resist accepting a successful first-screen preview as proof of completion. The trial ends with a separate browser session, a complete target-language playthrough and a short list of confirmed defects and decisions.

The acceptance criterion is practical: an unfamiliar person can select their intended language, understand the weather warning, buy the right equipment and complete or refuse the rescue without seeking an English explanation. This can be observed and documented. Merely counting translated entries cannot prove the player’s comprehension or the actual integrity of the finished package.

A translator, developer and reviewer

The developer supplies stable keys, contextual screenshots and protected placeholders. The translator receives enough information to distinguish a mission launch from an application launch and can query unclear wording before committing a sentence. A fluent reviewer checks language quality and player expectations. The developer integrates approved entries without modifying gameplay data. A tester verifies the actual mission, including counts, purchases, warnings and alternative endings. Where editorial and technical tests disagree, the team reproduces the full action rather than debating abstract terminology.

A publisher with several supported locales

The team freezes a project revision and records which dictionaries and font assets belong to it. Every release build includes a list of target platforms, current extension versions, chosen fallback rules and the minimum screen sizes tested. A language edition is rejected if critical warnings are missing, if a glyph cannot be displayed or if changing language resets progress. The publisher checks the distribution page, controls, screenshots and credits as well as the game. A prior verified package is retained so that a serious localization regression can be reversed quickly.

Four-week implementation and review plan

Week 1: inventory and decisions

Inspect all harbour scenes, conditional alerts, shop paths, credits and image text. Record keys, state triggers, owner and limits. Choose supported target languages based on real font and editorial resources. Decide one localization architecture and clearly identify which parts come from GDevelop, which come from a third-party extension and which are built with events.

A good weekly review leaves evidence another person could use. Name the edition and build, state the triggering action, record what the reader saw and state which outcome was correct. When a test cannot be completed, document the limitation plainly instead of treating the unchecked language as approved.

Week 2: one complete working language path

Translate the title, warning, radio purchase and debrief as one connected route. Test loading, locale precedence, missing-key behavior and the font on the actual smallest planned screen. Have a fluent reviewer explain what each important sentence asks the player to do. Capture all defects with a screenshot and an exact reproduction path.

Week 3: branch and format coverage

Include unsafe launch, insufficient funds, missing equipment, abort, failed mission and restored saves. Expand the test to optional text, image assets, audio and accessibility cues. Try a clean web deployment under slow loading and a second device. Check that game conditions and numeric amounts are identical across editions.

Week 4: frozen release and rollback

Freeze the source revision, approved dictionaries and font assets. Export the intended packages, then reopen them independently of the editor. Check language choice, mission route, debrief, controls, permissions, credits and public instructions. Retain the last successful build, the known limitations and a compact report of tests passed or still blocked.

Frequently asked questions

Is multilingual support automatic in GDevelop?

Not as a universal claim. Choose a documented event system or an appropriate extension, then review actual translations and builds.

The practical answer depends on the installed version, selected extension and game’s tested design. Verify it in a clean exported package, including the full player action. If the source text, display and consequence cannot be checked together, the translation has not yet been validated.

Can I use external JSON dictionaries?

A suitable resource workflow can load JSON. The documented JSON Resource Loading extension is experimental, so check the specific installed version.

Should the browser choose the language?

Use it only as a first preference under an explicit hierarchy. A person must be able to change a wrong guess.

Can players switch languages mid-scene?

Only if your project updates every active text object and handles ongoing state and fallback correctly.

How do I translate dynamic counts?

Preserve numeric values as program data and use grammatical full-sentence formatting suited to each locale.

What about Arabic or Hebrew?

Test actual font coverage, shaping, directionality, mixed numerals and interface order. Never assume manual string reversal is adequate.

Why does it work in preview but fail online?

The exported package may have missing resources, paths or different extension behavior. Check the exact build under clean conditions.

What is the minimum release standard?

A new player completes a meaningful journey, understands every critical choice and encounters no broken resources in the shipped edition.

Primary technical documentation and further reading

For the larger discipline of preserving meaning, read Master Art of Translation. For other platform-specific guides, visit the Translate Like a Pro series index. This article focuses on actual GDevelop localization implementation and player testing rather than generic translation speed or unrelated industry documents.

Final principle: the player can act on the meaning

In a translated rescue game, a reader should not need an English-speaking friend to identify a safety warning, understand an equipment cost or know which choice ends a mission. The words, event variables, font assets and exported package need to agree. A successful international release makes the player’s understanding observable and repeatable. That is a more demanding standard than translated word count, and it produces a more useful game.

Translate Like a Pro | 7110 — GDevelop JSON Localization, Event Variables, Text Objects, Fonts and Release QA