Implementing Translations in Ren'Py [Updated Tutorial]

A place for Ren'Py tutorials and reusable Ren'Py code.
Forum rules
Do not post questions here!

This forum is for example code you want to show other people. Ren'Py questions should be asked in the Ren'Py Questions and Announcements forum.
Message
Author
User avatar
Morhighan
Miko-Class Veteran
Posts: 975
Joined: Sun Jun 27, 2010 12:54 pm
Completed: AIdol, When Our Journey Ends, Forgotten Not Lost
Organization: MysteryCorgi
Tumblr: MysteryCorgi
Deviantart: MysteryCorgi
Soundcloud: MysteryCorgi
itch: MysteryCorgi
Location: USA
Contact:

Implementing Translations in Ren'Py [Updated Tutorial]

#1 Post by Morhighan »

Image
Tutorial on Itch.io
Note: As of May 29,2019 I will focus any future updates on the itch.io page rather than this post.
Introduction
In this tutorial I'll be discussing how to add a language option to your Ren'Py game. This is solely for the implementation of a translation, NOT to generate a translation from the script. There is no automated translation button built into Ren'Py, and I highly recommend against using machine translation for official game releases, as the practice is highly frowned upon in.
When working for Afterthought Studios, I worked with a team of translators to make the Russian translations of Afterthoughi's games. I then implemented the translations into the scripts. However, the process can be confusing when you only do it once every six-to-twelve months or so. Thus I made a guide for myself some time back to avoid confusion. I've decided to share and update the tutorial for anyone who might find it useful.

Step One

To get a basic understanding of the translation framework built into Ren'Py, I recommend reading this Documentation page.

Once you have your game's script completed in the original language (I'll be using English in the example), you will want to generate a blank script for translation into another language (Russian, in this example.) To do this, you will select the project in The Ren'py Launcher and go to the Actions menu, where you will click "Generate Translations."

Image

This will take you to a second menu, in which you will input the name of the language you are generating scripts for. Be sure to use all lowercase letters.


Image

Now press "Generate Translation," making sure to have the box next to 'generate empty strings for translations' checked.

Image

Ren'Py will generate blank files for your project, which can take a few moments depending on how large your project is. Once it's done you'll find the blank scripts for translation in your project's "game" folder, like so:

Code: Select all

[Your Game]/game/tl/russian
Image

Your files will be ready for the translation to be input. This will be done manually. The team we worked with input the translation into the script as they worked, so everything could be matched up and double checked. Some programmers receive translations via spreadsheets, some scripters input the translations themselves. It all depends on what you/your team and the translator's preferences are.

Here's what one of the scripts looks like before the translation is filled in.

Image

You can see that the contents of original script (in this case, the English text) is available in comments. The lines above the comments are what allows Ren'py to replace the English line with the Russian line, when the game is played in Russian. Below the comment is an empty dialogue line with the appropriate character label defined, which will eventually be filled with the translation.

Code: Select all

# game/script.rpy <--file from which the lines are taken
translate language script_#######:  #<--string for replacing original script with translation
# n "Commented version of line from original script."
n "Translated version of line."
Here is what the same script looks like after the translation is implemented:

Image

!! Important !!

Be sure that any strings like the following

Code: Select all

translate russian script1_f978b7f5:
match the capitalization of your game folders. If the folder is "/game/tl/russian" make sure "russian" is always lowercase, or you might get weird issues. At one point I had an error in which only the menus appeared translated, but all of the text was still in English. It was because of a mismatch in capitalization.

Another issue that sometimes crops up has to do with how characters are defined. When Ren'Py converts a script into an empty script to be filled with translations, it will automatically convert some lines that won't be translated in the same manner as the rest of the script.

For example, the script we generated for Forgotten, Not Lost included the character definitions, which our translators naturally translated.

Code: Select all

# game/script.rpy:79
translate russian start_3989d14d:
    #define mad1 = Character("Madalene")
    define mad1 = Character("Мадалена")
But this caused the translated names to override the names in English, no matter which language you played the game in, due to how Ren'Py works. To prevent this, you must do the following:

Code: Select all

define e = Character(_('Eileen'), color="#c8ffc8")
You will find this in the scripts of the Russian translation:

Code: Select all

translate russian strings: 
    old "Eileen" 
    new "Эйлин"
In the end, our Russian Strings looked like this:

Image

and the error was resolved.

Now that the above is done, you should have a functioning translated script. Be sure that your UI is also translated. If you use imagemaps for your GUI, you'll want to have translated versions of any UI images and add them to your translated file folder, like so:

Code: Select all

[Your Game]/game/tl/russian/images
Now, you'll need a way to allow your players to select the language they want to play in. For Afterthought Studio's games, I had the option pop up in a splash screen upon opening the game. If the player has already made their selection, the splash screen won't pop up again.

To do this, I used the following code in options.rpy:

Code: Select all

init -3 python: 
    if persistent.lang is None: 
        persistent.lang = "english"
    lang = persistent.lang
init python: 
    config.main_menu.insert(3, (u'Language', "language_chooser", "True"))
