From c1b0c005167ca94ad89b1b4ac0887e773ff44cc2 Mon Sep 17 00:00:00 2001 From: tastybento Date: Sat, 14 Nov 2026 19:53:12 -0800 Subject: [PATCH] docs: rewrite Multilingual as the Languages & Messages admin guide Default and per-player language, where locale files live, changing and hiding messages, how updates merge, formatting, delivery and clickable tags, troubleshooting. Translating page keeps contributor guidance and status tables. Checked against BentoBox source. Co-Authored-By: Claude Opus 5.5 --- docs/BentoBox/About/Multilingual.md | 180 ++++++++++++------ .../BentoBox/Translate-BentoBox-and-addons.md | 64 ++----- 2 files changed, 133 insertions(+), 111 deletions(-) diff --git a/docs/BentoBox/About/Multilingual.md b/docs/BentoBox/About/Multilingual.md index dbeebe3e..a2304da6 100644 --- a/docs/BentoBox/About/Multilingual.md +++ b/docs/BentoBox/About/Multilingual.md @@ -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//`, 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: "Building your [prefix_island], hang tight..." ``` -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: "Welcome to the island!" +example: "Warning! Something happened." +example: "Island Name" ``` -/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//`). -* **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. diff --git a/docs/BentoBox/Translate-BentoBox-and-addons.md b/docs/BentoBox/Translate-BentoBox-and-addons.md index 3863f4da..e485e449 100644 --- a/docs/BentoBox/Translate-BentoBox-and-addons.md +++ b/docs/BentoBox/Translate-BentoBox-and-addons.md @@ -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: "Welcome to the island!" -my-message: "Warning! Something happened." -my-message: "Island Name" -``` - -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 `` 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