fespalier-i18n
Translated texts in a fespalier app with fespalier_tolgee (since 0.10.0) — the language from the URL ($lang enum segments and route.dart paths spellings) through TranslationScope.routerConfig on Mater
SKILL.mdskills/fespalier-i18n/SKILL.md
GitHubfespalier-i18n
Verified against fespalier
589cf391(2026-10-08), release v0.13.0. These skills ship in the fespalier repository, and CI checks them against its code on every change. Version-sensitive claims say the release they became true in; if your app pins another fespalier, trust that release's code over this page. See Versions.
Since 0.10.0. package:fespalier_tolgee gives an app translated texts that show at once, keep working offline and
can be updated without a release: the texts bundled in the app are the floor, Tolgee's Content
Delivery (or a TranslationSource you write) brings fresh ones, and the language comes from the URL. It adds no
file kind, no fespalier: key and no fsp command, and app.g.dart is the same bytes. It is not the tolgee
SDK: that one imports dart:io (no web), keeps the locale in a static singleton, can put the network before runApp,
and runs in-context editing on the production key. A release that predates 0.10.0 has no such package.
Install
# pubspec.yaml: the same url and the same ref as fespalier, or pub refuses to resolve
dependencies:
fespalier:
git:
url: https://github.com/fespalier/fespalier
path: packages/fespalier
ref: <the tag of your fespalier>
fespalier_tolgee:
git:
url: https://github.com/fespalier/fespalier
path: packages/fespalier_tolgee
ref: <the same tag>
flutter_localizations:
sdk: flutter
flutter:
assets:
- assets/i18n/
(A fragment: pub resolves the pair only at a release tag that contains the package, 0.10.0 or later. Write ref: v…
with a real tag in an app, but never in these pages, where cli/tests/versions.rs would read it as fespalier's own
version. The package's own
install block is the
one release-please keeps current.) For a cache that survives restarts add fespalier_storage and use its
PrefsDataStorage as dataCacheStorage (see fespalier-data (its storage-backends.md page)).
The shape of it
One enum for the languages, a setup in startup(), an app that gives MaterialApp.router the scope's router
config, and pages that ask for the language by its enum.
// lib/lang.dart
enum Lang { en, fr, de }
// lib/app/startup.dart
import 'package:fespalier/startup.dart';
import 'package:fespalier_tolgee/fespalier_tolgee.dart';
import 'package:my_app/lang.dart';
const _cdn = String.fromEnvironment('TOLGEE_CDN_URL'); // public, not a secret
Future<List<Override>> startup() async => [
translationsConfig.overrideWithValue(
Translations(
// Local assets only: assets/i18n/en.arb, fr.arb, de.arb. A missing file throws, and splash.dart offers the retry.
bundled: await BundledTranslations.load(locales: Lang.values.map((l) => l.name)),
baseLocale: 'en',
remote: _cdn.isEmpty ? null : TolgeeCdn(Uri.parse(_cdn)),
),
),
];
// lib/app/app.dart
import 'package:fespalier/fespalier.dart';
import 'package:fespalier_tolgee/fespalier_tolgee.dart';
import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
class App extends ConsumerWidget {
const App({super.key, required this.router});
final GoRouter router;
@override
Widget build(BuildContext context, WidgetRef ref) => MaterialApp.router(
routerConfig: TranslationScope.routerConfig(router, localeOf: localeSegment()),
supportedLocales: ref.watch(translationsConfig).supportedLocales.map(localeFromTag),
localizationsDelegates: GlobalMaterialLocalizations.delegates,
);
}
// lib/app/$lang/products/page.dart
// -> /en/products, /fr/products, /de/products
import 'package:fespalier_tolgee/fespalier_tolgee.dart';
import 'package:flutter/material.dart';
import 'package:my_app/lang.dart';
class ProductsPage extends StatelessWidget {
const ProductsPage({super.key, required this.lang});
final Lang lang; // asking for it is what types the segment as the enum: /xx/products is not found
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const TrText('products.title')),
body: Center(child: Text(context.tr('product.stock', {'count': 3}))), // {count, plural, ...}
);
}
# pubspec.yaml dependencies
flutter_localizations:
sdk: flutter
The catalog behind it, one file per language (a fragment, not built):
// assets/i18n/fr.arb
{
"@@locale": "fr",
"products.title": "Produits",
"product.stock": "{count, plural, =0 {Épuisé} one {# en stock} other {# en stock}}"
}
Golden rules
- Give
MaterialApp.routerrouterConfig: TranslationScope.routerConfig(router, localeOf: ...), never the router itself. The config wraps go_router's root Navigator in the scope, so the first frame is already in the route's language and a dialog on the root navigator is under it too. localizationsDelegates: GlobalMaterialLocalizations.delegatesis required (andflutter_localizationsin the pubspec). Without it a route in a language the app has noMaterialLocalizationsfor makes anAppBaror aBackButtonthrowNo MaterialLocalizations found.- The locale comes from the route. A
data.darttakesrequired Lang lang; there is no global locale and nosetLocale. A language menu navigates (relocate, below). - Bundled texts are the floor. Every locale you list is read from
assets/i18n/before the first frame; a missing asset makesstartup()throw (sosplash.dartoffers the retry), and the base locale must be bundled. - Never an API key in a build.
TolgeeCdnhas no parameter for one. The only key is the in-context editor's, passed with--dart-define-from-file=tolgee.local.json(gitignored) to a debug run; release builds pass onlyTOLGEE_CDN_URL. - A test passes its own
app:.pumpRouter's default app is a bareMaterialApp.routerwith no scope, andcontext.trthere throws.references/testing.md.
Traps
- No
translationsConfigoverride means every key renders as itself, silently (Translations.none). Raw keys on screen: the override is missing (a test does not runstartup()), or the key is a typo;Translator.originOf(key)says which link answered, orTranslationOrigin.missing. - The enum segment only takes effect if some file asks for
required Lang lang. Otherwise$langis aStringand/xx/productsmatches. A tag likept-BRcannot be an enum name: use aStringsegment, which the scope resolves against what you bundled (pt-BRtopt). - Spellings alone do not give the canonical path a locale. With
const paths = {'fr': 'produits'}and no$langfolder,/productssays nothing: the locale is then the previous one, or the device's (preferredLocale). - ICU apostrophes are quotes.
l'{app}rendersl{app}; writel''{app}. Files written forgen-l10nmay need an apostrophe before{or}doubled. - Numbers are not locale-formatted (
1000, not1 000).selectordinalis not supported: the message is shown as written and reported once in debug. Plural categories come fromintl(French 0 isone; 1.5 isother); aselectgiven an enum matches on itsname. - A CDN failure is silent. The app keeps the cache, then the bundled text, and nothing is printed. Tolgee publishes
after up to 15 minutes; a locale is fetched once per container;
refreshOnResumeis off by default andrefreshOnReconnectacts only after a failed fetch. The web needs CORS headers on the CDN. - Hive storage gives the cache one frame later;
PrefsDataStoragegives it on the first frame. adapters: [fespalier_tolgee]does not compile: the package has nofespalier_adapter.dart(the setup is app code, whichstartup()already is).Target of URI doesn't existnames the file.localeSpellingandrelocateneedAppManifest(fromapp.g.dart, or the libraryoutput_manifestnames).
What it does not do
Typed keys (gen-l10n's job: an app may keep gen-l10n beside this, its getters are just not updated over the air), the
tolgee SDK's widgets, a polling refresh, fespalier_adapter.dart, and telemetry (none in v1; a later span would never
carry keys, texts or the CDN URL). It starts no timer and adds no listener of its own.
References
| Need | Page |
|---|---|
$lang versus paths, localeSegment, localeSpelling, the language menu, the first URL |
references/locales-and-the-url.md |
ARB and Tolgee JSON, the ICU subset, tolgee pull, gen-l10n beside it or migrating from it |
references/messages-and-catalogs.md |
TolgeeCdn, ETags, the fallback chain, the cache key, a TranslationSource of your own |
references/over-the-air-and-cache.md |
The debug-only panel, tolgee.local.json, key scope, RecordingEditor |
references/in-context-editing.md |
fakeTranslations, FakeTranslations, a restart, fsp test and setup.dart |
references/testing.md |
| An error message, or a symptom | fespalier-troubleshooting (its diagnostics-tolgee.md page) |
The route side: route.dart paths, locationFor, locale: |
fespalier-routing (its route-dart.md page) |
Example
examples/i18n (in the fespalier repository) is this skill as a runnable app: lib/app/startup.dart (bundled ARB assets), app.dart (the scope's routerConfig), $lang/layout.dart (a language switch with relocate), products/ (an ICU plural and a paths spelling) and test/i18n_test.dart (pumpRouter(app:), FakeTranslations, fakeTranslations), with no network and no key.
Where the code is
packages/fespalier_tolgee/lib/src/: scope.dart (TranslationScope, context.tr, TrText), providers.dart
(translationsConfig, translator, preferredLocale, the fetcher and the cache), translator.dart (the chain,
originOf), icu.dart, locale.dart (localeSegment, localeSpelling, relocate), tolgee_cdn.dart,
bundled.dart, in_context/; lib/testing.dart; test/no_timers_test.dart and test/no_secrets_test.dart grep
lib/ for timers and for key code. The guide is
docs/i18n-tolgee.md.