> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/edlang/readme.md).

# EdLang

Per-player languages for **every plugin**, with no plugin integration needed.

**How it works:** wherever a plugin shows a text (its config, a chat message, a scoreboard, a hologram, an item lore, a menu title...), you put a placeholder instead of the text, and you write the translation of that placeholder once per language. EdLang replaces each placeholder in the language of the player who sees it, on its way to that player. Ten players looking at the same hologram read it in ten languages.

```yaml
# a scoreboard plugin's config
title: '{lang:scoreboard.title}'
lines:
  - '{lang:scoreboard.balance|%vault_eco_balance_formatted%}'
```

```yaml
# plugins/EdLang/lang/en/server/scoreboard.yml       # plugins/EdLang/lang/es/server/scoreboard.yml
scoreboard:                                           scoreboard:
  title: '&b&lMY SERVER'                                title: '&b&lMI SERVIDOR'
  balance: '&7Balance: &a{0}'                           balance: '&7Dinero: &a{0}'
```

Each language is a folder (`lang/en/`, `lang/es/`...) with as many `.yml` files and subfolders as you like, so a big server keeps its translations organised by plugin, menu or feature. Start with [How translations work](/p/edlang/getting-started/how-translations-work.md).

## Features

* **Works with every plugin**: a packet translator (PacketEvents) replaces placeholders in chat, action bars, titles, boss bars, sidebars and teams, tab list, menu titles, item names and lore (inventories, cursor, trades, armour), entity names and holograms (text displays, armour stands, NPCs), dropped items, item frames, signs, books, advancements, death messages, kick screens and the resource-pack prompt.
* **Fast**: a packet without a placeholder is let through after a byte scan (about 350 ns for a 2 KB packet), without being decoded. Translated parts are cached per language. See [Performance](/p/edlang/reference/performance.md).
* **Two placeholder forms**: `%lang_key%` and `{lang:key|arg1|arg2}` with positional and named arguments, nested placeholders, legacy colours, hex and MiniMessage values, multi-line values.
* **Organised translations**: unlimited files and subfolders per language, optional `key-prefix:` per file, duplicate key warnings, `/edlang missing <code>` to see what a language still lacks, `/edlang reload` without lag.
* **Automatic language**: the player's Minecraft language (followed live when they change it), their country (free GeoIP database, downloaded for you) as a fallback, and a first-join picker.
* **Menus**: `/lang` language menu with flag heads, `/lang settings`, the first-join picker. Plain chest menus, fully configurable (items, slots, actions, conditions, pages, sounds). No resource pack needed.
* **Chat translation** (optional): player chat translated into each reader's language with DeepL, Google Cloud, LibreTranslate or any OpenAI-compatible API. Cache, per-player limits, daily budget, usage stats, per-player toggle, the original on hover.
* **Safe**: players can't type placeholders; creative mode never stores translated items; only the copy sent to each player changes, never the real item, hologram or scoreboard.
* **Storage**: YAML or MySQL / MariaDB (shared between servers), with `/edlang migrate`.
* **PlaceholderAPI** placeholders and a **developer API** with events.
* EdLang's own texts in English, Spanish, German, French, Portuguese and Italian.

## Requirements

* Paper 1.21 or newer (Java 21).
* **PacketEvents** 2.x (built against 2.13; use the latest release) for the packet translator. Without it EdLang still runs (API, PlaceholderAPI, menus, chat translation) and says so in the console, but texts of other plugins are not translated.
* Optional: PlaceholderAPI.

## Quick start

1. Put `EdLang.jar` and PacketEvents in `plugins/`, restart.
2. Open `plugins/EdLang/lang/en/server/`: the example files show keys for a scoreboard, the tab list, holograms, messages and a crates plugin. Copy the idea for your own texts.
3. In another plugin's config, replace a text with its placeholder, e.g. `'{lang:holograms.spawn.welcome}'`.
4. Write the same key in `lang/es/...` (and every other language you want), then `/edlang reload`.
5. Players pick their language with `/lang`, or keep the automatic one.

## Folder

```
plugins/EdLang/
  config.yml                 every option (packets, placeholders, detection, menus, chat translation, storage)
  lang/<code>/**/*.yml       one folder per language, any files and subfolders
  lang/<code>.yml            optional: the EdLang 1 single-file layout, merged with the folder
  menus/                     languages.yml, settings.yml, first-join.yml
  players.yml                language choices (YAML storage)
  data/translation-usage.yml chat translation usage per day
  country.mmdb               the GeoIP country database
```