Candy Logo Copyright © 2025-2026 Candy Arts
Translating Speech
Spoken Lines are translated through language Variations. Each translation of a line is a Variation of that line, written in the line itself, next to the original text. Variations in general are explained on the Variations page. Language Variations The first part of a Variation's name is its language. The original language of your Dialogues is always named Default, whatever language it actually is. Each translation is named after its language, such as French or Japanese. A line written in English and translated into French and Japanese has three Variations:
Default Welcome to the village! French Bienvenue au village ! Japanese 村へようこそ！
Language names are free, as long as the same name is written everywhere: in Variation names, in the localization tables and in the language settings. Language names are case-sensitive. Don't use underscores (_) or spaces in a language name. The Current Language Each Engine displays its Dialogues in one language. That language is decided in this order: 1. The Engine's engine_language, when it isn't empty. It is set in the Inspector, or modified during a Dialogue by the Engine_Language command. 2. Otherwise, language in Candy_Properties.gd, which applies to every Engine. 3. If both are empty, Default. In most games, language is the only setting needed. So that players can change it from your options menu, set candy_de.language in your game code:
candy_de.language = "French"
The Engine reads the language each time it starts a Dialogue, so a change made while a Dialogue is running applies from the next Dialogue. To apply it immediately, call the Engine's refresh_language() function after changing the language:
candy_de.language = "French" $DialogueUI/CandyEngine.refresh_language()
The Engine's next Spoken Line is then displayed in the new language, and its open choice menus and Input scenes display their texts in it (see Translating UI Texts). Call refresh_language() on each Engine that is running a Dialogue. The Engine_Language command applies its change immediately, in the same way. Candy Dialogue Engine doesn't save candy_de.language. To preserve the player's choice between game sessions, save it with your game's settings, and set candy_de.language again when the game starts. engine_language is useful when one Engine must retain its own language, such as an Engine for a foreign character whose lines are always displayed untranslated. What the Language Affects The current language decides:
  • Which Variation of each Spoken Line is displayed.
  • Which voice file each line plays (see Voice Files below).
  • Which Word Substitution rules and Lexicon keywords apply, when their tables have entries for specific Variations (see Word Substitution and Lexicon).
  • How choice menus and Input scenes are translated (see Translating UI Texts).
  • The language Actor names are displayed in (see Translating Names).
Translating Tagged Variations Tags work the same way in every language. Each language only chooses among its own Variations, so every tagged Variation needs a translation with the same tags.
Default Welcome, traveler! Default_P=F Welcome, miss! French Bienvenue, voyageur ! French_P=F Bienvenue, mademoiselle !
If French_P=F were missing, a female player character playing in French would be greeted with "Bienvenue, voyageur !". The Default Variations are never displayed in French. The same applies to numbered alternatives. The French Variation can have its own alternatives (French_#1, French_#2...), whether or not Default has any. Lines in Some Languages Only A line that has no Variation in the current language is skipped. It doesn't fall back to the Default text. Each language can therefore use a different number of lines. A translation is often longer than the original, and may not fit in the dialogue box. The translation can then be split over two lines: the first line has a Default Variation and a French Variation, and the second line has only a French Variation. In Default, the second line is skipped. The same rule means that a missing translation removes the line from the Dialogue, without an error. Check that every Spoken Line has a Variation in each language your game supports, unless it is meant to be skipped. If your Dialogues use Media_Pause with a Lines count, set the Engine's mp_count_variations to true. Skipped lines then count toward Lines, so paused media resumes at the same point in every language. Writing Direction For languages written from right to left, such as Arabic or Hebrew, set the Variation's Direction to RtL (see Spoken Line). Each Variation has its own Direction, so a line's French and Arabic Variations can be written in different directions. Voice Files A voiced line needs a voice file for each language. The voice file of every Variation other than Default is stored in a sub-folder named after the Variation, under the same file name:
res://Candy_DE/Media/Actors/Voices/Alice/Intro/Meeting/Start/hello.ogg res://Candy_DE/Media/Actors/Voices/Alice/Intro/Meeting/Start/French/hello.ogg
If a translation's voice file doesn't exist, the line is displayed without voice. To play another language's file instead, such as while recordings in a language are not finished, set voice_fallback_language in Candy_Properties.gd to that language, or to Default for the original. Players can also choose the voice language apart from the text's, with voice_language. See Voice. With text-to-speech in Advanced mode, each language can also have its own TTS Variation, such as French_TTS (see TTS). Translating Text Inside Lines Some parts of a line's text are not written in the Variation itself:
  • Word substitutions are replaced according to the Substitution Table, which can have separate rules for each language. See Word Substitution.
  • Text variables display values from your game, such as an Actor's name or an item name. Actor names are covered in Translating Names, and other values in Translating Other Content.