zlang

Per-player language system using GVar or SVar.

The GVar plugin is optional, but recommended when using SA-MP. If the plugin is not used (i.e. gvar is not included before zlang), SVar will be used instead.

You can explicitly control this behavior using:

• #define LANG_USE_SVAR - force SVar mode.
• #define LANG_USE_GVAR - force GVar mode.

The foreach library is optional, but recommended.

Also take a look at the mdialog library, which provides updated versions of Dialog_Open, Dialog_Message, and Dialog_MessageEx with zlang support.

Basic usage

#include <a_samp>
#include <gvar> // optional
#include <zlang>

enum e_LANG_INFO {
	Lang:e_LANG_EN,
	Lang:e_LANG_RU,
}

static
	gLang[e_LANG_INFO];

main() {}

public OnGameModeInit()
{
	// load languages
	gLang[e_LANG_RU] = Lang_Add("ru", "Russian");
	gLang[e_LANG_EN] = Lang_Add("en", "English");

	Lang_LoadFile(gLang[e_LANG_RU], "ru.ini");
	Lang_LoadFile(gLang[e_LANG_EN], "en.ini");

	// set english as the default language
	Lang_SetDefaultLang(gLang[e_LANG_EN]);
	return 1;
}

public OnPlayerCommandText(playerid, cmdtext[])
{
	if (strcmp(cmdtext, "/ru", true, 3) == 0) {
		Lang_SetPlayerLang(playerid, gLang[e_LANG_RU]);
		Lang_SendText(playerid, "LANGUAGE_CHANGED");
		return 1;
	}

	if (strcmp(cmdtext, "/en", true, 3) == 0) {
		Lang_SetPlayerLang(playerid, gLang[e_LANG_EN]);
		Lang_SendText(playerid, "LANGUAGE_CHANGED");
		return 1;
	}

	if (strcmp(cmdtext, "/help", true, 5) == 0) {
		Lang_SendText(playerid, "{FF0000}HELLO_MSG");
		Lang_SendText(playerid, "COMMANDS_LIST");
		return 1;
	}

	if (strcmp(cmdtext, "/help330", true, 5) == 0) {
		Lang_SendText(playerid, "Hello, World!");
		Lang_SendText(playerid, "Commands: /help, /en, /ru");
		return 1;
	}

	if (strcmp(cmdtext, "/multiline", true, 5) == 0) {
		Lang_SendText(playerid, "MULTILINE_EXAMPLE");
		// Line 1,line 2,line 3.
		return 1;
	}

	return 0;
}

scriptfiles/en.ini:

COLOR_GRAY = {CCCCCC}
LANGUAGE_CHANGED = \v(COLOR_GRAY)Now you are using english language.
HELLO_MSG = Hello, {00FF00}World!
COMMANDS_LIST = Commands: /help, /en, /ru
MULTILINE_EXAMPLE_0 = Line 1,
MULTILINE_EXAMPLE_1 = line 2,
MULTILINE_EXAMPLE_2 = line 3.

scriptfiles/ru.ini:

COLOR_GRAY = {CCCCCC}
LANGUAGE_CHANGED = \v(COLOR_GRAY)Теперь вы используете русский язык.
HELLO_MSG = Привет, {00FF00}Мир!
COMMANDS_LIST = Команды: /help, /en, /ru
MULTILINE_EXAMPLE_0 = Строка 1,
MULTILINE_EXAMPLE_1 = строка 2,
MULTILINE_EXAMPLE_2 = строка 3.
# since zlang 3.3.0
Hello, World! = \v(HELLO_MSG)
Commands: /help, /en, /ru = \v(COMMANDS_LIST)

Filterscript example

To use zlang in filterscripts, add #define ENABLE_LANG_MULTISCRIPT to all your scripts (including the gamemode), as shown below:

#include <a_samp>

#define ENABLE_LANG_MULTISCRIPT
#include "zlang.inc"

Language file format

Language file format is a standard INI file format (without sections). It supports a variety of special characters, such as \n, \t, \%, \s, \\, \v(<value>), \x<hex>.

Variables

You can use variables in your text files. This supports any nesting level.

HELLO_MSG = Hello
COLOR_RED = {FF0000}
COLOR_GREEN = {00FF00}
COLOR_WHITE = {FFFFFF}
NAME_ONE = \v(COLOR_RED)Alex\v(COLOR_WHITE)
NAME_TWO = \v(COLOR_GREEN)Peter\v(COLOR_WHITE)
MESSAGE_HELLO = \v(COLOR_WHITE)\v(HELLO_MSG) \v(NAME_ONE) and \v(NAME_TWO)
dynamic_var_test = Hello, \v(%s) <- this is dynamic variable

Example of usage dynamic variables:

// initialize dynamic variables
#define ENABLE_LANG_DYNAMIC_VARS
#include <zlang>

public OnGameModeInit()
{
	// ...init zlang...

	Lang_printf("dynamic_var_test", "MESSAGE_HELLO");

	// result:
	// Hello, {FFFFFF}Hello {FF0000}Alex{FFFFFF} and {00FF00}Peter{FFFFFF} <- this is dynamic variable

	return 1;
}

Defines

