df_localization_jaspr

Localization for Jaspr apps, built on df_config's pure-Dart .tr() engine — the Flutter-free counterpart to df_localization.

df_localization depends on Flutter, so it can't be used in a Jaspr (pure-Dart) app. This package provides the same String.tr() experience without Flutter:

• String.tr() — re-exported from df_config, so translations use the exact same 'Default text||key' + {{ }} / { } handlebar syntax as the Flutter side, and the same content-addressed versioning (versionedTranslationKey).
• JasprTranslationController — owns the active locale, fetches a flat key → string map per locale from a host-supplied function, and installs it on TranslationManager so .tr() resolves.
• TranslationScope — a Jaspr component that resolves the initial locale on the client and re-renders when it changes.
• Locale detection — resolveInitialLocaleTag reads a lang param from the URL first (so an app that opens the site can hand its language across, e.g. …#from=app&lang=de-DE), then the browser language, matched against your supported locales with bestLocaleTag.

Usage

import 'package:df_localization_jaspr/df_localization_jaspr.dart';
import 'package:http/http.dart' as http;

// 1. A controller that fetches your backend's flat translation map per locale.
final controller = JasprTranslationController(
  fetchTranslations: (localeTag) async {
    final res = await http.get(Uri.parse('https://api.example.com/i18n/$localeTag'));
    return (jsonDecode(res.body) as Map).cast<String, String>();
  },
);

// 2. Wrap the part of your tree that uses `.tr()`. On the client it resolves
//    the locale (URL `lang` -> browser language) and re-renders on change; on
//    the server pre-render it emits the in-code English source.
TranslationScope(
  controller: controller,
  supportedTags: const ['en-us', 'de-de', 'es-us', 'fr-fr', 'nl-nl'],
  builder: (context) => const Home(),
);

// 3. Anywhere below, translate:
p([text('Welcome to this app||welcome'.tr())]);
p([text('Hi {__NAME__}||greeting'.tr(args: {'__NAME__': name}))]);

Server pre-render & SEO

The initial fetch runs on the client only (kIsWeb). During Jaspr's server pre-render .tr() emits the in-code English source — that is the SEO baseline — and the client re-renders in the visitor's language after hydration. Full per-locale server pre-render (translated HTML for crawlers) is out of scope here; model it at the routing/build layer if you need it.

Versioning

Pass versionBySourceText: true only if your fetchTranslations returns a map the server keyed with versionedTranslationKey(key, source) — that keeps each deployed build pinned to the copy it shipped with. See the df_config docs.

License

MIT — © dev-cetera.com & contributors.