Developpers : i18n support

One of the best features of eXpansion is it's support multiple languages. When designed it was designed to be simple to use & fast.

Creating A I18n plugin

First of all you need to define your language files in order to define the translations keys. I will remind ou here that eXpansion can only support languages that are supported by ManiaPlanet.

Creating the translations

You will place you translation files in the messages directory of your plugin. So for my test plugin this will be libraries/ManiaLivePlugins/oliverde/test/messages. In this folder you will need to create one txt file for each language. Let say we will do translations for french and english. So we create 2 files

en.txt
fr.txt

And now let say that our plugin sends a Hello World to the connecting players. We will put this content in the files

en.txt

Hello World
Hello World

fr.txt

Hello World
Bonjour le Monde

Creating the plugin that will use them

In this part we will consider you have already read the tutorial about how to create plugins for eXpansion. If you didn't we suggest you should now. Create the MetaData & You plugin file.

Now we will send a message to the player on player connect, so we will catch the onPlayerConnect($login) event .

public function onPlayerConnect($login){
     $this->connection->chatSend(__('Hello World', $login), $login);
}

And you are right this is complicated, we are passing login as argument 2 times. Another problem of this is future use. If you want to send messages to multiple players you will need to send the chat for each player one by one. We will come to this a bit later

public function onPlayerConnect($login){
     $this->exp_chatSendServerMessage('Hello World', $login);
}

Variables in the text

Now that we have a plugin that will say Hello World to all connecting players we wish to change it so that it says Hello This is extremely easy.

First of all let change the translation files :

en.txt

Hello %s
Hello %s

fr.txt

Hello World
Bonjour %s

We will observe the use of %s that actually is used by the php sprintf function

We will also modify our code to look like the fallowing

public function onPlayerConnect($login){
     $this->exp_chatSendServerMessage('Hello %s', $login, array($this->getPlayer($login)->nickName);
}

This way we define our variables, you may use %1$s, %1$s when the order of the variables might change in different translations.

Multilingual announcement

Actually nothing changes, and that is the nice part about it, we provide the abstraction that make it easier for you to send those messages.

Sending the same message translated to multiple players is easy you can use the fallowing code

public function onPlayerConnect($login){
     $this->exp_chatSendServerMessage('Hello World', array('player1', 'player1'));
}

This way all players will receive their content in their native language.

Last step is to send a message to all players, to do this we will just replace the logins with null

public function onPlayerConnect($login){
     $this->exp_chatSendServerMessage('Hello World', null, array('params));
}

I would like to point out that expansion won't do multiple chat calls to send those messages it will use the translation system that is built in the dedicated, so no worry about performances 😄

Optimisation

The problem with the previous code is everytime you send a chat message it will need to look into an array to see if a translation exist for that key. Even if HashMaps are incredibly fast in can slow down when the size of the element to hash increases. We have done our home work and added a secondary system for chat that are used very often

eXpansion will store translations of each key in Message Object, the array we spoke about just points to those objects. The idea is to have variables that directyl points to those Message objects. The idea is to get the translations when the plugin start, OnLoad or onReady.

Let put the fallowing code in one of the 2 methods :

     $this->msg_hello = exp_getMessage('Hello World');

Now to send the message we will use the fallowing code

public function onPlayerConnect($login){
     $this->exp_chatSendServerMessage($this->msg_hello, null, array('params));
}

Hope fully all is clear, if any problem we are here to help