Directive | Default value | Note ----------|---------------|------------ INVALID_LANG_ID | Lang:-1 | INVALID_LANG_FILE_ID | -1 | MAX_LANGS | 2 | Can be redefined LANG_VAR_OFFSET | 1000 | Can be redefined LANG_IGNORED_FIRST_SYMBOL | '\0', '#', ';' | Can be redefined MAX_LANG_VAR_STRING | 144 | Can be redefined MAX_LANG_VALUE_STRING | 288 | Can be redefined MAX_LANG_FORMAT_STRING | 144 | Can be redefined MAX_LANG_MULTI_LINES | 25 | Can be redefined MAX_LANG_MVALUE_STRING | MAX_LANG_VALUE_STRING * MAX_LANG_MULTI_LINES | Can be redefined MAX_LANG_MFORMAT_STRING | MAX_LANG_FORMAT_STRING * MAX_LANG_MULTI_LINES | Can be redefined MAX_LANG_SEPARATOR_STRING | 64 | Can be redefined MAX_LANG_CODE | 2 | Can be redefined MAX_LANG_NAME | 16 | Can be redefined MAX_LANG_FILES | 5 | Can be redefined MAX_LANG_FILENAME | 256 | Can be redefined ENABLE_LANG_DYNAMIC_VARS | (disabled) | Can be redefined LANG_SVAR_VARNAME_MASK | "lng%d_%s" | Can be redefined MAX_LANG_PREFIX_SVAR_STRING | 7 + MAX_LANG_VAR_STRING | Can be redefined, available only in SVar mode LANG_SYSVAR_PREFIX | "zlang_" | Can be redefined, available only in SVar mode ENABLE_LANG_MULTISCRIPT | (disabled) | Enables multiscript mode LANG_SYSVAR_VARS_NAME | LANG_SYSVAR_PREFIX "vars_name" | Available only in multiscript mode LANG_SYSVAR_SLOT_NAME | LANG_SYSVAR_PREFIX "slot_name" | Available only in multiscript mode LANG_SYSVAR_SLOT_CODE | LANG_SYSVAR_PREFIX "slot_code" | Available only in multiscript mode LANG_SYSVAR_SLOT_STATUS | LANG_SYSVAR_PREFIX "slot_status" | Available only in multiscript mode LANG_SYSVAR_SLOT_FILES | LANG_SYSVAR_PREFIX "slot_files" | Available only in multiscript mode LANG_SYSVAR_DEFAULT_LANG | LANG_SYSVAR_PREFIX "default_lang" | Available only in multiscript mode LANG_SYSVAR_PLAYER_LANG | LANG_SYSVAR_PREFIX "player_lang" | Available only in multiscript mode

Functions

Add language

Lang:Lang_Add(const code[], const name[])

Remove language

Lang_Remove(Lang:lang)

Remove all languages

Lang_RemoveAll()

Load language file

Lang_LoadFile(Lang:lang, const filename[])

Unload language file

Lang_UnloadFile(Lang:lang, const filename[] = "", fid = INVALID_LANG_FILE_ID)

Reload all language files

Lang_Reload(Lang:lang)

Get language id by code or name

Lang:Lang_Get(code[] = "", name[] = "")

Set language name

Lang_SetName(Lang:lang, const name[])

Get language name

Lang_GetName(Lang:lang, name[], const size = sizeof(name))

Get language name and return it

Lang_ReturnName(Lang:lang)

Set language code

Lang_SetCode(Lang:lang, const code[])

Get language code

Lang_GetCode(Lang:lang, code[], const size = sizeof(code))

Get language code and return it

Lang_ReturnCode(Lang:lang)

Get language codes string

Lang_GetCodes(result[], const size = sizeof(result), const separator = '/', const bool:isuppercase = false)

Get language codes string and return it

Lang_ReturnCodes(const separator = '/', const bool:isuppercase = false)

Check language on valid

Lang_IsValid(Lang:lang)

Get languages count

Lang_GetCount()

Set player language

Lang_SetPlayerLang(playerid, Lang:lang)

Get player language

Lang:Lang_GetPlayerLang(playerid)

Set player language by code

Lang:Lang_SetPlayerLangByCode(playerid, const code[])

Set player language by name

Lang:Lang_SetPlayerLangByName(playerid, const name[])

Set default server language

Lang_SetDefaultLang(Lang:lang)

Get default server language

Lang_GetDefaultLang()

Get language text

Lang_GetText(Lang:lang, const var[], text[], const size = sizeof(text), {Float, _}:...)

Get player language text

Lang_GetPlayerText(playerid, const var[], text[], const size = sizeof(text), {Float, _}:...)

Get default language text

Lang_GetDefaultText(const var[], text[], const size = sizeof(text), {Float, _}:...)

Remove language text

Lang_RemoveText(Lang:lang, const var[])

Is language text exists

Lang_IsTextExists(Lang:lang, const var[])

Language printf function with default language

Lang_printf(const var[], {Float, _}:...)

Language printf function with specific language

Lang_printfex(Lang:lang, const var[], {Float, _}:...)

Language print function with default language

Lang_print(const var[], {Float, _}:...)

Language print function with specific language

Lang_printex(Lang:lang, const var[])

Send language text to player

Lang_SendText(playerid, const var[], {Float, _}:...)

Send language text to all players

Lang_SendTextToAll(const var[], {Float, _}:...)

Send language text to all players in array

Note: iteration over the players array stops when an element with the value INVALID_PLAYER_ID is encountered.

Lang_SendTextToPlayers(const players[], const var[], {Float, _}:...)

Send language text to all players in array

Lang_SendTextToPlayersEx(const players[], const size = sizeof(players), const var[], {Float, _}:...)

Show language dialog to player

Lang_ShowDialog(playerid, dialogid, style, const var_caption[], const var_info[], const var_button1[], const var_button2[], {Float, _}:...)

Show language game text to player

Lang_GameText(playerid, time, style, const var[], {Float, _}:...)

Show language game text to all players

Lang_GameTextForAll(time, style, const var[], {Float, _}:...)

Create TextDraw with language var

Lang_TextDrawCreate(Lang:lang, Float:x, Float:y, const var[], {Float, _}:...)

Sets the language text to the TextDraw for specific player

Note: open.mp