Skip to main content

Plugin Configuration

This page is a guide on Triton's config.yml file.

Introduction​

This file is where you can configure how Triton will behave in that server.
Triton's default config file has comments all over the place, which do a great job at explaining what everything does. However, this page will explain some settings in more detail.

You can check out Triton's default Spigot, BungeeCord, and Velocity config.yml at any time on GitHub.

Languages section​

This section allows you to add/remove languages from Triton.
Triton is fully customizable, which means you can create as many languages as you'd like!

Each language must have a language ID (the key of the YML section), a flag, and a display-name.
The commands, fallback-languages, and minecraft-code properties are optional.

Example language
languages:
  en_GB:
    flag: eapwplpnpmbzbj
    display-name: '<green>English (UK)'
warning

When using a proxy (e.g., BungeeCord or Velocity) with a non-local storage option (read below), you'll need to make sure this section is exactly the same across all servers.
The only exception to this rule is the commands field that is ignored on Spigot servers when using a proxy, regardless of storage options.

flag​

Represents the flag to show up in the banner in the language selection menu. Follow the generating a flag guide if you don't know what to put here.

minecraft-code​

This is a list of the corresponding locales in Minecraft.
It is currently used to automatically set the player's language when they join for the first time, if there is a corresponding locale.
If there is not a corresponding locale, it falls back to the main language.
You can find the complete list of locales in the Minecraft Wiki.

All the values in the list are case-insensitive.

Usage example
languages:
  en_GB:
    flag: eapwplpnpmbzbj
    display-name: '<green>English (UK)'
    minecraft-code: [en_GB, en_US, en_AU, en_CA, en_NZ, en_PT, en_UD]

display-name​

This is what will show up as the language name in chat and the selection GUI. It supports MiniMessage styles and Triton placeholders.

fallback-languages​

Added in 3.7.0

Sometimes you might have missing translations on all languages or just don't want to fallback directly to the main language (e.g. make European Portuguese fallback to Brazillian portuguese first and then English).
This is a list of languages to try if the translation is not available in this language.

Regardless of the value of this field, Triton will always attempt to fetch the translation from the default language after trying all the languages in the config.

Example

Consider the following configuration (some fields are removed for simplification):

languages:
  en_GB:
    display-name: '&aEnglish (UK)'
    fallback-languages: []
  pt_PT:
    display-name: '&aPortuguese (Portugal)'
    fallback-languages:
      - 'pt_BR'
      - 'es_ES'
  pt_BR:
    display-name: '&aPortuguese (Brazil)'
    fallback-languages:
      - 'pt_PT'
      - 'es_ES'
  es_ES:
    display-name: '&aSpanish (Spain)'
    fallback-langauges:
      - 'pt_PT'
      - 'pt_BR'

main-language: en_GB

If a player has their language set to pt_PT (Portuguese Portugal), Triton will attempt to get the translations from the following languages, in order, until that language has the requested translation:

  • Portuguese (Portugal) - pt_PT
  • Portuguese (Brazil) - pt_BR
  • Spanish (Spain) - es_ES
  • English (UK) - en_GB

commands​

There are 4 types of commands you can execute: PLAYER, SERVER, PROXY, PROXY_PLAYER; with the last two being available on a proxy only.

  • PLAYER: Runs the command as if the player typed it in the chat.
  • SERVER: Runs the command from console.
  • PROXY: Runs the command from the proxy console.
  • PROXY_PLAYER: Runs the command as if the player typed it in the chat, but on the proxy side.

There are 2 available variables for use: %player% and %uuid%.

  • %player%: Player's name
  • %uuid: Player's UUID (with dashes)

If you're using a proxy, you can also limit commands to certain servers by doing something like: PROXY:lobby,lobby-2,lobby-3:alert This will only run on 3 servers!

warning

The commands must not have a preceding slash (/).

Examples​

Run command as a player:

PLAYER:say I'm using English now!

Run command as console, using 2 variables:

SERVER:say %player% (%uuid%) has just changed their language!

Run command on the proxy console, but only if the player is on the lobby server:

PROXY:lobby:alert This will only run on lobby!
tip

(proxy only) If a command you're using contains a : and you want it to be universal, do something like this: PLAYER::give @a minecraft:dirt

main-language​

The Language ID (the key of the section) of the main language.
This will be the default language of a player when they join the server for the first time, if no corresponding locale is found. This will also be used to get a message if you don't have it translated in the player's language yet.

General settings​

twin-token​

If you're using a proxy, you only need to place your TWIN token in the Triton's config on the proxy.
To learn more about TWIN and how you can get the token, visit the TWIN documentation page.

open-selector-command-override​

Spigot Only
Default: null
If you want to open a custom menu (or even just execute a custom command) instead of opening Triton's default language selector menu, put the command here, without the first slash (/).
Instead of opening the language menu, Triton will execute this command as the player.

