Fusion 2.5+
Guides & Tips+

Localization in MMF2 and Fusion 2.5

Localization in MMF2 and Fusion 2.5

What is localization? Localization means support for multiple languages. With the 'new' runtimes such as iOS and Android, localization is getting more and more important. Oldtimers such as most of us developers are used to getting everything in English, but today the average iPad or phone-user is used to get apps and games in his / her own language.

How do I make my game or app support multiple languages?

Fusion doesn't come with any localization tools, so you'll have to create your own system. However, creating a localization system yourself is actually quite easy. Well, the easiest solution might be to create multiple versions of your game, or multiple identical frames just with a different language, but this is not very developer-friendly as it mean you'll have to change your code several places whenever you're doing a slight change in your game. Another method could be to use active obects instead of strings, which kind of works, but makes your game consume more memory / space and doesn't allow for easy translation of the game.

So, now when know how not to do it, why not figure out a cool way to have multiple languages in our game which is both effective and translation-friendly? 
The method I am going to talk about in this article is, yeah, you probably figure it out by now allready (since I'm Popcorn I mean): ini-files. Ini-files are great in that they are supported by all the Fusion runtimes and is easy to edit. If all the text in your game is in an inifile, all you need to do if you want the entire game to be translated to another language, is to simply edit the file yourself, or hand it over to the person or company that will do the translation for you. They never need to see any code whatsoever.

How should I organize my game's text??

First off, I recommend you learn how to use the ini-object. This isn't a tutorial, but I will try to explain everything needed in this article, however it might be easier for you to follow if you allready have a good understanding of how inifiles works. There are several tutorials on how to use the ini object scattered around. 

I'll show you straight up how your ini-file might be going to look like:

Game over=Game over
Introtext=Welcome, {username}, to this fantastic world!

[Silly language]
Game over=Gamba Bomba
Introtext=Wabba, {username}, ma takka falakka wobba!

Ok, it probably wouldn't look exactly like that in your game, but that doesn't matter. The important thing is that you have the syntax right: One group for each language, and one item for each string in the game.

Name your ini-file "mygame_localization.ini". When you're developing it's nice to hardcode the filepath, such as "c:\mygame_localization.ini". Put an ini-object in each of your game's frames that needs localization, make it use your ini-file and give the ini-object an fitting name such as "Ini Localization".

How to work with the ini-file

I'll talk about how to setup your game to select a language later, but for now it is important to know that we'll be using a global string to tell Fusion which language is currently active. Rename a Global String to 'Language', and set it to 'English'.

Whenever you are setting a text, instead of setting it to "Game over", you will be setting it to GroupItemString$( "Ini Localization", Language, "Game over"). You see here why I named each item the way I did; it is easy to read in the event editor what the text is saying.

It is good practice to have an Eventgroup labeled 'Localization' in each frame that have static text. In this group you'll localize all strings that wouldn't be changed during the game. Some times you'll have dynamic text, such as dialogues, messages etc. These texts can have its localization in the actual event that sets the text.


Notice the Infotext item in the inifile. This text have a stand-in variable named {username}. Sometimes you have variables in your game that should not be translated, but can also not be in the inifile simply because you don't know what word or text it will be. So we use a stand-in for that variable. In your game you will have to replace that bit of text with the actual variable. You don't need {}, but it makes variables easier to spot for the person who will do the translation, and makes sure only the wanted text gets replaced.

By the time I write this, Fusion does not have a way to replace strings natively. You will have to use an extension for this. I am using String Parser 2 to replace my stand-in variables with the true variables. String Parser 2 is not the easiest extension to work with, but it is supported by all the Fusion runtimes. If you are developing for Windows only, you can choose another simpler extension to do the string replacement for you. I am using one String Parser object for just this purpose, and I have renamed it to String Parser Replace Text.

For strings that have variables, we set the Source string of the String Parser object to GroupItemString$( "Ini Localization", Language, "Introtext").
In this example we have setup a Global String named Username. We therefore set the text to replace$( "String Parser Replace Text", "{username}", Username). This is an effective way to set the text to the correct language and the correct variable.

You can choose if you want to set all the localized text directly into the text-objects, or if you want it to go through the String Parser object. If you have lots of variables that appears in your texts, it may be smart to have all text go through the String Parser so that it can replace the stand-in variables with the true variables in your game. That way you'll treat all text the same way, and it will be easy to insert variables in any text if you will need it in the future. For instance, since lineshifts isn't quite straightforward to have in ini-files, you could have a stand-in variable named {newline} that you replace with Newline$ all the places you want to have a lineshift.

How to select a language

If you're developing for iOS there's a way to detect the device's preferred languages. Simply detect what language the device is using and set your Global String Language to that language. If the device is set to "en", you may set Language to "English", and if it is set to "de", you may set it to "German".

In any case you'd like to have an options-screen where the user can set the language. You can save which language is set using another ini-file. The ini-file we have been using so far should be used for localization only, and never be written to by the game or app.

How to export the localization-file with the game

The Localization ini-file should be added to Binary Data in Data Elements. This way the content of the file will be transferred when you compile your final application.

Okay, that's it for now. Thanks for reading! Please report any mistakes I might have done, suggestions, alternate methods etc so that this article gets as good as possible 

Additional Resources

Original Form Post: https://community.clickteam.com/threads/83785-Localization

Original Author: Forum User Popcorn

Spread the word!

You can share this document using the following buttons.

Submit your own User Tip