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

# localization

The server language directory is `config/stellarskills/locale`. Its YAML files use **flat keys**, not nested maps. The custom client receives synchronized server wording; fallback UI uses the same server translator where implemented.

The main English reference is [locale defaults](file:///4985688/reference/locales.md). New client English fallback keys are also included there so admins can override quest/choice/Covenant wording without modifying the engine jar.

## Create a language

{% stepper %}
{% step %}

### Copy the English locale file

Copy `en_us.yml` to a supported language-code filename such as `es_es.yml` or `de_de.yml`.
{% endstep %}

{% step %}

### Translate values only

Translate values, not keys. Keep format placeholders like `{0}`, `{1}` in the correct order.

Use scalar strings; nested YAML objects/lists are not translations.
{% endstep %}

{% step %}

### Reload the server configuration

Run `/skills admin reload` and reopen the menu.
{% endstep %}

{% step %}

### Test the locale

Test with a client's Minecraft language set to that locale.
{% endstep %}
{% endstepper %}

The player's client language selects a loaded locale; missing/unloaded languages fall back to `en_us`, and missing translated keys fall back to English. Changing `general.language` alone does not force every player's locale. The sanitization accepts two-/three-letter language and region combinations such as `en_us`.

Limits are 4096 entries per locale, key length 1–160, and value length up to 1600 characters. Text uses Java MessageFormat: preserve numbered placeholders and double a literal apostrophe when necessary (`''`). YAML quoting and MessageFormat escaping are separate concerns.

Example override:

```yaml
quests.back: Back to Skills
quests.title: '<gradient:#55DDF0:#B388FF>Field Journal</gradient>'
```

Only existing consumed keys change their matching UI labels. Adding a random key does not create a new button; use the exact reference key for the field you intend to change. Class, tree, node, quest and module `title`/`description` are server content fields, not automatically translated dictionary IDs.

## Styled text syntax

| Syntax               | Example                                                        |
| -------------------- | -------------------------------------------------------------- |
| Legacy colors/styles | `&aGreen &lBold &rReset`                                       |
| RGB ampersand        | `&#55DDF0Cyan`                                                 |
| RGB tag              | `<#55DDF0>Cyan</color>`                                        |
| Color tag            | `<color:#55DDF0>Cyan</color>`                                  |
| Multi-stop gradient  | `<gradient:#55DDF0:#B388FF:#FFD166>Trainer Journey</gradient>` |

Use quoted strings in YAML. The parser is safe styled text, not arbitrary HTML, MiniMessage execution, JavaScript, or embedded commands. Gradient colors are `#RRGGBB` stops separated by colons. Plain color settings such as a node background accept only hex/auto, not these text tags.

The new engine fallback dictionary is `assets/stellar_skills_client/lang/en_us.json`. Synchronized server keys take priority. Adding those keys to server locale files is the intended customization path; do not edit third-party jars in place.

## Readable effect explanations

The server BenefitFormatter turns known effect keys into readable labels, including typed capture/damage names. Use action effect `filters.display` when a technical permission or custom reward should be described differently. A text override must accurately describe the configured value; it does not change gameplay.

Raw text keys usually indicate an outdated/missing locale entry or a client/server mismatch. Check the actual key in the reference and the engine fallback dictionary before replacing an entire language file. Not every diagnostic log/command output is localized; this guide does not claim every developer error string is a locale entry.