translocale_flutter_runtime 0.1.0

Flutter integration for approved TransLocale translation updates and offline fallback.

TransLocale Flutter runtime

Approved translation updates for Flutter, with automatic refresh and offline fallback.

translocale_flutter remains the Dart developer tool. This package adds Flutter platform defaults around the independent translocale_delivery client. All client packages use MIT.

See migration from existing packages before upgrading an app.

Install

flutter pub add translocale_flutter_runtime:^0.1.0
flutter pub add --dev translocale_flutter:^0.2.0

Requires Dart 3.12 and a configured TransLocale cloud project.

Setup

Generate the integration and schema with the TransLocale CLI after mapping the source catalogs:

translocale flutter-init --catalog app.arb
translocale flutter-setup --file release-schema.json --catalog app.arb

Create one runtime for the app, then pass it to the generated wrapper:

import 'package:translocale_flutter_runtime/translocale_flutter_runtime.dart';

final delivery = FlutterDelivery(
  projectId: projectId,
  schemaHash: translocaleSchemaHash,
  token: deliveryToken,
);

// Inside build:
TransLocaleAppLocalizationsBuilder(
  delivery: delivery,
  builder: (context, delegates) => MaterialApp(
    localizationsDelegates: delegates,
    supportedLocales: AppLocalizations.supportedLocales,
    home: const HomePage(),
  ),
)

Keep the runtime outside build so rebuilds retain the same client. The generated wrapper owns it and disposes it when replaced or removed. Existing AppLocalizations.of(context) calls keep their types and bundled fallback.

translocaleSchemaHash comes from the generated adapter; import that file alongside the runtime. The lower-level Dart ota-adapter command remains available when supplying schema configuration yourself.

Use a read-only tld_ delivery credential scoped to the project, channel and schema. The default channel is production; set channel: 'preview' for release checks. Cloud delivery must be enabled and compatible translations published before an app can fetch them. App credentials are extractable; never embed authoring credentials.

Defaults and overrides

• Startup begins after the wrapper's first frame. Version lookup, cache reads and network requests do not delay bundled translations.
• The installed app version comes from package_info_plus. Detection has a three-second deadline. Supply appVersion: '1.2.3' to override it; appVersionProvider supports tests and custom version sources. Versions must have three numeric components. Build numbers are not part of the release compatibility check.
• Native platforms use private application-support storage through path_provider. Cache entries are validated, written atomically, and contain no credentials. Storage failure permits network delivery; offline fallback uses valid cached or bundled wording.
• Flutter web uses browser localStorage, scoped by service origin, project, channel and schema. It validates cached releases before use and stores no credentials. Blocked or full storage keeps delivery working with network or bundled wording; a failed write preserves the previous entry.
• Pass cache to use another DeliveryCache, or persistentCache: false to disable the default cache. An explicit cache takes precedence.
• The wrapper pauses polling while inactive and refreshes on resume. Set automaticUpdates: false on the wrapper for manual-only checks through delivery.check().
• Setup errors use state.error values app_version or configuration, retain bundled wording and permit a manual retry. Disposal cancels waiting for version detection; a late result cannot start delivery.

FlutterDelivery and the lower-level DeliveryClient implement DeliveryRuntime, so either works with the generated adapter. The underlying client retains its integrity checks, cache validation, server cooldowns, version bounds and compatible rollback behavior. See delivery behavior and formatting limits.

For offline web reloads, the app itself must be available offline and its version must resolve. package_info_plus reads version.json on web; make that file available offline or provide the current build's appVersion. Translation caching does not cache app assets or version metadata. Browser settings can clear stored translations; bundled wording remains the fallback.

For Android release builds, grant Internet access in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Production delivery uses HTTPS. Network entitlements, plugin setup and deployment targets remain the app's responsibility. The plugin dependencies currently require Flutter 3.38.1 or later, Dart 3.12 for this package, iOS 13+, macOS 10.15+, and Android SDK 24+. Check their linked requirements for Android build-tool versions.

Verification and release status

Run flutter test and flutter analyze in this package. Runtime tests cover deferred initialization, version overrides and timeouts, cancellation, private cache recovery, storage failures, and inactive polling. Host tests of the web storage adapter cover offline restoration, cache isolation, corrupt or incompatible entries and failed writes. The repository's test:delivery:flutter-app installs local copies into an isolated consumer and exercises the generated adapter. Its --build-web option compiles with delivery configured, using a nonsecret fixture unless a delivery configuration is supplied.

Manifest discovery and credential configuration use flutter-init and flutter-connect. Host tests, service checks and compiled builds cover the delivery contract. Installed-device and actual browser-persistence checks remain separate from those tests.

License

MIT. The hosted service remains proprietary.