Translation

Ren'Py contains a comprehensive framework for the translation of visual novels. There are four main types of things that can be translated:

Dialogue

The main dialogue of the script can be translated, including a provision for splitting, combining, omitting, and reordering lines.

Menus and other Strings

All interface text can be translated.

Images and Files

It's possible to include variant images and other files that are used when a language is selected.

Styles

It's possible to customize styles based on the language, so that the game can automatically switch to a font appropriate for the language that was chosen.

Ren'Py's translation support is currently focused on sanctioned translations, where the game's creators either release the game scripts to the translator or create translation templates themselves. Support for unsanctioned translations is more limited.

Primary and Alternate Languages

Ren'Py expects each game to be written in a single primary language. This is called the None language, regardless of what language it actually is. (For example, if the game was written in English, English will be the None language.)

When the None language is selected, most of Ren'Py's translation functionality is disabled.

Alternate languages are referred to by names which can double as python identifiers. (Starts with a letter or underscore, followed by letters, numbers, and underscores.)

Generating Translation Files

When the project scripts are available, translation files can be generated by opening the project in the Ren'Py Launcher, and choosing "Generate Translations". The launcher will prompt you for the name of the language to generate, and will then proceed to create or update the translation files.

The translation files live in directories underneath the "tl" subdirectory of the game directory. For example, if you create a piglatin translation of the tutorial project, translation files will be placed under tutorial/game/tl/piglatin.

There will be one translation file created per game script file. The common.rpy file will also be created to contain translations of strings found in the common code.

Translating Dialogue

As Ren'Py is a visual novel engine, we expect most translation to involve dialogue. Ren'Py includes a flexible framework that allows dialogue to be split, combined, reordered, and omitted entirely.

Translation Units

The fundamental unit of translation is a block of zero or more translatable statements, optionally followed by a single say statement. Translatable statements are the voice and nvl statements. For example take the following game:

label start:
    e "Thank you for taking a look at the Ren'Py translation framework."

    show eileen happy

    e "We aim to provide a comprehensive framework for translating dialogue, strings, images, and styles."

    e "Pretty much everything your game needs!"

This is broken up into multiple translation units. Each unit has an identifier assigned to it, with the identifier being generated from the label preceding the unit, and the code inside the unit. (If multiple units would be assigned the same translation number, a serial number to the second and later units to distinguish them.)

In the example above, the first unit generated is assigned the identifier start_636ae3f5, and contains the statement:

e "Thank you for taking a look at the Ren'Py translation framework."

The second unit is given the identifier start_bd1ad9e1m and contains:

e "We aim to provide a comprehensive framework for translating dialogue, strings, images, and styles."

The third unit has the identifier start_9e949aac, and contains:

e "Pretty much everything your game needs!"

These units are created automatically by Ren'Py when the game script is loaded.

Translate Statement

When you generate translations for a language, Ren'Py will generate a translate statement corresponding to each translation unit. When translating the code above, Ren'Py will generate:

# game/script.rpy:95
translate piglatin start_636ae3f5:

    e "Thank you for taking a look at the Ren'Py translation framework."

# game/script.rpy:99
translate piglatin start_bd1ad9e1:

    e "We aim to provide a comprehensive framework for translating dialogue, strings, images, and styles."

# game/script.rpy:101
translate piglatin start_9e949aac:

    e "Pretty much everything your game needs!"

This can be translated by editing the generated code. A finished translation might look like:

# game/script.rpy:95
translate piglatin start_636ae3f5:
    # e "Thank you for taking a look at the Ren'Py translation framework."
    e "Ankthay ouyay orfay akingtay away ooklay atway ethay En'Pyray anslationtray ameworkfray."

# game/script.rpy:99
translate piglatin start_bd1ad9e1:

    # e "We aim to provide a comprehensive framework for translating dialogue, strings, images, and styles."
    e "Eway aimway otay ovidepray away omprehensivecay ameworkfray orfay anslatingtray ialogueday, ingsstray, imagesway, andway ylesstay."

# game/script.rpy:101
translate piglatin start_9e949aac:

    # e "Pretty much everything your game needs!"
    e "Ettypray uchmay everythingway ouryay amegay eedsnay!"

When a block in the main script is encountered, Ren'Py checks to see if a translate statement corresponding to that block exists. If so, it executes the translate statement instead of the translated block, showing the user the translation.

More Complex Translations

Translate statements do not need to contain 1-to-1 translations of the original language. For example, a long line could be split:

# game/script.rpy:99
translate piglatin start_bd1ad9e1:
    # e "We aim to provide a comprehensive framework for translating dialogue, strings, images, and styles."
    e "Eway aimway otay ovidepray away omprehensivecay ameworkfray..."
    e "...orfay anslatingtray ialogueday, ingsstray, imagesway, andway ylesstay."

Or a statement can be removed, by replacing it with the pass statement:

# game/script.rpy:101
translate piglatin start_9e949aac:

     # e "Pretty much everything your game needs!"
     pass

It's also possible to run non-dialogue statements, such as conditionals or python code. For example, we can translate:

