Flutter API and update lifecycle

All translation readers may use the SDK. Publishing and read-key administration remain Owner/Admin operations in the panel. Runtime requests carry only a channel-scoped read key.

Client operations

API	Behavior
createLocalisyncClient(config)	Supplies native or Web persistence, transport and preparation adapters.
LocalisyncClient(...)	Injects boundary adapters for controlled integrations and tests.
translate(key, arguments:, locale:, defaultValue:)	Synchronous prepared-memory lookup.
resolve(...)	Returns text, source, requested/resolved locale, release and argument failure.
ready	Completes initial cache loading and the optional startup refresh. First rendering need not await it.
refresh()	Explicit bounded update; simultaneous calls share the active operation.
setLocale(tag)	Prepares that locale from the active release without checking for a new publication.
activatePending()	Activates a verified candidate in manual activation mode.
changes, status	Typed update phase and active-content version.
dispose()	Cancels work and closes owned transport, storage and status stream.

LocalisyncConfig requires project/distribution IDs, channel, two distinct delivery origins, read key, trusted Ed25519 public keys, strict SemVer application version, selected locale and bundled translations. Pass generated contracts to protect compiled typed accessors. The default request timeout is 15 seconds and the complete refresh deadline is 60 seconds. The persistent budget defaults to 256 MiB.

status.contentVersion advances only when visible content or locale changes. Use it to refresh translation consumers. status.revision is the signed channel decision, not the release display number. The starting, checking, downloading and pending phases may coexist with usable baseline or previous content. failed describes an update failure; it does not mean synchronous translations are unavailable.

resolve() returns a parameter diagnostic in failure when a message cannot be formatted. Inspect that field rather than treating fallback text as a successful format. Subscribe to changes for update status, and cancel subscriptions when the owning widget/service ends. dispose() is asynchronous; await it in service teardown. A widget can use an explicitly unawaited disposal from its synchronous dispose() method.

Update policy

UpdatePolicy.onStart performs one automatic refresh during initialization. There is no resume observer, repeating timer or persistent connection. Widget rebuilds do not create checks. Set UpdatePolicy.manual to initialize from bundle/cache and wait for explicit refresh().

ActivationPolicy.immediate activates a completely verified candidate. With ActivationPolicy.manual, hasPending and the pending phase expose the candidate; call activatePending() to apply it. A newer check invalidates an older pending choice.

Outcomes distinguish updated, unchanged, pending, bundled, failed and cancelled. A storage failure can accompany a usable in-memory update: persisted is false. It does not claim that a restart will retain that generation. Configuration errors fail construction; network errors are returned without interrupting synchronous reads.

Widget integration

LocalisyncScope.of(context) subscribes the caller to active-content changes. Widgets outside that dependency do not rebuild for translations. Preserve navigator and form keys when rebuilding a MaterialApp; do not key the whole application by release ID.

flutterLocale(tag) accepts language, script and region. It rejects variants that Flutter’s Locale cannot represent. The core retains the full tag; provide an explicit application mapping at the Flutter boundary instead of silently dropping a variant.

Diagnosing results

LocalisyncException.code separates configuration, network, timeout, cancellation, authorization, integrity, protocol, compatibility, stale revision, storage, locale, argument and disposed-client failures. Messages are English and do not contain read keys or message bodies. Use the code for diagnostics; do not infer success from a completed network request.

Generate the full Dart API reference with dart doc in each package. This guide describes application behavior; generated Dart documentation follows the actual exported signatures.