Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 118 additions & 62 deletions docs/BentoBox/About/Multilingual.md
Original file line number Diff line number Diff line change
@@ -1,84 +1,140 @@
# Multilingual Support
# Languages & Messages

BentoBox and its addons support a wide range of languages out of the box. All in-game messages, GUI text, and item names that players see can be shown in their own language — no extra plugins needed.
Every message, menu and item name in BentoBox and its addons comes from **locale files**: one YAML file per language. Players pick their own language, and you can change any text, colour, or how a message is shown (chat, action bar, title, sound).

## Supported Languages
## Languages

BentoBox currently ships with translations for:
BentoBox ships with 25 languages:

| Language | Code |
| Language | File | Language | File |
|---|---|---|---|
| English (default) | `en-US` | Italian | `it` |
| Chinese (Simplified) | `zh-CN` | Japanese | `ja` |
| Chinese (Traditional, Hong Kong) | `zh-HK` | Korean | `ko` |
| Chinese (Traditional, Taiwan) | `zh-TW` | Latvian | `lv` |
| Croatian | `hr` | Polish | `pl` |
| Czech | `cs` | Portuguese | `pt` |
| Dutch | `nl` | Portuguese (Brazil) | `pt-BR` |
| French | `fr` | Romanian | `ro` |
| German | `de` | Russian | `ru` |
| Hungarian | `hu` | Spanish | `es` |
| Indonesian | `id` | Turkish | `tr` |
| | | Ukrainian | `uk` |
| | | Vietnamese | `vi` |

Addons may have fewer. Each [game mode](../../gamemodes/Comparison.md) and [addon](Addons.md) page has a table showing how complete each language is.

### The server's default language

New players see the default language until they choose one. Set it in BentoBox's `config.yml`, using a file name from the table:

```yaml
general:
default-language: en-US
```

Then restart or run `/bentobox reload`. BentoBox doesn't detect a player's Minecraft language automatically.

### Players choosing a language

