Audio & content
Localization
Translate your game with a LocalizationManager on engine.context.localization: string files per locale, namespaces, fallbacks, plurals, selects and widgets that follow the locale.
A LocalizationManager holds your string tables and the current locale. Set it as engine.context.localization and every GameWidget showing the engine provides it to the widgets drawn over the game, and the dialogue system can use the same strings.
String files
Strings are JSON files, one per locale (and per namespace, if you use them). Keys can be flat or nested; nested keys are joined with dots, so {"ui": {"back": "Back"}} gives the key ui.back. List the folder under flutter: assets:.
{
"ui": {
"start_game": "Start game",
"back": "Back"
},
"hud.greeting": "Welcome back, {name}!",
"hud.coins": "{count, plural, =0{No coins} =1{One coin} other{{count} coins}}",
"hud.arrived": "{who, select, male{He arrived} female{She arrived} other{They arrived}}"
}Set up the manager
import 'package:flutter/foundation.dart' show debugPrint;
import 'package:flutter/widgets.dart' show Locale;
import 'package:just_game_engine/just_game_engine.dart';
Future<void> setUpLocalization(Engine engine) async {
final l10n = LocalizationManager(); // falls back to English
await l10n.loadAll(
const [Locale('en'), Locale('fr')],
'assets/l10n/ui_{locale}.json',
ns: 'ui',
);
l10n.setLocale(const Locale('fr'));
engine.context.localization = l10n; // before building the GameWidget
debugPrint(l10n.t('ui.back'));
debugPrint(l10n.t('hud.coins', args: {'count': 3}));
debugPrint(l10n.tr('hud.greeting', {'name': 'Aria'}));
}load(locale, path, ns: ...)loads one file;loadAll(locales, template, ns: ...)loads one per locale, replacing{locale}with the locale's tag (en,fr_CA,zh_Hans). A missing file is skipped quietly; a file that is there but malformed is logged.registerMap(locale, strings)andregister(locale, table)add strings from code, for tests or downloaded content.t(key, args: ..., locale: ..., ns: ...)looks a key up;tr(key, args)is the short form.has(key)andraw(key)read without filling anything in.setLocale(locale)switches language and notifieslocaleChanged, a signal the widgets below listen to.
Namespaces
A namespace keeps one area's strings in tables of their own: ui for menus, game for gameplay, dialogue for lines (LocalizationManager.dialogueNamespace). Without ns: strings go to LocalizationManager.defaultNamespace.
A namespace does not prefix keys. t('ui.back') searches every namespace, the default one first and then the others in the order they were loaded; t('ui.back', ns: 'ui') searches only ui. Files loaded for the same locale and namespace merge, and a key in a later file replaces the same key from an earlier one.
Fallbacks
For a key looked up in fr_CA, the manager tries the fr_CA tables, then fr, then the fallback locale (en unless you pass LocalizationManager(fallbackLocale: ...)), and finally returns the key itself, so missing strings are obvious on screen. A locale with a script keeps its own tables: zh_Hans_CN falls back to zh_Hans, then zh, and its file is named like ui_zh_Hans.json.
Variables, plurals and selects
{name} is replaced by the name argument. Two ICU-style forms choose text by an argument:
{count, plural, =0{...} =1{...} one{...} other{...}}: an exact=Nwins, thenonefor exactly 1, thenother. A count with a fraction matches only an=Nequal to it, so 1.5 takesother. There are nofewormanycategories.{who, select, male{...} female{...} other{...}}: the branch named by the argument's value, elseother.
Variables inside a branch are filled in too, as in other{{count} coins}. Forms are resolved one level deep: a plural inside a plural is not.
In widgets
The widgets are in package:just_game_engine/widgets.dart. Under a GameWidget they find the engine's manager themselves; elsewhere, wrap your widgets in LocalizationScope(manager: l10n, child: ...).
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';
import 'package:just_game_engine/widgets.dart';
class MainMenu extends StatelessWidget {
const MainMenu({super.key});
@override
Widget build(BuildContext context) => Column(
mainAxisSize: MainAxisSize.min,
children: [
const LocalizedText('ui.start_game'),
LocalizationBuilder(
builder: (context, l10n) =>
Text(l10n.t('hud.coins', args: {'count': 3})),
),
const LocaleSelector(
locales: [Locale('en'), Locale('fr')],
labels: {'en': 'English', 'fr': 'Français'},
),
],
);
}LocalizedText(key, args: ..., ns: ..., style: ...)is aTextthat rebuilds when the locale changes.LocalizationBuilderrebuilds its subtree on every locale change and hands you the manager.LocaleSelectorshows a tappable label for each locale and switches to it.context.t(key)andcontext.tr(key, args)(theBuildContextLocalizationextension) look a key up in the nearest scope. They do not rebuild when the locale changes, so use them inside aLocalizationBuilder.LocalizationScope.of(context)returns the manager itself.
Strings resolved once stay as they were when the locale changes: for example, SubtitleTrack.localized resolves its cues when it is made. See Dialogue & subtitles.