init python:
    if lang == "english":
        style.default.font = "font_name_here_1.ttf" #english font here 
    elif lang == "russian": 
        style.default.font = "font_name_here_2.ttf" #russian font here
Please note that not all fonts will be compatible with a given language, so you may need to change the font depending on the language selection.

If you want players to be able to choose the language upon opening the game, put the following in script.rpy:

Code: Select all

label language_chooser: 
    scene black 
    menu: 
        "{font=Arimo-Regular.ttf}English{/font}": $ renpy.change_language(None) 
        "{font=Arimo-Regular.ttf}Русский{/font}": $ renpy.change_language("russian")
    $ renpy.utter_restart() #alternatively, use "return" if you don't want to go to the main menu.
And in case your players want to switch languages after starting the game, put the following in your imagemap for the Main Menu or Options Menu for screens.rpy:

Code: Select all

hotspot(#,#,#,#) action ShowMenu("language_chooser") #insert coordinates appropriately
This is how I've implemented translations in the past. As Ren'Py updates, I'll try to improve on this tutorial as I am able to. I will focus any updates on the itch.io page rather than this post.

This code is compatible with SteamAPI, so you can use it in conjunction with achievements and such. (ie. having an achievement unlock when players change the language.)

I hope this helps anyone who might need it. If you have any questions, please feel free to leave a comment and I will try to get back to you.

If you found this helpful at all, please consider leaving me a token of your appreciation, if you are able to.
Last edited by Morhighan on Mon Jun 17, 2019 2:44 am, edited 7 times in total.

User avatar
karorogunso
Newbie
Posts: 6
Joined: Mon Nov 24, 2014 10:01 am
Projects: Bluebird
IRC Nick: karorogunso
Github: karorogunso
Location: Thailand
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#2 Post by karorogunso »

Also.. you can use this code with SteamAPI too. :D

User avatar
Morhighan
Miko-Class Veteran
Posts: 975
Joined: Sun Jun 27, 2010 12:54 pm
Completed: AIdol, When Our Journey Ends, Forgotten Not Lost
Organization: MysteryCorgi
Tumblr: MysteryCorgi
Deviantart: MysteryCorgi
Soundcloud: MysteryCorgi
itch: MysteryCorgi
Location: USA
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#3 Post by Morhighan »

karorogunso wrote:Also.. you can use this code with SteamAPI too. :D
Good to know/remember that! :D

User avatar
Ertal77
Veteran
Posts: 322
Joined: Sat Feb 27, 2016 2:33 pm
Completed: A Hand in the Darkness, Chasing the Stars, My Burning Heart, Blood and Lust, Lurkers, Jolly Roger, The Remainder, The Manor, Night and Day
Projects: Deep in the Forest and Exes Assault!!
Organization: Ertal Games
Tumblr: ertalgames
itch: ertal-games
Location: Spain
Discord: Ertal#0394
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#4 Post by Ertal77 »

Morhighan wrote: Put the following in script.rpy:
(You can use this label before the game starts so players can choose the language immediately.)

Code: Select all


label language_chooser:
    scene black
    
    menu:
        "{font=Arimo-Regular.ttf}English{/font}":
            $ renpy.change_language(None)
        "{font=Arimo-Regular.ttf}Русский{/font}":
            $ renpy.change_language("russian")

    $ renpy.utter_restart()

Thank you so much for this tutorial, it's very clear and useful!
Just a question, though: how do I change the "$ renpy.utter_restart()" part so it goes to my "label start" directly and skips the splashscreen?

*EDIT Nevermind, I changed it for "return" and now it leads me directly back to the game instead of the main menu, but I guess that works fine, too.
Do you like BL games? Then join Ertal Games' Discord!

User avatar
karorogunso
Newbie
Posts: 6
Joined: Mon Nov 24, 2014 10:01 am
Projects: Bluebird
IRC Nick: karorogunso
Github: karorogunso
Location: Thailand
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#5 Post by karorogunso »

Ertal77 wrote:
Morhighan wrote: Put the following in script.rpy:
(You can use this label before the game starts so players can choose the language immediately.)

Code: Select all


label language_chooser:
    scene black
    
    menu:
        "{font=Arimo-Regular.ttf}English{/font}":
            $ renpy.change_language(None)
        "{font=Arimo-Regular.ttf}Русский{/font}":
            $ renpy.change_language("russian")

    $ renpy.utter_restart()

Thank you so much for this tutorial, it's very clear and useful!
Just a question, though: how do I change the "$ renpy.utter_restart()" part so it goes to my "label start" directly and skips the splashscreen?

*EDIT Nevermind, I changed it for "return" and now it leads me directly back to the game instead of the main menu, but I guess that works fine, too.
Yes return is fine too.
Hi.

Kinross07
Newbie
Posts: 7
Joined: Mon May 29, 2017 3:29 am
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#6 Post by Kinross07 »

Unfortunately I don't speak any other language well enough to know myself, how good do the translations tend to be? Is it just utilising something like Google Translate where it makes sense 98% of the time but sometimes completely falls apart?

User avatar
Morhighan
Miko-Class Veteran
Posts: 975
Joined: Sun Jun 27, 2010 12:54 pm
Completed: AIdol, When Our Journey Ends, Forgotten Not Lost
Organization: MysteryCorgi
Tumblr: MysteryCorgi
Deviantart: MysteryCorgi
Soundcloud: MysteryCorgi
itch: MysteryCorgi
Location: USA
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#7 Post by Morhighan »

Kinross07 wrote: Sun Aug 06, 2017 2:02 am Unfortunately I don't speak any other language well enough to know myself, how good do the translations tend to be? Is it just utilising something like Google Translate where it makes sense 98% of the time but sometimes completely falls apart?
So we hired a team to manually translate the script and then programmed it using the method above. I don't think Ren'Py actually translates anything itself. Though it would be nice.

Hope that helps! :)

