Interface I18n

public interface I18n
A registry for translations in different languages. One language is selected as the default language and used to translate all translation requests. Translations can take a variable number of arguments, but can also be fixed which means that they don't take any argument at all. How translations are loaded and messages are formatted is the responsibility of a TranslationProvider.
Since:
4.0

  • Method Details

    • i18n

      @NonNull static @NonNull I18n i18n()
      Get the current default implementation of this translator interface from the service registry. Where possible injection should be preferred over using this method.
      Returns:
      the current default implementation of this translator interface from the service registry.

    • selectedLanguage

      @NonNull @NonNull Locale selectedLanguage()
      Get the current selected language. If no language was selected specifically, the en-US locale is returned.
      Returns:
      the current selected language.

    • selectLanguage

      void selectLanguage(@NonNull @NonNull Locale language)
      Sets the given locale as the current selected language. Future translations calls will use translations from the given language. This method does no checks if translations for the given language are present.
      Parameters:
      language - the language to set as the current selected language.
      Throws:
      NullPointerException - if the given language is null.

    • availableLanguages

      @NonNull @NonNull @UnmodifiableView Collection<Locale> availableLanguages()
      Get a view of the locales for which a translation provider was registered.
      Returns:
      a view of the locales for which a translation provider was registered.

    • translate

      @NonNull @NonNull String translate(@NonNull @NonNull String key, Object... args)
      Returns the translated message for the given translation key based on the current selected language, optionally inserting the given arguments into the message. If no translation can be provided for the key in the selected language, a fallback message is returned instead.
      Parameters:
      key - the key of the translation to get.
      args - the arguments which can optionally be embedded into the translation.
      Returns:
      the translated message for the given key in the current language.
      Throws:
      NullPointerException - if the given translation key or arguments array is null.
      IllegalArgumentException - if the translation cannot be formatted with the given arguments.

    • registerProvider

      void registerProvider(@NonNull @NonNull Locale language, @NonNull @NonNull TranslationProvider provider)
      Registers a translation provider into this registry. Translation providers are called in registration order when a translation is requested, returning the translated message from the first provider that can provide it. The caller of this method is marked as the owner of the translation provider. This information will be used when a request is made to unregister all translation providers by their class loader.
      Parameters:
      language - the language for which the provider should be registered.
      provider - the provider to register into this registry for the given language.
      Throws:
      NullPointerException - if the given language or provider is null.
      IllegalCallerException - if the caller of the method cannot be resolved.

    • unregisterProvider

      void unregisterProvider(@NonNull @NonNull Locale language, @NonNull @NonNull TranslationProvider provider)
      Unregisters the given provider for the given language from this registry.
      Parameters:
      language - the language for which the provider was registered.
      provider - the provider to unregister from this registry.
      Throws:
      NullPointerException - if the given language or provider is null.

    • unregisterProviders

      void unregisterProviders(@NonNull @NonNull ClassLoader classLoader)
      Unregisters all providers from this registry whose owner class was loaded by the given class loader.
      Parameters:
      classLoader - the class loader of the owner of the providers to be unregistered.
      Throws:
      NullPointerException - if the given class loader is null.