Migrating from Triton v2 to v3

warning

Before proceeding, make sure to backup your Triton folder on all servers in case something goes wrong during the migration!

Changelog

Below are the changes that require your attention:

MySQL support for translations (💥 Breaking Change)
Better debugging tools (debug has been replaced with log-level)
Removed universal field for translations since it was redundant
Add feature that prevents players from typing placeholders in the chat (enabled by default)
players.yml has been renamed to players.json and it's now not used when using a non-local storage type
cache.json has changed syntax
messages.yml content has changed and it now has a blueish theme
/triton setlanguage for others has changed format (arguments have swapped)
Removed scoreboard translation
Removed all multilanguageplugin.* permissions

All other changes in this version can be found on Spigot or Polymart.

Downloading the new version

Follow the instructions in the installation guide.

Updating config files

The config files have changed substantially. I'd recommend updating them before proceeding with the migration guide.
Below is a copy of the default config for both Spigot and BungeeCord, with the changes highlighted.

Spigot config.yml

Alternatively, see the diff on GitHub.

spigot/plugins/Triton/config.yml
# This will be ignored if 'bungeecord' is enabled and local storage is being used.
# If using non-local storage, please make sure this matches what's on BungeeCord.
languages:
  # The language name. This will influence the language key in the translation files.
  # It's recommended to follow this syntax: xx_XX
  # It's also not recommended to change this after someone has joined your server,
  # as their language will reset to default.
  en_GB:
    # This is the encoded flag code to show up the banner.
    # To get a working code, you should visit https://www.needcoolshoes.com/banner and create your banner.
    # When you finish, you should notice that the link as changed. Just copy the code generated by it.
    # i.e. If the link is https://www.needcoolshoes.com/banner?=eapwplpnpmbzbj then the code will be eapwplpnpmbzbj
    flag: eapwplpnpmbzbj
    # The Minecraft code is the Minecraft language code. You can find a complete list here:
    # https://minecraft.gamepedia.com/Language
    minecraft-code: [en_GB]
    # This display name. This will be the language name in non-code version. For example, en_UK should be English (UK)
    # Feel free to use colours here!
    display-name: '&3English (UK)'
    # Use this to run commands on language change.
    # The commands must not start with a slash.
    # Prefix with the desired type. Available types: 'PLAYER', 'SERVER'
    # i. e. "PLAYER:say I'm using English now!"
    # Please uncomment the lines below to start using this feature.
    # Available variables:
    # %player% - Replaced with the player's name.
    # %uuid% - Replaced with the player's UUID (with dashes).
  #  commands:
  #      - 'SERVER:say %player% (%uuid%) has just changed their language!'
  pt_PT:
    flag: bacLlt
    minecraft-code: [pt_PT]
    display-name: '&3Portuguese (Portugal)'
  #  commands:
  #    - 'SERVER:say %player% (%uuid%) has just changed their language!'

# The main language is the fallback language. If some message is not found, it will try to get it from here before
# returning an error message.
# Also, if you delete any language, the players with that language will have their language changed to this.
main-language: en_GB

# When enabled, the commands inside each language will run when the player joins.
run-language-commands-on-join: false

# When enabled, the plugin will set the player's Triton language to their game language every time.
# By default, the plugin only does this when they join the server for the first time.
# It it recommended to leave this off for user experience reasons.
# Ignored when bungeecord is enabled.
force-client-locale-on-join: false

# Automatically reload the plugin (equivalent to /twin reload) every X seconds.
# Might be useful if you're editing the translations folder with symlinks or another program.
# Set to -1 to disable (default)
config-auto-refresh-interval: -1

# Enable this if you're using the plugin on BungeeCord.
# A restart of the server and BungeeCord might be required after changing this setting.
bungeecord: false

# To access TWIN, you need a special token.
# To get it, join our Discord server at https://triton.rexcantor64.com/discord or DM me on Spigot.
# If you've enabled "bungeecord" above, there is no need to put your token here. You just need it on your BungeeCord config.
twin-token: ''

# Determines how verbose the logging will be. A lower value means less verbose.
# 0 (default): Only errors and startup messages are logged to the console.
# 1: Also outputs details about config initialization and other relevant information (translation count, startup time, stack traces etc).
# 2: Also outputs information related to reading/writing files, as well as communication with BungeeCord and a database.
# 3: Logs EVERYTHING. Only recommended for debugging purposes. When enabled, every translation job will be logged to the console.
log-level: 0

# This section controls the storage location of player data and translations.
# If using a database, the tables/collections will be created automatically for you.
# You can use '/triton database upload' to upload the local translations to a remote storage.
# This MUST match what is on BungeeCord
storage:
  # Valid options: 'local', 'mysql', 'mongodb'
  type: 'local'
  # This should match the name of this server in BungeeCord's config.yml
  # Used to filter translations for this server only
  server-name: 'lobby'
  # The options below this are for non-local storage only
  host: 'localhost'
  port: 3306
  database: 'triton'
  username: 'root'
  password: ''
  table-prefix: 'triton_'

