Solarus quests  1.1
Quest maker's reference
Translated dialogs

Dialogs are all messages shown to the player in the dialog box during the game. Some dialogs are triggered by the engine and others by your quest. They are all defined in the file languages/xx/text/dialogs.dat, where xx is a language code defined in project_db.dat (e.g. "en" or "fr").

When translating the game, you have to translate this dialogs.dat file as well as the strings file (strings.dat). Have a look at the How to translate a quest page if you are interested in translating a Solarus game.

dialogs.dat is a text file encoded in UTF-8. We specify here its full syntax, with instructions for quest makers and translators.

The sequence of characters -- (two dashes) marks the beginning of a comment. After them, the rest of the line is ignored by the engine. Empty lines are also ignored. Quest makers should put many comments to explain where each dialog is used and give instructions to translators if needed.

The definition of a dialog starts with dialog{ and ends with }. Inside the braces, the properties of the dialog are specified. Properties are declared with the syntax key = value and separated with commas. It is allowed to have an extra comma after the last property. String values should be enclosed within double quotes, except when specified otherwise. Each dialog must have at least the following two properties:

  • id (string): A name identifying the dialog. The id allows the engine and your Lua scripts to refer to the dialog whenever they want to display it. If you are translating dialogs, you must never translate the id.
  • text (multi-line string): Contents of this dialog. If you are translating dialogs, text is the property to translate. The text has usually several lines. The text should be enclosed between [[ and ]], which is the notation for multiline strings.

Only id and text are mandatory (because the default minimal built-in dialog box use them), but you can add any other property depending on your dialog box implementation. Properties of a dialog are always of type string (numbers and booleans are also accepted, but they will be converted to strings).

The dialog box system is entirely customizable, so you it is up to you to put the properties that fit your needs. For example, you can make properties that define:

  • the speed of the dialog (assuming that your dialog box displays the letters gradually),
  • whether the dialog stops automatically or manually,
  • whether it can be skipped by the player,
  • whether it contains special features like a question or an icon,
  • etc.

When a dialog starts at runtime, your dialog box script receives these properties through the game:on_dialog_started() event and is responsible to handle them.

Here is a small example of dialog file. Again, remember that only id and text are mandatory: other properties are specific to a particular implementation of dialog box.

dialog{
  id = "wise_man",
  skip = "current",
  question = true,
  next = "wise_man.thanks",
  next2 = "wise_man.insisting",
  text = [[
I can feel courage in
you.
Do you think you can
protect the Princess?
Definitely!
No way
  ]],
}

dialog{
  id = "wise_man.insisting",
  question = true,
  next = "wise_man.thanks",
  next2 = "wise_man.insisting",
  text = [[
I beg you.
You are the only one
one able to protect
our kingdom...
Sure
No way
  ]],
}

dialog{
  id = "wise_man.thanks",
  text = [[
I knew I could count on
your immense bravery.
  ]],
}
Remarks
This syntax of the dialog file is actually valid Lua. The engine internally uses Lua to parse it.