Messages and languages
The texts of the app live in message files in lib/resources/: messages.properties for English, messages_ja.properties for Japanese, and so on. A widget reads a text in the app's current language with context.message, or with the typed getters of context.messages that the generator writes. The app's locales follow the files by themselves.
Why
Flutter's own localization needs ARB files, a code generator and a delegate per app. Here the texts are Spring's message files, the ones a Spring server uses too, so a team can share them, and the same MessageSource bean gives them to services (for an email, a notification) and to widgets.
Example
# lib/resources/messages.properties
basket.total=Total: {0}
basket.empty=Your basket is empty.
# lib/resources/messages_ja.properties
basket.total=合計:{0}
basket.empty=カゴは空です。
// By code, with arguments for {0}, {1}, ...
Text(context.message('basket.total', args: [total]));
// Typed, generated from the same files.
Text(context.messages.basket.total(total));
Text(context.messages.basket.empty);
context.message
context.message(code, args:, defaultMessage:) returns a text from the message files in the app's current language: the locale of Localizations, else the device's. args fill the {0}, {1}, ... placeholders.
A missing code throws a NoSuchMessageException, unless you pass defaultMessage: or set spring.messages.use-code-as-default-message=true (then the code itself is shown).
Typed messages: context.messages
The generator writes context.messages from the same files into lib/spring_gen/messages.spring.keys.dart (import spring_gen/main.spring.dart):
- a getter for a message without arguments (
context.messages.basket.empty); - a method for one with
{0},{1}, ... (Object?parameters, formatted by the same message source, in the current language).
A key missing in one language is a build warning; different argument counts in two languages fail the build. A renamed key no longer compiles. context.message('...') stays for keys built at run time. See Typed keys.
The app's locales
The app supports the languages it has texts for: messages.properties counts as English, and each messages_<locale>.properties adds its locale (messages_ja adds ja, messages_pt_BR adds pt_BR). spring.flutter.app.locales lists them instead when set:
spring:
flutter:
app:
locales: en, ja # one comma-separated value, not a YAML list
Flutter's own translations (the texts of its widgets, in every language) are added for the app type. See The app widget.
The properties
The message files are read by the application's MessageSource, set with Spring Boot's keys:
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.messages.basename |
comma-separated names | messages |
The base names of the message files in lib/resources/. In a Flutter app write one comma-separated value with / as the separator (i18n/messages,i18n/errors), so the starter finds the locales of those files |
spring.messages.use-code-as-default-message |
bool | false |
A missing code gives the code itself instead of an error |
spring.messages.fallback-to-system-locale |
bool | true |
When a language has no file, try the device's language before the file without a language |
spring.messages.always-use-message-format |
bool | false |
Apply the {0} formatting rules (and its quoting) to messages without arguments too |
spring.messages.encoding |
charset | UTF-8 |
The encoding of the files; an unknown one fails the start |
spring.messages.cache-duration |
duration (a plain number is seconds) | kept for ever | How long a loaded file is kept before it is read again |
spring.messages.default-locale |
locale | none | A locale tried before the device's (not in Spring Boot) |
spring.messages.common-messages |
list of locations | none | Texts shared by every language; a later file wins |
See Messages in spring_core_dart for the formats and the MessageSource itself.
Known limits
spring.flutter.app.localesandspring.messages.basenameare read as single values: write them comma-separated, also in YAML. A YAML list is not seen: the locales then come from the message files, and the starter looks for the locales ofmessages*.propertieseven when theMessageSourcereads other files.- Write the basename with
/(i18n/messages). TheMessageSourcealso accepts dots (i18n.messages), but the starter then finds no locale files.
Fonts for other scripts on the web
On the web, Flutter downloads a font for Japanese, Chinese or emoji the first time it lays such text out, and the first switch of the language stutters. Turn on the text warm-up to download them while the splash shows (see The splash and the start).