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 Details

    • SINGLE_QUOTE_PATTERN

      static final Pattern SINGLE_QUOTE_PATTERN
      A pattern which matches a single quote.
      Since:
      4.0.0
  • Method Details

    • create

      static @NonNull TranslationRegistry create​(net.kyori.adventure.key.Key name)
      Creates a new standalone translation registry.
      Returns:
      a translation registry
      Since:
      4.0.0
    • contains

      boolean contains​(@NonNull 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 MessageFormat translate​(@NonNull String key, @NonNull 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​(@NonNull 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​(@NonNull String key, @NonNull Locale locale, @NonNull 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:
      IllegalArgumentException - if the translation key is already exists
      Since:
      4.0.0
    • registerAll

      default void registerAll​(@NonNull Locale locale, @NonNull Map<String,​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:
      IllegalArgumentException - if a translation key is already exists
      Since:
      4.0.0
      See Also:
      register(String, Locale, MessageFormat)
    • registerAll

      default void registerAll​(@NonNull Locale locale, @NonNull 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:
      IllegalArgumentException - if a translation key is already exists
      Since:
      4.0.0
      See Also:
      registerAll(Locale, ResourceBundle, boolean)
    • registerAll

      default void registerAll​(@NonNull Locale locale, @NonNull 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:
      IllegalArgumentException - if a translation key is already exists
      Since:
      4.0.0
      See Also:
      UTF8ResourceBundleControl
    • registerAll

      default void registerAll​(@NonNull Locale locale, @NonNull Set<String> keys, Function<String,​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:
      IllegalArgumentException - if a translation key is already exists
      Since:
      4.0.0
    • unregister

      void unregister​(@NonNull String key)
      Unregisters a translation key.
      Parameters:
      key - a translation key
      Since:
      4.0.0