Translating Names
Actor names are translated through the display_names localization table, each time they are displayed.
The actors dictionary always contains names in the Default language. When a name is displayed, the Engine looks it up in display_names and displays its translation for the Engine's current language. If the player changes the language, every name is displayed in the new language from then on, including names changed during the game. Lines already displayed, such as those retained in the Chat or in the Dialogue History, retain the name they were displayed with.
Where Names Are Displayed
- The speaker's DisplayName is displayed in the speaker label of the Dialogue Box, Subtitles and Chat, on VN name tags, and in the Dialogue History.
- Text variables that name an Actor, such as ¤Alice¤ or ¤°guard¤, display the Actor's ShortName, or their DisplayName when ShortName is empty (see Displaying Variables).
Both are translated through display_names. When an Actor has neither name, their Actor Reference is displayed, and translated in the same way. See Actor Properties.
Each name is translated when its Spoken Line runs: the speaker's name once for the whole line, and each text variable while the line's text is prepared. The VN name tag is translated when the speaker's bust is highlighted.
Other Actor properties displayed with text variables, such as ¤Alice.Title¤, are displayed as they are, without translation.
Reading Names Directly
Only the places listed above translate names. Reading a name property yourself returns the value stored in the actors dictionary, which is always the Default name. This applies to:
- Text variables that read the property, such as ¤Alice.DisplayName¤ or ¤°guard.ShortName¤.
- ¢ expressions, such as
¢candy_de.actors["Alice"]["DisplayName"] or ¢°guard.DisplayName. - Your game code, such as
candy_de.actors["Alice"]["DisplayName"].
When such a value is displayed to the player, translate it with the translation functions, so that it is displayed in the current language.
In a text variable, write the Actor Reference alone where possible: ¤Alice¤ is translated, ¤Alice.DisplayName¤ isn't. To display the DisplayName when the Actor also has a ShortName, call display_name() in an expression:
¤¢CandyActors.get_shared().display_name(self, self, "Alice")¤
In an expression, self is the Engine running the Dialogue, so it is passed as both the Engine and the caller.
When the name is already a value, translate it through display_names with translate() (see Translating Other Content):
¤¢CandyWriting.get_shared().translate(self, self, °guard.DisplayName, "display_names")¤
translate() doesn't fall back to the Actor Reference when the name is empty. display_name() and text_name() do.
In your game code, call the functions described in Displaying Names in Your Game below.
The display_names Table
The display_names table is in Display_Names.gd, in the User_Data/Localization_Tables folder. It's a 'safe' file: updates never overwrite it. Each key is a name in the Default language, and contains its translation in each language:
var display_names = {
"Old Man": {
"French": "Vieil homme",
"Japanese": "老人",
},
"Elder Ryn": {
"French": "Doyen Ryn",
"Japanese": "リン長老",
},
"Ryn": {
"Japanese": "リン",
},
}
The key must match the name exactly, including capitals and spaces. A name without an entry for the current language is displayed as written. In this example, "Ryn" is displayed as written in French, because the French name is identical.
DisplayName and ShortName values share the same table. Add an entry for each value that needs translating.
Language names must be spelled exactly as in your Variation names (see Translating Speech).
Changing a Name
Names are changed by the Name command, or by your game code. Either way, write the new name in the Default language.
For example, a stranger is introduced as "Old Man", then reveals that they are "Elder Ryn". In the actors dictionary, Ryn's DisplayName is "Old Man", and the Dialogue later changes it with a Name command:
| Key | Value |
| Reference | Ryn |
| Name | Elder Ryn |
candy_de.actors["Ryn"]["DisplayName"] = "Elder Ryn"
Displaying Names in Your Game
To display an Actor's name elsewhere in your game, such as in a quest log or on a character sheet, call the same functions as the Engine:
var actors := CandyActors.get_shared()
name_label.text = actors.display_name(engine, self, "Ryn")
nickname_label.text = actors.text_name(engine, self, "Ryn")
| Function | Returns |
| display_name() | The Actor's DisplayName, or their Actor Reference when it is empty, translated. |
| text_name() | The Actor's ShortName, else their DisplayName, else their Actor Reference, translated. |
self) and the Actor Reference.
Like translate(), these functions require the Engine to know its language: before the Engine's first Dialogue, call its refresh_language() first (see Translating Other Content).
Keys as Identifiers
A name can be an identifier rather than the Default name itself, with an entry of its own for the Default language:
"NAME_ELDER": {
"Default": "Elder Ryn",
"French": "Doyen Ryn",
},
The Name command then sets the name to NAME_ELDER, which is displayed as "Elder Ryn" in Default. The Default name can then be changed later without editing your Dialogues. An identifier without an entry for the current language is displayed as written, so write an entry for every language you support.
Copyright © 2025-2026 Candy Arts