e "You scored [points] points!"

into:

# game/script.rpy:103
translate piglatin start_36562aba:

    # e "You scored [points] points!"
    e $ latin_points = to_roman_numerals(points)
    e "Ouyay oredscay [latin_points] ointspay!"

Tips

Be very careful when changing dialogue that has been translated, especially when that dialogue is repeated in more than one place inside a label. In some cases, it may be necessary to assign a translation identifier directly, using a statement like:

translate None mylable_03ac197e_1:
    "..."

Adding labels can also confuse the translation process. To prevent this, labels that are given the hide clause are ignored by the translation code.:

label ignored_by_translation hide:
    "..."

While translation blocks may include python code, this code should not have side effects visible outside of the block. That's because changing languages will restart the translation block, causing the side effects to occur multiple times.

Menu and String Translations

In addition to dialogue, Ren'Py is able to translate text found in menus and other strings. Interface translations are a 1-to-1 substitution. Wherever a string is found, it will be replaced by a single replacement.

When generating translations, Ren'Py will scan the script files for menus, and for strings enclosed inside the _() function. It will then place the strings inside a translate strings block. For example, if we have the following script:

define e = Character(_("Eileen"))

# ...

menu:

     "Go West":
        # ...

     "Head East":
        # ...

Ren'Py will generate the following code:

translate piglatin strings:

    old "Eileen"
    new "Eileen"

    old "Go West"
    new "Go West"

    old "Head East"
    new "Head East"

Which can then be translated:

translate piglatin strings:

    old "Eileen"
    new "Eileenway"

    old "Go West"
    new "Ogay Estway"

    old "Head East"
    new "Eadhay Eastway"

String translations are also applied to dialogue strings that are not translated as dialogue.

When the same string is used in multiple places in the code, the string can be distinguished using the {#...} text tag. Even though they display the same, Ren'Py considers all of these distinct strings for the purpose of translation:

"New"
"New{#project}"
"New{#game}"
"New{#playlist}"

Translating substitutions

String substitutions can be translated using the !t conversion flag. So the following code will be translatable using the dialogue and code translation systems:

if mood_points > 5:
    $ mood = _("great")
else:
    $ mood = _("awful")

"I'm feeling [mood!t]."

Image and File Translations

When translating a game, it may may be necessary to replace a file with a translate version. For example, if an image contains text, it might make sense to replace it with a version of the image where the text is in another language.

Ren'Py handles this by looking in the translation directory for the image. For example, if the "piglatin" language is in use, and "library.png" is loaded, Ren'Py will use "game/tl/piglatin/library.png" in preference to "game/library.png".

Style Translations

It may be necessary to change styles - especially font-related styles - when translating a game. Ren'Py handles this with translate python blocks. These blocks can contain code to change language-related styles:

translate piglatin python:
     style.default.font = "stonecutter.ttf"

When a language is activated - either at the start of the game, or after a language change - Ren'Py resets the styles to their contents at the end of the init phase. It then runs all translate python blocks associated with the current language, in some order. Finally, it rebuilds styles, allowing the changes to take effect.

Style translations may be added to any .rpy file.

Default Language

The default language is chosen using the following method:

• If the RENPY_LANGUAGE environment variable is set, that language is used.
• If config.language is set, that language is used.
• If the game has ever chosen a language in the past, that language is used.
• Otherwise, the None language is used.

Translation Actions, Functions, and Variables

The main way to switch languages is with the Language action.

Language(language)

Changes the language of the game to language.

language

A string giving the language to translate to, or None to use the default language of the game script.

The Language action can be used to add a language preference to the preferences screen, using code like:

frame:
    style_group "pref"
    has vbox

    label _("Language")
    textbutton _("English") action Language(None)
    textbutton _("Pig Latin") action Language("piglatin")

There are two translation-related functions:

renpy.change_language(language)

Changes the current language to language, which can be a string or None to use the default language.

renpy.known_languages()

Returns the set of known languages. This does not include the default language, None.

There are two language-relate variables. One is config.language, which is used to change the default language of the game.

_preferences.language

The name of the current language, or None if the default language is being used. This should be treated as a read-only variable. To change the language, call renpy.change_language().

Unsanctioned Translations

Note

It's best to ask a game's creators for permission before creating an unsanctioned translation.

Ren'Py includes a small amount of support for creating translations without the active assistance of the game's creators. This support consists of the ability to automatically create a string translation file from all of the strings in the game. Since string translations are used for untranslated dialogue, this technique makes it possible to translate a game.

To create a string translation file, perform the following steps:

• Set the RENPY_LANGUAGE environment variable to the language you want to translate to.
• Set the RENPY_UPDATE_STRINGS environment variable to a non-empty value.
• Play through the game until all text is seen.

This will update the "game/tl/language/strings.rpy" file with a translation template that contains all of the strings in it.

If a game doesn't include support for changing the language, it may be appropriate to use an init python block to set config.language to the target language.

Along with the use of string translations for dialogue, unsanctioned translators may be interested in using the techniques described above to translate images and styles.