Interface TranslationRegistry

    • 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

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      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