# Here you can enable and disable certain features of the plugin.
# Every section contains a "syntax-lang", "syntax-args" and "syntax-arg" field. This are used in the placeholders.
# If you change them, make sure to adjust accordingly in your plugins.
language-creation:
  chat:
    # Should the plugin check for placeholders in chat messages?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  actionbars:
    # Should the plugin check for placeholders in action bars?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  titles:
    # Should the plugin check for placeholders in titles and subtitles?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  guis:
    # Should the plugin check for placeholders in GUIs' titles?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  holograms:
    # Should the plugin check for placeholders in holograms (and/or entity display names)?
    # Normally the most recent plugins use armor stands to make the holograms, but if they don't, you can change it here.
    # Also, you can also translate other's entities name, like villagers. Add their entity type on the list below.
    # Full list: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html
    types:
      - ARMOR_STAND
    # When enabled, the list above is ignored and all entities' names are checked and translated.
    allow-all: false
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  kick:
    # Should the plugin check for placeholders in kick messages?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  tab:
    # Should the plugin check for placeholders in tab?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  items:
    # Should the plugin check for placeholders in items?
    enabled: true
    # When enabled, items in the player's own inventory will also be checked.
    # Items might permanently change names if the players are in creative mode.
    allow-in-inventory: false
    # Enable translation of books.
    # It is recommended to enable "allow-in-inventory" above if this is enabled.
    books: false
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  signs:
    # Should the plugin overlay the signs with the translations on languages.json?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  bossbars:
    # Should the plugin check for placeholders in bossbars? (1.9+)
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  motd:
    # Should the plugin check for placeholders in the MOTD?
    # This works by associating each IP with a language that changes when a player changes language.
    # When the IP is unknown, the default language is used.
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  # If any message contains a placeholder with the key defined in the field below, that message won't be sent to the players (console will still receive it).
  # Leave empty to disable this feature (it's disabled by default).
  # Example (assuming you have the default values on your config and you set disabled-line to 'disabled.line'):
  # If any message contains '[lang]disabled.line[/lang]' it won't be sent.
  disabled-line: ''
  # Translate messages that go through console to the default language.
  # For UX reasons, messages that contain disabled line placeholders aren't touched.
  # Changing this requires a full server restart.
  terminal: false
  # Should placeholders typed in chat by players be ignored?
  # Default is true
  prevent-placeholders-in-chat: true

Bungee config.yml

Alternatively, see the diff on GitHub.

bungee/plugins/Triton/config.yml
languages:
  # The language name. This will influence the language key in the translation files.
  # It's recommended to follow this syntax: xx_XX
  # It's also not recommended to change this after someone has joined your server,
  # as their language will reset to default.
  en_GB:
    # This is the encoded flag code to show up the banner.
    # To get a working code, you should visit https://www.needcoolshoes.com/banner and create your banner.
    # When you finish, you should notice that the link as changed. Just copy the code generated by it.
    # i.e. If the link is https://www.needcoolshoes.com/banner?=eapwplpnpmbzbj then the code will be eapwplpnpmbzbj
    flag: eapwplpnpmbzbj
    # The Minecraft code is the Minecraft language code. You can find a complete list here:
    # https://minecraft.gamepedia.com/Language
    minecraft-code: [en_GB]
    # This display name. This will be the language name in non-code version. For example, en_UK should be English (UK)
    # Feel free to use colours here!
    display-name: '&3English (UK)'
    # Use this to run commands on language change.
    # The commands must not start with a slash.
    # Prefix with the desired type. Available types: 'PLAYER', 'SERVER', 'BUNGEE', 'BUNGEE_PLAYER'.
    # i. e. "PLAYER:say I'm using English now!"
    # You can also limit the command to certain servers:
    # i. e. "BUNGEE:lobby,lobby-2,lobby-3:alert This will only run on 3 servers!"
    # NOTE: If a command you're using contains a ':' and you want it to be universal, do something like this:
    # i. e. "PLAYER::give @a minecraft:dirt"
    # Please uncomment the lines below to start using this feature.
    # Available variables:
    # %player% - Replaced with the player's name.
    # %uuid% - Replaced with the player's UUID (with dashes).
  #  commands:
  #    - 'SERVER:say %player% (%uuid%) has just changed their language!'
  pt_PT:
    flag: bacLlt
    minecraft-code: [pt_PT]
    display-name: '&3Portuguese (Portugal)'
  #  commands:
  #    - 'SERVER:say %player% (%uuid%) has just changed their language!'

# The main language is the fallback language. If some message is not found, it will try to get it from here before
# returning an error message.
# Also, if you delete any language, the players with that language will have their language changed to this.
main-language: en_GB

# When enabled, the commands inside each language will run when the player joins.
run-language-commands-on-join: false

# When enabled, the plugin will set the player's Triton language to their game language every time.
# By default, the plugin only does this when they join the server for the first time.
# It it recommended to leave this off for user experience reasons.
force-client-locale-on-join: false

# Automatically reload the plugin (equivalent to /twin reload) every X seconds.
# Might be useful if you're editing the translations folder with symlinks or another program.
# Set to -1 to disable (default)
config-auto-refresh-interval: -1

# To access TWIN, you need a special token.
# To get it, join our Discord server at https://triton.rexcantor64.com/discord or DM me on Spigot.
twin-token: ''

# Determines how verbose the logging will be. A lower value means less verbose.
# 0 (default): Only errors and startup messages are logged to the console.
# 1: Also outputs details about config initialization and other relevant information (translation count, startup time, etc).
# 2: Also outputs information related to reading/writing files, as well as communication with BungeeCord and a database.
# 3: Logs EVERYTHING. Only recommended for debugging purposes. When enabled, every translation job will be logged to the console.
log-level: 0

# This section controls the storage location of player data and translations.
# If using a database, the tables/collections will be created automatically for you.
# You can use '/triton database upload' to upload the local translations to a remote storage.
# The same settings MUST be placed on the Triton config for all Spigot servers under the same network
storage:
  # Valid options: 'local', 'mysql', 'mongodb'
  type: 'local'
  # The options below this are for non-local storage only
  host: 'localhost'
  port: 3306
  database: 'triton'
  username: 'root'
  password: ''
  table-prefix: 'triton_'

# Here you can enable and disable certain features of the plugin.
# Every section contains a "syntax-lang", "syntax-args" and "syntax-arg" field. This are used in the placeholders.
# If you change them, make sure to adjust accordingly in your plugins.
language-creation:
  chat:
    # Should the plugin check for placeholders in chat messages?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  actionbars:
    # Should the plugin check for placeholders in action bars?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  titles:
    # Should the plugin check for placeholders in titles and subtitles?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  kick:
    # Should the plugin check for placeholders in kick messages?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  tab:
    # Should the plugin check for placeholders in tab?
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  bossbars:
    # Should the plugin check for placeholders in bossbars? (1.9+)
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  motd:
    # Should the plugin check for placeholders in the MOTD?
    # This works by associating each IP with a language that changes when a player changes language.
    # When the IP is unknown, the default language is used.
    enabled: true
    syntax-lang: lang
    syntax-args: args
    syntax-arg: arg
  # If any message contains a placeholder with the key defined in the field below, that message won't be sent to the players (console will still receive it).
  # Leave empty to disable this feature (it's disabled by default).
  # Example (assuming you have the default values on your config and you set disabled-line to 'disabled.line'):
  # If any message contains '[lang]disabled.line[/lang]' it won't be sent.
  disabled-line: ''
  # Translate messages that go through console to the default language.
  # For UX reasons, messages that contain disabled line placeholders aren't touched.
  # Changing this requires a full server restart.
  terminal: false

Storage options

This is the most important change that you must perform before proceeding. Make sure to read the initial configuration guide if you're unsure how to configure it.

The database section has been renamed to storage. The guide linked above will help you go through the configuration.

Automatic Migration

Just like every major release of Triton until now, this version includes auto migration.
Due to the lack of major changes in the file format, Triton might have a hard time identifying that there is a need for migration.

tip

Triton starts the migration if it finds the players.yml file but it doesn't find the players.json file. This is important if you want to manually trigger the migration.
It is extremely important that you do not run the migration more than once, otherwise it might break your translations.

This is what the auto migration does:

Convert your players.yml to players.json
Convert cache.json (if it exists) to the new format
Replace all entries of universal: true in translations with blacklist: true and servers: [].

Upload local translation to a database

If you're using a database (e.g. MySQL), you must learn two new commands: /triton database upload and /triton database download.
They are two very destructive commands, so make sure you're the only one that has permissions (triton.database) to use them.

After starting your server and making sure all servers share the same storage settings, you must run /triton database upload to copy all the translations from the translations folder to the database.

danger

As I said, these commands are very destructive.
Running /triton database upload will delete ALL TRANSLATIONS that are in the database already.

Editing translations without TWIN

If you're using a database, editing the translations directly might be cumbersome.
Instead, you can use /triton database download to download the translations from the database into the translations folder.

Then you can simply edit them as you'd like and upload with /triton database upload as before.

danger

Just like the upload command, /triton database download can be very destructive. When executed, all .json files in the translations folder are deleted and replaced with the translations from the database.

Changes to `messages.yml`

The messages.yml file has updated translations and a new blueish color theme. You can find the diff on GitHub.

Changes to `/triton setlanguage`

This command previously was used as /triton setlanguage [player] <language>.
Now, as it should have been from the beginning, the new format is /triton setlanguage <language> [player].

If you're using this command on menus or something similar, please swap the arguments.

Removal of scoreboard translation

Scoreboard translation using Triton placeholders was deprecated since v2.5.1.
It has now been removed from the plugin completely.

Reasons for removal include poor and laggy implementation and visual glitches.

As an alternative (and recommended), use PlaceholderAPI from now on.

After Migration 🎉

Congrats, you've made it!
You should now be running Triton v3.0.0!

If you've encountered any issue during the migration process, please ask for help in our Discord server.

Below are some resources that might be useful:

Changelog​

Downloading the new version​

Updating config files​

Storage options​

Automatic Migration​

Upload local translation to a database​

Editing translations without TWIN​

Changes to messages.yml​

Changes to /triton setlanguage​

Removal of scoreboard translation​

After Migration 🎉​