PlayerLangAPI

A simple, lightweight language API for KarsaMine-MP plugins.

This plugin provides per-player language management and translation support which other plugins can use as a dependency.

---

Quick summary (for server admins)

• What it does: lets players choose their language and lets other plugins show translated messages per player.
• Why it is useful: if you run multilingual servers or plugins that want to present messages in the player's language, this provides a central, consistent solution.
• Commands provided: /lang to list, set and reset language.

---

Installation (server admin)

1. Download the PlayerLangAPI plugin (PHAR) and place it in your server's plugins/ folder.
2. Start the server — the plugin will create a plugin_data/PlayerLangAPI/ folder and a default configuration file.
3. Edit plugin_data/PlayerLangAPI/config.yml if you need to change the database settings (the plugin works with SQLite out of the box).

If the plugin logs an error about libasynql on startup, check the database section inside the plugin data config.yml — common issues are missing entries for SQLite or invalid MySQL credentials.

---

Basic commands (players)

• /lang — show available languages (the command lists codes and human-readable names)
• /lang set <code> — set your language (saved to the database)
• /lang reset — remove your saved preference (the server will again use your client locale or the default)

Permission: playerlangapi.command (server operators can change this via their permission manager).

All command output is translated using the plugin's global translations, so players see messages in their chosen language when translations are available.

---

Bundled languages and editing translations

PlayerLangAPI comes with a set of bundled language files (English plus regional translations). On first run the plugin will attempt to copy these files into:

plugin_data/PlayerLangAPI/lang/global/

You may edit those YAML files to customise the messages or add new language files (named <code>.yml, for example id.yml for Indonesian). After editing, reload the plugin or restart the server so the changes are picked up.

Files use a simple dot-notated key structure. Example (in en.yml):

lang:
  set: "Your language has been set to {lang}"
  reset: "Your language has been reset"

---

Simple troubleshooting (server admin)

• Error: Failed to initialise libasynql: Config problem: Database settings are missing or incorrect
  • Open plugin_data/PlayerLangAPI/config.yml and verify the database block.
  • For SQLite, ensure sqlite.file is writable in the plugin data folder.
• If a language file does not appear in the data folder after restart, ensure the plugin PHAR includes the resource; you can copy your own files to plugin_data/PlayerLangAPI/lang/global/ and restart.

---

For plugin authors (short guide)

If you are a plugin developer and want to use PlayerLangAPI as a dependency, here is the minimal information you need.

1. Get the API instance:

   $api = KirizaNetwork\PlayerLangAPI\PlayerLangAPI::getInstance();

2. Register translations (recommended): place your translations in your plugin's data folder as <code>.yml and call:

   $api->registerFromYaml($this, $this->getDataFolder() . "lang/");

3. Translate text for a player:

   $text = $api->translate($player, $this /* pass your PluginBase instance or null for global */, 'messages.welcome', ['{player}' => $player->getName()]);
   $player->sendMessage($text);

4. Useful helpers:

   • translateForSender(CommandSender $sender, ?PluginBase $plugin, string $key, array $params = []) — for console or generic senders
   • getAllAvailableLanguagesWithNames() — returns code => display name (useful for GUIs)
   • getLanguageDisplayName(string $lang) — human-readable name for a language code

Notes for plugin authors

• Always pass your PluginBase instance (not a string) when registering translations — that prevents collisions between plugins.
• The API will normalise locale strings and build candidate codes so en_GB, en-GB, en and en_gb are handled sensibly.

---