Package valorless.valorlessutils.color

Class Lang

java.lang.Object

valorless.valorlessutils.color.Lang

public class Lang
extends Object

Language/message utility for plugin text formatting and lookup.

This class can:

• load translatable strings from lang.yml,
• resolve PlaceholderAPI placeholders when available,
• apply/remove legacy color formatting and hex colors,
• convert legacy formatted strings to MiniMessage.

Constructor Summary

Constructors

Constructor	Description
Lang(org.bukkit.plugin.java.JavaPlugin plugin)	Creates a language helper for a plugin.

Method Summary

Modifier and Type	Method	Description
String	convertToMiniMessage(String text)	Converts legacy color codes (invalid input: '&' or §) and hex color sequences into MiniMessage format.
String	get(String key, org.bukkit.entity.Player... player)	Retrieves a localized string from lang.yml by key, with optional player context.
List<String>	getList(String key, org.bukkit.entity.Player... player)	Retrieves a list of localized strings from lang.yml by key, with optional player context.
String	getRaw(String key)	Retrieves a raw localized string from lang.yml by key, without any parsing.
String	hex(String message)	Converts hex color codes (#RRGGBB) into legacy color sequences understood by Bukkit, then applies ChatColor.translateAlternateColorCodes(char, String).
String	parse(String text)	Parses a message by applying placeholders and color formatting without a player context.
String	parse(String text, boolean minimessage)	Parses a message and optionally converts it to MiniMessage format.
String	parse(String text, org.bukkit.OfflinePlayer player)	Parses a message by applying placeholders and color formatting.
String	parse(String text, org.bukkit.OfflinePlayer player, boolean minimessage)	Parses a message and optionally converts it to MiniMessage format.
String	parsePlaceholderAPI(String text, org.bukkit.OfflinePlayer player)	Resolves PlaceholderAPI placeholders when the hook is available.
String	parseWithName(String text, String playerName)	Parses a message by applying placeholders and color formatting, replacing %player% with the provided name.
String	removeColorFormatting(String text)	Removes all color and formatting codes, including hex sequences, from the text.
String	removeHex(String text)	Removes hex color sequences of the form §x§R§R§G§G§B§B from the text.
String	stripMiniMessageFormatting(String text)	Removes MiniMessage tags from text while preserving the visible content.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Lang

public Lang(org.bukkit.plugin.java.JavaPlugin plugin)

Creates a language helper for a plugin.

If a bundled lang.yml resource exists, it is loaded via Config. Otherwise a warning is logged and language lookup methods (get(String, Player...), getList(String, Player...), getRaw(String)) are unavailable.

Parameters:

plugin - owning plugin instance

Method Details

parse

public String parse(String text,
 @Nullable
 org.bukkit.OfflinePlayer player)

Parses a message by applying placeholders and color formatting.

Operations performed (in order):

1. PlaceholderAPI resolution when available (using the provided player, or a fallback)
2. Convert hex colors of the form #RRGGBB to Minecraft color sequences
3. Translate legacy color codes (& to §)
4. Unescape newlines ("\\n" to newline)
5. Replace %player% with the player's name when a player is provided

If player is null, an arbitrary offline player is used as a best-effort fallback for PlaceholderAPI parsing; if that fails, placeholders are resolved with null.

Parameters:

text - the raw message to parse; if null/empty, returns as-is

player - the player context for placeholder resolution; may be null

Returns:

the formatted and placeholder-resolved message

parseWithName

public String parseWithName(String text,
 String playerName)

Parses a message by applying placeholders and color formatting, replacing %player% with the provided name.

This method is similar to parse(String, OfflinePlayer), but instead of using an OfflinePlayer for placeholder resolution, it directly replaces the %player% token with the given playerName string. PlaceholderAPI parsing is still performed with a null player context. This is useful when you want to format a message with a specific player name without needing an actual player object.

Parameters:

text - the raw message to parse; if null/empty, returns as-is

playerName - the player name to replace %player% with; may be null

Returns:

the formatted message with %player% replaced by playerName

parse

public String parse(String text)

Parses a message by applying placeholders and color formatting without a player context.

This is a convenience method that calls parse(String, OfflinePlayer) with null.

Parameters:

text - the raw message to parse

Returns:

the formatted message

parse

public String parse(String text,
 boolean minimessage)

Parses a message and optionally converts it to MiniMessage format.

If minimessage is true, the result of parse(String, OfflinePlayer) is further processed by convertToMiniMessage(String) to convert legacy color codes and hex sequences into MiniMessage tags. If minimessage is false, this method simply delegates to parse(String, OfflinePlayer) with a null player context.

Parameters:

text - the raw message to parse

minimessage - whether to convert the parsed message to MiniMessage format

Returns:

the formatted message, optionally converted to MiniMessage

parse

public String parse(String text,
 org.bukkit.OfflinePlayer player,
 boolean minimessage)

Parses a message and optionally converts it to MiniMessage format.

This overload currently behaves the same as parse(String, boolean) and parses with a null player context.

Parameters:

text - the raw message to parse

player - currently ignored

minimessage - whether to convert parsed output to MiniMessage

Returns:

the parsed message, optionally converted to MiniMessage

get

public String get(String key,
 org.bukkit.entity.Player... player)

Retrieves a localized string from lang.yml by key, with optional player context.

If the key is missing from the configuration, logs an error and returns "§4error". When a player is provided, player-specific placeholders can be resolved. If lang.yml was not bundled and could not be loaded, this method is unavailable.

Parameters:

key - the lookup key in lang.yml

player - optional player context for placeholder resolution

Returns:

the configured value with parsing applied, or "§4error" if the key doesn't exist

getList

public List<String> getList(String key,
 org.bukkit.entity.Player... player)

Retrieves a list of localized strings from lang.yml by key, with optional player context.

If the key is missing from the configuration, logs an error and returns a list containing "§4error". When a player is provided, player-specific placeholders can be resolved in each line. If lang.yml was not bundled and could not be loaded, this method is unavailable.

Parameters:

key - the lookup key in lang.yml

player - optional player context for placeholder resolution

Returns:

the configured list of values with parsing applied, or a list containing "§4error" if the key doesn't exist

getRaw

public String getRaw(String key)

Retrieves a raw localized string from lang.yml by key, without any parsing.

Logs an error and returns a visible error token ("§4error") if the key is missing. If lang.yml was not bundled and could not be loaded, this method is unavailable.

Parameters:

key - the lookup key in lang.yml

Returns:

the configured value as-is

hex

public String hex(String message)

Converts hex color codes (#RRGGBB) into legacy color sequences understood by Bukkit, then applies ChatColor.translateAlternateColorCodes(char, String).

Parameters:

message - the message possibly containing hex color codes

Returns:

the message with hex and legacy color codes translated

parsePlaceholderAPI

public String parsePlaceholderAPI(String text,
 org.bukkit.OfflinePlayer player)

Resolves PlaceholderAPI placeholders when the hook is available.

Curly braces are converted to percent tokens before delegation, e.g. {foo_bar} becomes %foo_bar%.

Parameters:

text - the text possibly containing PlaceholderAPI placeholders

player - the player context used for placeholder resolution; may be null

Returns:

the text with placeholders resolved, or the original text on failure/not hooked

removeColorFormatting

public String removeColorFormatting(String text)

Removes all color and formatting codes, including hex sequences, from the text.

Parameters:

text - the text to sanitize

Returns:

the text without any § formatting codes

removeHex

public String removeHex(String text)

Removes hex color sequences of the form §x§R§R§G§G§B§B from the text.

Parameters:

text - the text to sanitize

Returns:

the text without any §x hex color sequences

convertToMiniMessage

public String convertToMiniMessage(String text)

Converts legacy color codes (invalid input: '&' or §) and hex color sequences into MiniMessage format.

This allows for better compatibility with MiniMessage-based APIs while preserving the original formatting intent. Hex colors are converted to invalid input: '<'#RRGGBB> tags, and legacy codes are converted to their corresponding MiniMessage tags (e.g. invalid input: '&c' to ). Color codes reset previous formatting as per legacy behavior.

Parameters:

text - the text containing legacy color codes and hex sequences

Returns:

the text converted to MiniMessage format

stripMiniMessageFormatting

public String stripMiniMessageFormatting(String text)

Removes MiniMessage tags from text while preserving the visible content.

Examples:

• <red>Hello</red> -> Hello
• <gradient:red:blue>Hi</gradient> -> Hi
• \\<red> -> <red>

Escaped angle brackets (\< and \>) are unescaped and kept as literal characters. If a < has no closing >, it is treated as normal text.

Parameters:

text - the text that may contain MiniMessage tags

Returns:

the input text with MiniMessage tags removed