Skip to content

feat!: in-context editing with the Tolgee web editor and safe release builds - #11

Open
dkrizan wants to merge 16 commits into
mainfrom
dkrizan/flutter-sdk-2
Open

dkrizan wants to merge 16 commits into
mainfrom
dkrizan/flutter-sdk-2

Conversation

@dkrizan

@dkrizan dkrizan commented Oct 27, 2026

Copy link
Copy Markdown
Member

Brings the Flutter SDK closer to tolgee-js. Dev builds get in-context editing with the Tolgee web editor, and release builds stop calling the Tolgee API and never contain the API key.

  • Two packages in packages/: tolgee (core) and the new tolgee_in_context (the editor). The editor needs a WebView plugin, and Flutter ships every plugin of every dependency in release apps. Keeping it separate means apps without editing don't carry it. Both are released together with the same version.
  • Loading works like tolgee-js. Dev builds load from the API, with the key read from --dart-define only outside release builds. Release builds use the CDN, bundled files or both, with an optional fallback to the files. All texts of a language load in one request.
  • In-context editing reuses the tolgee-js dialog. It runs in the host page on the web, and in a WebView on iOS, Android and macOS. Alt+click on web and macOS, a Tolgee bubble on iOS and Android, no editor on Windows and Linux.
  • The 1.x popups are removed, which makes this a major release. doc/migrating-to-2.md covers the upgrade.
  • Workflows test, release and publish both packages. tolgee is published first, then tolgee_in_context once pub.dev serves the new tolgee.

Checked in the example app on web, iOS, Android and macOS against a real Tolgee project: editing and saving, the key picker, start language, plurals, release builds, and CDN failure with and without the fallback.

Release notes

Breaking

  • The 1.x translation popups are removed. In-context editing moves to the new tolgee_in_context package, which uses the Tolgee web editor
  • Release builds don't call the Tolgee API. apiKey and apiUrl are ignored there; pass the key with --dart-define=TOLGEE_API_KEY in dev builds instead
  • Language tags are kept whole (pt-BR), so bundled files are named after them
  • A builder of TranslationWidget must not return Expanded, Flexible, Positioned or a sliver
  • Dart 3.3 or newer is required

New

  • In-context editing: Alt (Option) + click on the web and macOS, a Tolgee bubble on iOS and Android
  • The CDN works without an API key, and fallbackOnFail falls back to bundled files when it fails
  • Bundled files are optional; availableLanguages and baseLanguage describe the languages without the API
  • Texts missing in the current language come from the base language
  • Tolgee.languages, Tolgee.reload() and TolgeeProjectLanguage.locale

Fixed

  • Tolgee.init completes with the texts loaded, so the first frame no longer shows keys
  • The API key no longer shows up when the config is printed
  • Warnings and errors are logged in debug builds by default

Changed

  • All translations of a language load in one API request instead of 20 keys per request

Before and after releasing

  • A tolgee.io publisher admin publishes the first version of tolgee_in_context on pub.dev by hand (from packages/tolgee_in_context, with pubspec_overrides.yaml moved aside), then turns on automated publishing for it with the tag pattern v{{version}}. Until then, the Publish workflow skips it with a warning.
  • Known limit on macOS: webview_flutter can't make the WebView transparent there, so the editor covers the app window while it's open.

The 1.x path paged 20 keys per request.
…ove the 1.x editing popups

- Dev builds load from the Tolgee API; on failure, the CDN or bundled files
- The CDN works without an API key; fallbackOnFail falls back to bundled files
- Bundled files are optional; availableLanguages and baseLanguage replace
  what the API tells about languages
- Language tags are kept whole (pt-BR), missing texts fall back to the base
  language, and Tolgee.init completes with the texts loaded
- New Tolgee.languages and Tolgee.reload()

BREAKING CHANGE: the 1.x translation popups are removed. In-context editing
moves to the tolgee_in_context package.
New tolgee_in_context package with the dialog bridge from the prototype:
the tolgee-js dialog runs in the host page on the web and in a transparent
WebView elsewhere. tolgee-js is loaded from jsdelivr at a pinned version, and
a failed load closes the WebView instead of leaving it over the app.

The core package ignores the new folder when publishing and analyzing.
…nd Android

TolgeeInContext.install() turns it on in dev builds. Windows and Linux get
no editor, since the WebView plugin doesn't support them.
…ee_in_context

Four languages, a plural key and a two-key header. Adds web and macOS, and
regenerates the Android project for current Flutter and Gradle.
With tolgee_in_context inside the tolgee package, pub either packed it into
the tolgee archive or, through the root .pubignore, refused to publish it.
…er a save, log warnings by default

- A language that fails to load is left out, so the store keeps its texts
  and tries again later; an API failure after init no longer switches the
  session to the bundled files
- reload() drops the cached languages it doesn't refresh
- Warnings and errors print in debug builds; LogLevel is exported
- Docs: the builder must not return Expanded and the like, the StateError
  for apps without languages, rebuilding MaterialApp after a language change
…oot navigator, time out a hanging editor load
- Test runs analyze and tests in each package
- Release bumps both versions and the tolgee constraint of tolgee_in_context,
  and writes the same entry to both changelogs
- Publish publishes tolgee first, then tolgee_in_context once pub.dev serves
  the new tolgee; its first version is published by hand, since automated
  publishing needs an existing package
@dkrizan
dkrizan force-pushed the dkrizan/flutter-sdk-2 branch from ed6a6b4 to 86469e5 Compare November 2, 2026 16:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant