YSI:Using Text
From SA-MP Wiki
Contents |
Introduction
The basic idea of the YSI text system is to allow multiple languages on a single server at once very simply, you do this by instead of doing something like:
SendClientMessage(playerid, 0xFF0000AA, "Welcome to the server");
You do:
Text_Send(playerid, "WELCOME_MESSAGE");
You can then define "WELCOME_MESSAGE" as "Welcome to the server" in an English file, and "Welkom in de server" in a Dutch file for example, the system will then display the message corresponding to the recipient's language, rather than just having the server limited to a single language.
It also has in-line format functions (i.e. no need to use format on a string and then send that string) so you can do:
Text_SendFormat(playerid, "WELCOME_MESSAGE", ReturnPlayerName(playerid), playerid);
And in the language file put:
WELCOME_MESSAGE = Welcome to the server %s (ID: %d)
And the player (assuming they were English) would see:
Welcome to the server Y_Less (ID: 0)
(or something similar).
If a text entry is not found for a users selected language the system will attempt to display the message to the player in the default language, if this is also not found the system will send a TEXT_NOT_FOUND error. To disable this error simply change YSI_TEXT_NOT_FOUND in the language files (found in the "core.XX" files) to have no value, DO NOT remove the entry as this will cause another error to be shown, one which can't easily be removed and one which there's no point removing as the first is easy to remove.
Use
The use requires editing in a few places but makes things much better in the end.
Entries
Firstly you need to create the files which will store your text, these need the same filename and extensions related to the language contained within them. For the example we'll make example.EN for the English text and example.NL for the Dutch text. The identifiers MUST NOT change between files, they can be anything you like but if you translate them the system won't work properly. Both these files should be placed in the scriptfiles folder for now:
example.EN:
[join_messages] WELCOME_MESSAGE = Welcome to the server %s (ID: %d) EXIT_MESSAGE = Hope to see you again soon
example.NL:
[join_messages] WELCOME_MESSAGE = Welkom in de server %s (ID: %d) EXIT_MESSAGE = Wij hopen je hier snel weer te zien
Loading
Now we've done that we need to signal the system to load these files, in the default YSI new file in the init functions there are lines like:
Langs_AddLanguage("EN", "English"); Langs_AddFile("core", "YSI");
That tells the system to load the language files called core.XX (where XX is a language extension) in the subdirectory of scriptfiles called /YSI , this file contains all the text used by YSI itself, e.g. the property messages, login text etc. It also tells the system to load English messages only currently, informing it that English message files end in .EN and that the name of this language in it's own language is "English" (for the /languages command). We need to add the file with our text to the system and tell it to load Dutch text too (this will also load core.NL, but this is good). The example.XX files are in the scriptfiles folder, not a subdirectory of it so there's no need for the directory parameter:
Langs_AddLanguage("EN", "English"); Langs_AddLanguage("NL", "Nederlands"); Langs_AddFile("core", "YSI"); Langs_AddFile("example");
As explained in the INI documentation all data in an ini file requires an associated tag, in the examples above this is [join_messages] so we need to tell the system to load text under these tags, this is so text not used at all (e.g. in YSI libraries optionally excluded) isn't loaded to waste memory. OUTSIDE a function do:
Text_RegisterTag(join_messages);
Displaying
You now have all the data loaded into the system in two languages (by default you can load up to 4 at once) so you can start using it. This is very simple and mostly already explained. To display a message to a player in their selected language do:
Text_Send(playerid, "TEXT_IDENTIFIER");
To send a message to all players, each one receiving it in their selected language do:
Text_SendToAll("TEXT_IDENTIFIER");
This is not the same as calling Text_Send repeatedly, there are optimizations in the code so that certain lookups and language text retrievals are only done once, a loop with Text_Send in would do these things repeatedly.
Formats
As mentioned you can change any of the functions mentioned above into format versions simply be appending "Format" to the end of the function. This turns the string in the file to a format string, as with WELCOME_MESSAGE in the example above:
Text_SendFormat(playerid, "WELCOME_MESSAGE", ReturnPlayerName(playerid), playerid);
(ReturnPlayerName is a generic function implemented in YSI).
The format options implemented in YSI and more are explained in greater detail here.
Exclusion
If you have text in a file and DON'T want it to show, simply remove the value - removing the entire line will give a "Text not found" error. The system is written so blank values will not be shown at all, it won't try show a blank line:
YSI_TEXT_NOT_FOUND = ; Line above exists but has no value ; If you are wondering ; is a comment in INI files
Appearance
As mentioned above the appearance of text is defined in a file, the name of the file is "<name>_format.YSI", e.g. the name of the format data for the YSI core data is core_format.YSI, for the example file it would be example_format.YSI. The style files uses the INI load system but is not a valid INI file so attempting to write to it from the script will destroy it, for this reason a new style system is being written using the XML system but it's not finished yet.
Sections
There are two sections to the file, the first is color section (or colour), this has a list of named colors and their hex values. The second is the data section and contains style data for the text entries.
color
To define a colour simply define a key/value pair where the key is the name of the colour and the value is the hex value:
[colors] RED = 0xFF0000AA GREEN = 0x00FF00AA BLUE = 0x0000FFAA
data
The data section defines how a single piece of text appears. You need to first state which text you are going to set the style for, then how it will appear, then additional data for the appearance (time, colour etc). To define which text identifier you're setting the style for either simply write the identifier or set it as a name parameter, so to set data for the welcome message from the examples above:
name = WELCOME_MESSAGE
Or simply:
WELCOME_MESSAGE
You then need to set the type of text the text will appear as. This is either 0 for SendClientMessage, -1 for TextDraw or 1-6 for GameText (depending on which GameText style you wish to use):
type = 0 ; use SendClientMessage type = -1 ; use TextDraw type = 1 ; use GameText type 1
The final parameter controls the appearance of the data. For SendClientMessage it's the colour (or color if you're American) of the message, for GameText it's the time the message will display, for TextDraw it's the named style, but this is covered elsewhere:
Set "WELCOME_MESSAGE" to a green SendClientMessage:
WELCOME_MESSAGE type = 0 colour = GREEN
Set "WELCOME_MESSAGE" to a green SendClientMessage another way:
WELCOME_MESSAGE type = 0 color = 0x00FF00AA
Set "WELCOME_MESSAGE" to GameText style 3 displaying for 5 seconds (5000 milliseconds):
WELCOME_MESSAGE type = 3 time = 5000
Set "WELCOME_MESSAGE" to TextDraw style "MY_STYLE" (defined elsewhere):
WELCOME_MESSAGE type = -1 style = MY_STYLE
