
# 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

```properties
# lib/resources/messages.properties
basket.total=Total: {0}
basket.empty=Your basket is empty.
```

```properties
# lib/resources/messages_ja.properties
basket.total=合計：{0}
basket.empty=カゴは空です。
```

```dart
// 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](../spring-core-dart-generator/flutter/typed-keys.md).

## 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:

```yaml
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](app-widget.md#locales).

## 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](../spring-core-dart/messages/index.md) for the formats and the `MessageSource` itself.

## Known limits

- `spring.flutter.app.locales` and `spring.messages.basename` are 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 of `messages*.properties` even when the `MessageSource` reads other files.
- Write the basename with `/` (`i18n/messages`). The `MessageSource` also 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](splash.md#fonts-for-the-apps-text)).

## See also

- [The app widget](app-widget.md)
- [Messages in spring_core_dart](../spring-core-dart/messages/index.md)
- [Typed keys](../spring-core-dart-generator/flutter/typed-keys.md)