Example: open-selector-command-override: "dm open language"

Set to null or an empty string to revert to default behaviour.
Since this is Spigot only, this can be set on a per-server basis.

run-language-commands-on-join​

Default: false
When enabled, the commands defined for each language are also run when the player joins the server, instead of only on language change.

force-client-locale-on-join​

Default: false
By default, Triton attempts to identify the locale used by the client and find a similar locale in the available languages when the player joins the server for the first time.
When this is enabled, Triton does this every time a player joins the server, effectively ignoring the player's preferences between rejoins.

It is highly recommended to leave this disabled for user experience purposes.

config-auto-refresh-interval​

Default: -1 (disabled)
When this option is enabled, Triton reloads automatically (in this server) every X seconds. It is recommended to use a relatively high value here to avoid lag.

command-aliases​

Default: lang, language
The aliases of the /triton command to register. This is especially useful as a way to customize the command that opens the language selection menu.

log-level​

Default: 0
This option changes how verbose Triton's log messages will be.

Available log levels:

  • 0: Corresponds to INFO. Logs useful information, such as successfully loading configurations.
  • 1: Corresponds to DEBUG. Logs more detailed information about each event.
  • 2: Corresponds to TRACE. Logs every action made by the plugin. Useful for reporting issues, but will print a lot of information.

storage​

This section defines where Triton will save/load translation and language preferences. At the moment, languages aren't synced automatically when a non-local storage option is in use.

A more detailed guide on this section can be found in the storage page.

message-parser​

Default: adventure
Defines which parser to use when translating messages. Two parsers are available:

  • adventure, which replaces translations in Adventure components directly; and
  • legacy, which converts components to an internal string representation (equivalent to Triton v3 and earlier).

Experimental settings​

experimental-async-protocol-lib​

Default: false
Intercept and parse ProtocolLib packets asynchronously. This should improve performance by avoiding blocking the main thread.

See this experimental feature's page for more information.

experimental-use-packetevents​

Default: false
Use PacketEvents instead of ProtocolLib (for Spigot/Paper) or native implementation (for BungeeCord and Velocity) for intercepting packets.

See this experimental feature's page for more information.

Using a proxy​

To use a proxy (such as BungeeCord or Velocity), you must enable behind-proxy on config. Furthermore, make sure all your servers (including the proxy) are using the same version of the plugin, otherwise you may encounter unexpected issues.
While using a proxy, your translations folder is ignored in all servers except the proxy. The languages section in the config is also ignored if using local storage.

Make sure the storage settings match on all servers.

Language creation​

This section only applies to the current server/proxy, which means you can customize it to fit the needs of a specific situation.

Triton's placeholders are composed of two tags: lang and arg. In this section, you can change these per context type, giving you huge amounts of flexibility! You can also enable/disable certain translation contexts if you aren't using them or they're causing issues.
Some contexts also have more options, so read the YAML comments to get to know them.

disabled-line​

This feature was requested by a user and it's extremely useful in certain situations.
Using Triton's ability to intercept every packet, you can block messages with being sent by using this.

For example, if you set disabled-line: 'disabled.line', any chat message that contains [lang]disabled.line[/lang] won't be sent at all.
Depending on the context, this placeholder behaves differently:

  • Chat: the message isn't sent and there isn't any visual indication of that message on the client. It behaves as if that message never existed.
  • Actionbar: same as chat, with the pro that it doesn't even hide the current actionbar if there is one.
  • Items titles: the client will see the default item material name (in their client locale) instead of the custom display name (e.g. Block of Diamond).
  • Item lores: the line containing the disabled line placeholder will be removed from the lore.
  • Books: the page containing the placeholder is deleted.
  • Titles and subtitles: If there is a disabled line placeholder in the title, neither the title nor the subtitle will be sent. If there is a disabled line placeholder in the subtitle, only the subtitle won't be sent. Like actionbars, it won't hide the current title/subtitle if there is one.
  • Tab header/footer: The header/footer will be removed.
  • Bossbars: The text of the bossbar will be blank.
  • GUI titles: The title will be blank.
  • Entities: Their display name will be hidden.
  • Custom TABs: The display name of the entity will be swapped for the real entity name.
  • Kick: The kick message will be blank.

terminal​

Default: false
When enabled, placeholders that appear on console with chat's syntax will be translated to the default language.

prevent-placeholders-in-chat​

Default: true
When enabled, if a player types a placeholder in the chat, it will be ignored by Triton. Otherwise, the placeholder will be translated like normal.
Keep in mind that placeholders outside the player's message (e.g. in the prefix), will still be translated when this is enabled.

max-placeholders-in-message​

Default: 10
How many placeholders the plugin should try to translate before giving up. This prevents infinite loops where the 404 message has a missing placeholder.