User avatar
Zelan
Lemma-Class Veteran
Posts: 2436
Joined: Tue Mar 01, 2016 7:23 pm
Completed: The Dark
Projects: Cosplay Couple
Tumblr: evns
itch: Zelan
Discord: ltnkitsuragi#7082
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#8 Post by Zelan »

This is absolutely fantastic, thank you so much, Morhigan! ^_^

017Bluefield
Regular
Posts: 93
Joined: Mon Dec 30, 2013 1:55 am
Projects: Project Bluefield - Origins
Organization: Autumn Rain
Deviantart: playerzero17
itch: autumn-rain
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#9 Post by 017Bluefield »

Having a bit of trouble employing the hotspot()? I don't really have an imagemap to use it with...

Code: Select all

    hotspot(500,500,400,200) action ShowMenu("language_chooser")

Code: Select all

While running game code:
  File "game/screens.rpy", line 391, in execute
    screen main_menu():
  File "game/screens.rpy", line 391, in execute
    screen main_menu():
IndexError: list index out of range

fearlessor
Newbie
Posts: 3
Joined: Sat Oct 27, 2018 9:28 am
Contact:

Re: [Tutorial] Creating Translations for Ren'Py Games

#10 Post by fearlessor »

Hello
I want to do the translation. I've created files using Renpy. I even made the language menu on the opening screen. But how do I guide? I do not know. What's missing?

Code: Select all

            if _return_button:
                textbutton _("RETURN") action Return()

            if main_menu:
                textbutton _("START") action Start()
            if main_menu:
                textbutton _("Language") action ShowMenu()
            else:
                #textbutton _("History") action ShowMenu("history")
                textbutton _("SAVE") action ShowMenu("save")

            textbutton _("LOAD") action ShowMenu("load")

User avatar
Morhighan
Miko-Class Veteran
Posts: 975
Joined: Sun Jun 27, 2010 12:54 pm
Completed: AIdol, When Our Journey Ends, Forgotten Not Lost
Organization: MysteryCorgi
Tumblr: MysteryCorgi
Deviantart: MysteryCorgi
Soundcloud: MysteryCorgi
itch: MysteryCorgi
Location: USA
Contact:

Re: Implementing Translations in Ren'Py [Updated Tutorial]

#11 Post by Morhighan »

Updated first post to include the improved tutorial and a link to itch.io version, which will be the location of any future updates.

Ayael
Regular
Posts: 82
Joined: Fri Apr 07, 2017 2:17 pm
Projects: Imperial Grace (on going), Autumn Spirit, Ballads at Midnight
Contact:

Re: Implementing Translations in Ren'Py [Updated Tutorial]

#12 Post by Ayael »

Thank you very much for this tutorial, it's really great ! I was thinking about it, and pop you update it, wonderful ♥
Image Image

User avatar
richycapy
Regular
Posts: 56
Joined: Mon May 27, 2019 8:53 pm
Organization: EN Productions
Location: Mexico
Contact:

Re: Implementing Translations in Ren'Py [Updated Tutorial]

#13 Post by richycapy »

Hi, is there a way to change the lenguaje using a imagebutton ?

User avatar
Andredron
Miko-Class Veteran
Posts: 700
Joined: Thu Dec 28, 2017 2:37 pm
Location: Russia
Contact:

Re: Implementing Translations in Ren'Py [Updated Tutorial]

#14 Post by Andredron »

richycapy wrote: Mon Jun 03, 2019 5:37 pm Hi, is there a way to change the lenguaje using a imagebutton ?
imagebutton..... action.....

User avatar
richycapy
Regular
Posts: 56
Joined: Mon May 27, 2019 8:53 pm
Organization: EN Productions
Location: Mexico
Contact:

Re: Implementing Translations in Ren'Py [Updated Tutorial]

#15 Post by richycapy »

Andredron wrote: Mon Jun 03, 2019 8:25 pm imagebutton..... action.....
Hi

Im doing this:

Code: Select all

vbox xalign 1.0 yalign 1.0:
        if baselang == 'spanish':
            imagebutton auto "images/gui/botones/english_%s.png" hovered tt.Action("Play game in english") action Language(None)
        else:
            imagebutton auto "images/gui/botones/spanish_%s.png" hovered tt.Action("Juega el juego en español") action Language("spanish")
And its not doing anything :(

It did change to spanish, but is not changing back to english, also, is there a way to restart the game after changing the lenguage?

Post Reply

Who is online

Users browsing this forum: No registered users