Package net.kyori.adventure.translation

Interface TranslationRegistry

All Superinterfaces:

Translator

public interface TranslationRegistry
extends Translator

A registry of translations. Used to register localized strings for translation keys. The registry can be submitted to the GlobalTranslator or can translate manually through translate(String, Locale).

The recommended way to register translations is through registerAll(Locale, ResourceBundle, boolean)

Since:

4.0.0

Field Summary

Fields

Modifier and Type	Field	Description
static java.util.regex.Pattern	SINGLE_QUOTE_PATTERN	A pattern which matches a single quote.

Method Summary

Modifier and Type	Method	Description
boolean	contains(@NotNull java.lang.String key)	Checks if any translations are explicitly registered for the specified key.
static @NotNull TranslationRegistry	create(Key name)	Creates a new standalone translation registry.
void	defaultLocale(@NotNull java.util.Locale locale)	Sets the default locale used by this registry.
void	register(@NotNull java.lang.String key, @NotNull java.util.Locale locale, @NotNull java.text.MessageFormat format)	Registers a translation.
default void	registerAll(@NotNull java.util.Locale locale, @NotNull java.nio.file.Path path, boolean escapeSingleQuotes)	Registers a resource bundle of translations.
default void	registerAll(@NotNull java.util.Locale locale, @NotNull java.util.Map<java.lang.String,java.text.MessageFormat> formats)	Registers a map of translations.
default void	registerAll(@NotNull java.util.Locale locale, @NotNull java.util.ResourceBundle bundle, boolean escapeSingleQuotes)	Registers a resource bundle of translations.
default void	registerAll(@NotNull java.util.Locale locale, @NotNull java.util.Set<java.lang.String> keys, java.util.function.Function<java.lang.String,java.text.MessageFormat> function)	Registers a resource bundle of translations.
@Nullable java.text.MessageFormat	translate(@NotNull java.lang.String key, @NotNull java.util.Locale locale)	Gets a message format from a key and locale.
void	unregister(@NotNull java.lang.String key)	Unregisters a translation key.

Methods inherited from interface net.kyori.adventure.translation.Translator

name

Field Detail

SINGLE_QUOTE_PATTERN

static final java.util.regex.Pattern SINGLE_QUOTE_PATTERN

A pattern which matches a single quote.

Since:

4.0.0

Method Detail

create

@NotNull
static @NotNull TranslationRegistry create(Key name)

Creates a new standalone translation registry.

Parameters:

name - the registry id

Returns:

a translation registry

Since:

4.0.0

contains

boolean contains(@NotNull
                 @NotNull java.lang.String key)

Checks if any translations are explicitly registered for the specified key.

Parameters:

key - a translation key

Returns:

whether the registry contains a value for the translation key

Since:

4.7.0

translate

@Nullable
@Nullable java.text.MessageFormat translate(@NotNull
                                            @NotNull java.lang.String key,
                                            @NotNull
                                            @NotNull java.util.Locale locale)

Gets a message format from a key and locale.

If a translation for locale is not found, we will then try locale without a country code, and then finally fallback to a default locale.

Specified by:

translate in interface Translator

Parameters:

locale - a locale

key - a translation key

Returns:

a message format or null to skip translation

Since:

4.0.0

defaultLocale

void defaultLocale(@NotNull
                   @NotNull java.util.Locale locale)

Sets the default locale used by this registry.

Parameters:

locale - the locale to use a default

Since:

4.0.0

register

void register(@NotNull
              @NotNull java.lang.String key,
              @NotNull
              @NotNull java.util.Locale locale,
              @NotNull
              @NotNull java.text.MessageFormat format)

Registers a translation.

   final TranslationRegistry registry;
   registry.register("example.hello", Locale.US, new MessageFormat("Hi, {0}. How are you?"));
 

Parameters:

key - a translation key

locale - a locale

format - a translation format

Throws:

java.lang.IllegalArgumentException - if the translation key is already exists

Since:

4.0.0

registerAll

default void registerAll(@NotNull
                         @NotNull java.util.Locale locale,
                         @NotNull
                         @NotNull java.util.Map<java.lang.String,java.text.MessageFormat> formats)

Registers a map of translations.

   final TranslationRegistry registry;
   final Map<String, MessageFormat> translations;

   translations.put("example.greeting", new MessageFormat("Greetings {0}. Doing ok?));
   translations.put("example.goodbye", new MessageFormat("Goodbye {0}. Have a nice day!));

   registry.registerAll(Locale.US, translations);
 

Parameters:

locale - a locale

formats - a map of translation keys to formats

Throws:

java.lang.IllegalArgumentException - if a translation key is already exists

Since:

4.0.0

See Also:

register(String, Locale, MessageFormat)

registerAll

default void registerAll(@NotNull
                         @NotNull java.util.Locale locale,
                         @NotNull
                         @NotNull java.nio.file.Path path,
                         boolean escapeSingleQuotes)

Registers a resource bundle of translations.

Parameters:

locale - a locale

path - a path to the resource bundle

escapeSingleQuotes - whether to escape single quotes

Throws:

java.lang.IllegalArgumentException - if a translation key is already exists

Since:

4.0.0

See Also:

registerAll(Locale, ResourceBundle, boolean)

registerAll

default void registerAll(@NotNull
                         @NotNull java.util.Locale locale,
                         @NotNull
                         @NotNull java.util.ResourceBundle bundle,
                         boolean escapeSingleQuotes)

Registers a resource bundle of translations.

It is highly recommended to create your bundle using UTF8ResourceBundleControl as your bundle control for UTF-8 support - for example:

   final ResourceBundle bundle = ResourceBundle.getBundle("my_bundle", Locale.GERMANY, UTF8ResourceBundleControl.get());
   registry.registerAll(Locale.GERMANY, bundle, false);
 

Parameters:

locale - a locale

bundle - a resource bundle

escapeSingleQuotes - whether to escape single quotes

Throws:

java.lang.IllegalArgumentException - if a translation key is already exists

Since:

4.0.0

See Also:

UTF8ResourceBundleControl

registerAll

default void registerAll(@NotNull
                         @NotNull java.util.Locale locale,
                         @NotNull
                         @NotNull java.util.Set<java.lang.String> keys,
                         java.util.function.Function<java.lang.String,java.text.MessageFormat> function)

Registers a resource bundle of translations.

Parameters:

locale - a locale

keys - the translation keys to register

function - a function to transform a key into a message format

Throws:

java.lang.IllegalArgumentException - if a translation key is already exists

Since:

4.0.0

unregister

void unregister(@NotNull
                @NotNull java.lang.String key)

Unregisters a translation key.

Parameters:

key - a translation key

Since:

4.0.0