ReloadableResourceBundleMessageSource class

A message source that reads its texts from .properties files, one file per language, and can re-read them when they change.

This is the usual message source. Spring Boot creates one from lib/resources/messages*.properties and the spring.messages.* properties; without Spring Boot, declare it as the messageSource bean.

For the basename i18n/messages and the locale ru_RU, the files i18n/messages_ru_RU.properties, i18n/messages_ru.properties and i18n/messages.properties are consulted. Basenames are locations for the resourceLoader (file:, classpath:, plain paths, custom protocols). The lookup goes basename by basename, as in Spring: every locale file of the first basename (requested locale, fallbackLocale, base file) before the second basename, so messages.properties wins over errors_de.properties. Resources that cannot be read synchronously (such as Flutter assets) must be loaded with preload first.

// Two bundles, re-read at most every 10 seconds, English by default.
@Configuration()
class I18nConfig {
  @Bean()
  MessageSource messageSource() => ReloadableResourceBundleMessageSource(
    basenames: ['file:i18n/messages', 'file:i18n/errors'],
    cacheSeconds: 10,
  )..defaultLocale = 'en';
}

// i18n/messages_de.properties:  greeting=Hallo {0}
context.getMessage('greeting', args: ['Ada'], locale: 'de_AT');

Spring (Java):

@Bean
MessageSource messageSource() {
  var source = new ReloadableResourceBundleMessageSource();
  source.setBasenames("file:i18n/messages", "file:i18n/errors");
  source.setCacheSeconds(10);
  source.setDefaultLocale(Locale.ENGLISH);
  return source;
}

Files are read in defaultEncoding, UTF-8 by default. Reloading (cacheSeconds) re-reads files that can be read synchronously: for file system resources the last modification time is compared, other resources are re-read on every check, and preloaded (async-only) resources are only replaced by another preload. Unlike Spring's, it does not receive the context's resource loader by itself: pass resourceLoader when the basenames use a custom protocol.

Inheritance

Constructors

ReloadableResourceBundleMessageSource({List<String> basenames = const [], ResourceLoader? resourceLoader, int cacheSeconds = -1, bool fallbackToSystemLocale = true})
Creates a source for basenames, consulted in that order.

Properties

alwaysUseMessageFormat ↔ bool
Whether messages without arguments are formatted too, so that their quotes follow MessageFormat rules ('' becomes '); false by default, which returns them as written. When it is true, an invalid pattern throws a FormatException instead of being returned as is.
getter/setter pairinherited
basenames → List<String>
The basenames in lookup order; an earlier one wins.
no setter
cacheMillis ↔ int
cacheSeconds in milliseconds, for intervals below a second (Spring's setCacheMillis; Spring Boot's spring.messages.cache-duration=500ms sets it).
getter/setter pair
cacheSeconds ↔ int
How long loaded files are kept before they are checked again, so that edited translations show without a restart: -1 (the default) keeps them forever; 0 checks the files on every lookup; a positive value checks them at most every cacheSeconds seconds. A file system file is re-read when its modification time changed; other resources are re-read on every check. Stored as cacheMillis; Spring's setCacheSeconds.
getter/setter pair
commonMessages ↔ Map<String, String>?
Messages that are the same in every language, by code; tried after all locales and before the parent.
getter/setter pairinherited
defaultEncoding ↔ Encoding
The charset the files are read in; UTF-8 by default. Spring's setDefaultEncoding, Boot's spring.messages.encoding.
getter/setter pair
defaultLocale ↔ String
The locale tried after the requested one (Spring's default locale), for example the language most texts are written in; empty means none (see fallbackLocale).
getter/setter pairinherited
fallbackLocale → String
The locale tried when the requested one has no message ('' for none): defaultLocale here. ReloadableResourceBundleMessageSource uses the system locale when there is no default locale, as Spring's AbstractResourceBasedMessageSource.getDefaultLocale().
no setteroverride
fallbackToSystemLocale ↔ bool
Whether a lookup falls back to the machine's locale (Locales.systemLocale) when the requested locale has no message and no defaultLocale is set; true by default. Set it to false so that a server answers the same whatever machine it runs on. A defaultLocale is used either way (Spring's setFallbackToSystemLocale).
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
parentMessageSource ↔ MessageSource?
The source asked for codes this one does not have; null for none.
getter/setter pairinherited
resourceLoader → ResourceLoader
Finds the files of the basenames; give the context (or a loader with a ProtocolResolver) to read from custom locations such as Flutter assets.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
useCodeAsDefaultMessage ↔ bool
Whether an unknown code is returned as the message instead of throwing a NoSuchMessageException; false by default. Handy while translations are incomplete: the screen shows the code.
getter/setter pairinherited

Methods

addBasenames(List<String> basenames) → void
Adds basenames after the existing ones, for example a library's own messages.
clearCache() → void
Forgets all loaded files, including preloaded ones, so that the next lookups read them again.
formatMessage(String pattern, List<Object?> args, [String? locale]) → String
Fills args into pattern with MessageFormat; without arguments (and with alwaysUseMessageFormat off) returns pattern as it is, like Spring.
inherited
getMessage(String code, {List<Object?> args = const [], String? defaultMessage, String? locale}) → String
The text for code in locale, with args filled into its {0}, {1}, ... placeholders.
inherited
getMessageFromResolvable(MessageSourceResolvable resolvable, {String? locale}) → String
The text for the first code of resolvable found in locale, with its arguments filled in; else its default message; else a NoSuchMessageException. Use it to show validation errors and other messages described by codes.
inherited
getMessageInternal(String code, List<Object?> args, String? locale) → String?
The formatted message for code from this source, its common messages or its parent; null when none has it. Unlike getMessage, it neither throws nor uses a default message.
inherited
localeChain(String? locale) → List<String>
The locales tried for locale: its candidates, then those of fallbackLocale, ending with '' (the base).
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
preload(List<String> locales) → Future<void>
Reads every file for locales (with their fallbacks and the base file) asynchronously and keeps them.
renderDefaultMessage(String defaultMessage, List<Object?> args, String? locale) → String
Formats a default message with args, resolving resolvable arguments first.
inherited
resolveArguments(List<Object?> args, String? locale) → List<Object?>
Replaces each MessageSourceResolvable in args by its message in locale; other arguments stay as they are.
inherited
resolveCode(String code, String locale) → String?
The unformatted message for code in exactly locale ('' for the base), or null. This is the one method a subclass must write; the fallbacks to other locales happen around it. locale is already normalized (see Locales.normalize).
override
resolveCodeInLocales(String code, List<String> locales) → String?
The unformatted message for code in the first of locales (most specific first, ending with '') that has one, or null.
override
toString() → String
A string representation of this object.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited