LangPlus

A lightweight multilanguage library for open.mp servers. Uses simple INI files for translations and provides an easy-to-use API for managing player languages.

Installation

sampctl install mysy00/LangPlus

#include <LangPlus>

Quick Start

gamemodes/main.pwn

#include <LangPlus>

new Language:g_English, Language:g_Ukrainian;

public OnGameModeInit() {
    g_English = LoadLanguage("en", "English");
    g_Ukrainian = LoadLanguage("uk", "Ukrainian");
    return 1;
}

public OnPlayerConnect(playerid) {
    SetPlayerLanguage(playerid, g_Ukrainian);
    SendLanguageMessage(playerid, -1, "WELCOME_MESSAGE", playerid);
    SendLanguageMessageToAll(-1, "PLAYER_JOINED", playerid);
    return 1;
}

scriptfiles/languages/en.ini

WELCOME_MESSAGE=Welcome, player %d!
PLAYER_JOINED=Player %d joined

scriptfiles/languages/uk.ini

WELCOME_MESSAGE=Вітаємо, гравець %d!
PLAYER_JOINED=Гравець %d приєднався

API Reference

Function	Description
Language:LoadLanguage(code[], name[], fileName[])	Load a language from INI file
SetPlayerLanguage(playerid, Language:id)	Set player's language
Language:GetPlayerLanguage(playerid)	Get player's current language
SendLanguageMessage(playerid, colour, key[], ...)	Send localized message to player (supports format specifiers)
SendLanguageMessageToAll(colour, key[], ...)	Send localized message to all players in their language
GetLanguageString(Language:id, key[], output[], len)	Get translated string for a language
ReturnLanguageString(Language:id, key[])	Return translated string (use immediately)
GetLanguageCount()	Get number of loaded languages
bool:HasLanguage(code[])	Check if language exists
GetLanguageList(languages[][], maxSize)	Get array of language display names
SetStringReplacement(key[], value[])	Define replacement for language loading (call before LoadLanguage)

Configuration

Define before including the library:

Macro	Default	Description
MAX_LANGUAGES	4	Maximum number of languages
DELIMITER_CHAR	"="	Key-value separator in INI files
DIRECTORY_LANGUAGES	"languages/"	Language files directory
MAX_LANGUAGE_KEY_LEN	32	Maximum key length
MAX_LANGUAGE_ENTRY_LENGTH	768	Maximum translation length
MAX_LANGUAGE_NAME	32	Maximum language name length
MAX_FILE_NAME	64	Maximum file name length
MAX_REPLACEMENT_KEY_LEN	16	Maximum replacement key length
MAX_REPLACEMENT_VALUE_LEN	16	Maximum replacement value length

Example:

#define MAX_LANGUAGES 8
#define DIRECTORY_LANGUAGES "translations/"
#include <LangPlus>

Language File Syntax

Language files use INI format with the following rules:

• Key format: Keys must start with a letter (a-z, A-Z), digit (0-9), or symbol (!, @, $, &)
• Delimiter: Keys and values are separated by = (configurable via DELIMITER_CHAR)
• Comments: Lines starting with other characters are ignored (e.g., ;, #, [)
• Escape sequences: Supports \n, \t, etc. in values
• Format specifiers: Values can contain %d, %s, %f, and other format specifiers

Example:

; This is a comment
WELCOME_MESSAGE=Welcome, player %d!
@ADMIN_COMMAND=Admin %s used command
$ERROR_MESSAGE=Error: %s

Features

• Fallback system - Missing keys fall back to the default language, that is: Language:0
• String replacements - Use SetStringReplacement() for dynamic text substitution
• Format specifiers - Full support for %d, %s, %f, etc.
• Escape sequences - Supports \n, \t in language files
• Auto-trimming - Keys and values automatically trimmed

Testing

sampctl run

Credits

Inspired by ScavengeSurvive/language