https://github.com/mysy00/LangPlus
Create multilanguage open.mp servers with ease
https://github.com/mysy00/LangPlus
omp-server pawn pawn-package sa-mp sa-mp-library samp sampctl
Last synced: 8 months ago
JSON representation
Create multilanguage open.mp servers with ease
- Host: GitHub
- URL: https://github.com/mysy00/LangPlus
- Owner: mysy00
- Created: 2023-08-29T22:00:14.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-15T21:17:30.000Z (about 2 years ago)
- Last Synced: 2024-10-02T07:04:18.756Z (over 1 year ago)
- Topics: omp-server, pawn, pawn-package, sa-mp, sa-mp-library, samp, sampctl
- Language: Pawn
- Homepage:
- Size: 55.7 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# LangPlus
[](https://github.com/mysy00/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
```bash
sampctl install mysy00/LangPlus
```
```pawn
#include
```
## Quick Start
**`gamemodes/main.pwn`**
```pawn
#include
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`**
```ini
WELCOME_MESSAGE=Welcome, player %d!
PLAYER_JOINED=Player %d joined
```
**`scriptfiles/languages/uk.ini`**
```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:
```pawn
#define MAX_LANGUAGES 8
#define DIRECTORY_LANGUAGES "translations/"
#include
```
## 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:
```ini
; 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
```bash
sampctl run
```
## Credits
Inspired by [ScavengeSurvive/language](https://github.com/ScavengeSurvive/language)