Players change language with **`/island language`** (or the game mode's own command), which opens a menu of the languages installed. Their choice applies to BentoBox and all addons, in every game mode.

If a message is missing from the player's language, BentoBox uses the server's default language, then English.

## Changing messages

The locale files are in:

| Text from | Folder |
|---|---|
| English (default) | `en-US` |
| Chinese (Simplified) | `zh-CN` |
| Chinese (Traditional, HK) | `zh-HK` |
| Chinese (Traditional, TW) | `zh-TW` |
| Croatian | `hr` |
| Czech | `cs` |
| Dutch | `nl` |
| French | `fr` |
| German | `de` |
| Hungarian | `hu` |
| Indonesian | `id` |
| Italian | `it` |
| Japanese | `ja` |
| Korean | `ko` |
| Latvian | `lv` |
| Polish | `pl` |
| Portuguese | `pt` |
| Romanian | `ro` |
| Russian | `ru` |
| Spanish | `es` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Vietnamese | `vi` |

Individual addons may support a different subset of languages. Check each addon's page for its specific translation status.

## Setting the Default Language

To set the language all players see by default, edit BentoBox's `config.yml`:
| BentoBox | `plugins/BentoBox/locales/BentoBox/` |
| A game mode or addon | `plugins/BentoBox/locales/<AddonName>/`, for example `locales/BSkyBlock/` |

To change a message:

1. Find it: search the language file (for example `en-US.yml`) for the text players see.
2. Change the text after the key, keeping the key and indentation. Leave anything in square brackets, like `[name]`, `[number]` or `[prefix_island]`, as it is; those are filled in by BentoBox. (`[prefix_island]` becomes the game mode's word for an island, such as "island", "cave" or "box".)
3. Run `/bentobox reload locales`.

```yaml
# Default language for new players.
# Refer to the /locale folder in the BentoBox plugin folder for available languages.
default-language: en-US
commands:
island:
create:
creating-island: "<green>Building your [prefix_island], hang tight...</green>"
```

Set this to any language code from the table above. After changing it, reload the server or run `/bentobox reload`.
Change every language your players use, or the others will still show the old text.

**Your changes are kept when you update.** When BentoBox or an addon is updated, new messages are added to the files on your server, but messages already there aren't overwritten. This also means that if an update improves a message's wording, you won't see it until you delete that line (or the whole file) and reload.

**To hide a message**, set it to an empty string: `creating-island: ""`. Empty messages aren't sent.

**To check for missing translations**, run `/bentobox locale`. It compares each language file, for BentoBox and every addon, with English and reports what's missing.

## Player Language Selection
## Colours and formatting

If enabled, players can switch to their own preferred language using:
Messages use [MiniMessage](https://docs.advntr.dev/minimessage/format.html) tags:

```yaml
example: "<green>Welcome to the island!</green>"
example: "<bold><red>Warning!</red></bold> Something happened."
example: "<gradient:gold:yellow>Island Name</gradient>"
```
/bentobox locale

Old-style colour codes (`&a`, `&l`, `§c`) still work.

## How a message is shown

By default a message goes to chat. Start it with a tag to show it somewhere else:

| Tag | Shows the message |
|---|---|
| `[actionbar]` | Above the hotbar |
| `[title]` | As a big title in the middle of the screen. Add `[subtitle]` to put text in a smaller line underneath |
| `[sound:name:volume:pitch]` | Plays a sound as well. Volume and pitch are optional. Use Minecraft sound names with underscores, for example `entity_experience_orb_pickup` |

```yaml
example: "[actionbar]Teleporting..."
example: "[title]Teleporting...[subtitle]Wait a second."
example: "[sound:entity_experience_orb_pickup:1:1][title]Teleporting...[subtitle]Wait a second."
```

Messages to the console always go to the console log.

### Clickable messages

Add these anywhere in a message to make the whole message clickable or show text on hover:

| Tag | Effect |
|---|---|
| `[run_command: /command]` | Clicking runs the command |
| `[suggest_command: /command]` | Clicking puts the command in the chat box |
| `[open_url: https://...]` | Clicking opens a link |
| `[copy_to_clipboard: text]` | Clicking copies the text |
| `[hover: text]` | Shows the text when the player hovers over the message |

```yaml
example: "You're not on your island. Click to go home![run_command: /island go][hover: Teleport home]"
```

This is useful on international servers where the player base speaks multiple languages.
## Menu text

## Translations Are Community-Made
Menu titles and button text are also in the locale files, referenced from the menu templates. See [Customizing Menus](../../Tutorials/generic/Customizable-GUI.md#change-the-title-or-button-text).

The translations for BentoBox and its addons are contributed by the community. The BentoBox team cannot review every translation in depth, but all contributions are checked for quality before being accepted.
## Fixing or adding translations

!!! note "Translation quality"
Because translations are community-contributed, quality varies. If you spot errors in a translation, please help improve it!
Translations are made with AI help and corrected by the community. If you spot a mistake, fix it in the locale file in the project's GitHub repository and open a pull request, or tell us on [Discord](https://discord.bentobox.world). See [Translating BentoBox](../Translate-BentoBox-and-addons.md) for guidelines and each project's translation status.

## How to Contribute a Translation
## Troubleshooting

Most translations are now generated with the help of AI, so the bulk of the
work is already done — but **AI is not perfect**. The most valuable thing the
community can do is **report errors** and **suggest corrections**.
**My change didn't show.**
Run `/bentobox reload locales`. Check that you edited the player's language (they may not be using English) and the right folder (BentoBox's own messages are in `locales/BentoBox/`, game mode messages in `locales/<GameMode>/`).

* **Spotted a mistake?** Open an issue or a PR on the relevant repository at
[bentobox.world](https://bentobox.world) (a short link to our GitHub org),
or tell us on [Discord](https://discord.bentobox.world).
* **Want to correct a string?** Edit the locale file under
`src/main/resources/locales/` in the relevant repo and open a PR. Do **not**
translate text inside square brackets — e.g. `[name]` should stay as-is.
* **Want to add a brand-new language?** Open a PR adding a new locale file
alongside the existing ones, or ask on Discord and we'll get you started.
**The server shows `commands.island...` instead of a message.**
The key is missing in the player's language, the server's default language and English. Delete the file so BentoBox writes a fresh copy, or add the key back.

A translation helper tool is available at
[download.bentobox.world/translate.html](https://download.bentobox.world/translate.html)
— it runs entirely in your browser. Translators earn a special community badge!
**After an update, a message still has the old wording.**
Your file keeps the old text. Delete that line or the whole file and run `/bentobox reload locales`.

See the full list of addon translation pages at [Translate BentoBox and Addons](../Translate-BentoBox-and-addons.md).
**The YAML file won't load after editing.**
Usually a missing quote or wrong indentation. Put messages containing `:` or `#` in quotes, and check the console for the line number.
64 changes: 15 additions & 49 deletions docs/BentoBox/Translate-BentoBox-and-addons.md
Original file line number Diff line number Diff line change
@@ -1,61 +1,27 @@
## Available locales

{{ translations("BentoBox") }}

## MiniMessage Formatting

BentoBox uses [MiniMessage](https://docs.advntr.dev/minimessage/format.html) for all locale strings. This means you can use MiniMessage tags in your translations to apply rich text formatting. For example:

```yaml
my-message: "<green>Welcome to the island!</green>"
my-message: "<bold><red>Warning!</red></bold> Something happened."
my-message: "<gradient:gold:yellow>Island Name</gradient>"
```

Legacy `§` or `&` color codes are still supported for backwards compatibility and will be automatically converted to MiniMessage format when loaded.
# Translating BentoBox

## Message Delivery Tags
Help translate BentoBox, its game modes and addons. To change messages on your own server instead, see [Languages & Messages](About/Multilingual.md).

Locale strings can control how messages are delivered to players using special inline tags. When no delivery tag is present, the message is sent in chat (the default behavior).

### `[actionbar]`

Sends the message as an **action bar** message (the text displayed above the hotbar).

```yaml
island-go: "[actionbar]Teleporting..."
```

### `[title]` and `[subtitle]`

Sends the message as a **title** overlay on screen. `[title]` displays the large heading text and `[subtitle]` displays smaller text below it. `[subtitle]` is not a standalone delivery type — it only works as a separator inside a `[title]` message. Without `[title]`, it falls through to the chat path.
## Available locales

```yaml
# Title with subtitle
island-go: "[title]Teleporting...[subtitle]Wait a second."
# Title only (empty title, text as subtitle)
scooping: "[title][subtitle]You scooped the lava!"
```
{{ translations("BentoBox") }}

### `[sound:name:volume:pitch]`
## How to help

Plays a **sound** for the player. Volume and pitch are optional (default `1.0`). Use underscore-separated sound names from the Bukkit/Minecraft sound list (e.g. `entity_experience_orb_pickup`). The sound tag can be combined with any delivery type tag.
Translations are made with AI help, so most of the work is done, but AI makes mistakes. The most useful thing you can do is correct them.

```yaml
island-go: "[sound:entity_experience_orb_pickup:1:1][title]Teleporting...[subtitle]Wait a second."
```
1. Find the locale file in the project's GitHub repository, under `src/main/resources/locales/` (for example `fr.yml`). The links below go to each project's translation status.
2. Fix the text and open a pull request. To add a new language, copy `en-US.yml`, rename it to the language code and translate it.
3. Or report the mistake on [Discord](https://discord.bentobox.world) and we'll fix it.

!!! note
Non-player senders (e.g. the console) will fall back to chat output when action bar or title tags are used.
The [translation tool](https://download.bentobox.world/translate.html) runs in your browser and can help with whole files. Translators get a special community badge.

## Guidelines
When translating:

* We now have a tool to enable translations of file at [https://download.bentobox.world/translate.html](https://download.bentobox.world/translate.html). This runs localling in your browser and may help translation. Submit new files as PRs on GitHub.
* Translators get a special badge!
* Do not translate text inside square brackets because those are placeholders, e.g. [name] should remain in English
* Test your translations - try to check everything you can before submitting it
* Do not include any advertising, swear words, or derogatory comments in the translations. We do check them before accepting the PR.
* Feel free to ask questions on Discord about translations.
- **Don't translate anything in square brackets.** `[name]`, `[number]` and `[prefix_island]` are filled in by BentoBox and must stay in English.
- **Keep the formatting tags** like `<green>` and delivery tags like `[actionbar]`. See [Languages & Messages](About/Multilingual.md#colours-and-formatting).
- **Test it on a server** if you can, to check the text fits in menus and titles.
- **No advertising, swearing or insults.** We check every file before accepting it.

## Game Modes

Expand Down
Loading