Skip to main content

Public API Reference

This reference lists the primary methods exposed by the Flutter v4 SDK. Use these APIs to initialize the SDK, translate content, manage languages, and integrate WebViews.

Setting APIs​

initialize​

Wovn.initialize({required String token, LocalSettings? config})

Bootstraps the SDK. Call this before rendering any translated widgets.

Parameters:

  • token: Project token issued by WOVN.
  • config: Optional LocalSettings for SDK configuration. Supported fields include logLevel (0=trace, 1=info, 2=warning) and translationPreviewMode (bool).

Example:

await Wovn.initialize(
  token: 'YOUR_TOKEN',
  config: const LocalSettings(
    logLevel: 0, // 0 = trace, 2 = warn
    translationPreviewMode: false,
  ),
);

wrapApp​

Wovn.wrapApp(Widget app) -> Widget

Wraps your root widget so the SDK can listen for language changes.

Parameters:

  • app: Your root widget.

Returns: A widget that should be passed to runApp.

Example:

runApp(Wovn.wrapApp(const MyApp()));

Translation APIs​

translate​

Wovn().translate(String text, {BuildContext? context, String? screenName}) -> String

Translates ad-hoc strings, useful for unsupported widgets or logging.

Parameters:

  • text: Source text to translate.
  • context: Optional BuildContext used to infer screen name.
  • screenName: Optional explicit screen name.

Returns: The translated text, or the original text if no translation is found.

Example:

final label = Wovn().translate('Welcome!', screenName: 'HomeScreen');

WovnText, WovnRichText, WovnListenableBuilder​

Drop-in widgets that automatically re-render when the language changes. Import package:wovn_flutter/wovn_flutter.dart to use them.

Notes:

  • All WOVN widgets support the isIgnored property. Set isIgnored: true to exclude specific text from translation.
  • See Ignoring Translations for detailed examples and alternatives.

Example:

WovnText('Welcome!', isIgnored: false);

Language APIs​

changeLang​

Wovn().changeLang(Locale locale)

Switches to a specific locale.

Parameters:

  • locale: Target locale, for example const Locale('ja').

changeLangUsingLocaleString​

Wovn().changeLangUsingLocaleString(String code)

Switches to a locale using an IETF language tag.

Parameters:

  • code: Locale string such as en-US or ja.

changeToSystemLang​

Wovn().changeToSystemLang()

Syncs the SDK with the device system language.

lang / langCode​

Wovn().lang -> Locale and Wovn().langCode -> String

Returns the current locale as a Locale or language tag.

languagesListCode​

Wovn().languagesListCode -> List<String>

Returns the list of available language codes.

sourceLanguage / secondaryLanguage​

Wovn().sourceLanguage -> Locale and Wovn().secondaryLanguage -> Locale?

Returns the source language and optional secondary language configured for the project.

Enable/Disable APIs​

Available from v4.1.0

isWovnEnabled​

Wovn().isWovnEnabled -> bool

Returns whether WOVN functionality is currently enabled.

Returns: true if WOVN is enabled (translations active, reporting enabled), false otherwise.

Example:

if (Wovn().isWovnEnabled) {
  debugPrint('WOVN translations are active');
}

enable​

Wovn().enable()

Enables WOVN functionality.

When enabled:

  • Text translations are performed
  • Untranslated strings are reported to WOVN servers
  • WebViews are translated

Example:

Wovn().enable();

disable​

Wovn().disable()

Disables WOVN functionality.

When disabled:

  • Original/untranslated text is returned
  • No reporting is performed to WOVN servers
  • WebViews are not translated
  • Language preference is preserved for when re-enabled

Example:

Wovn().disable();

WebView APIs​

followWebViewController​

Wovn().followWebViewController(WebViewController controller, {bool shouldTranslateImmediately = true})

Registers a WebViewController created via webview_flutter.

Parameters:

  • controller: The WebViewController instance to track.
  • shouldTranslateImmediately: If false, call translateWebViews on each navigation event.

Example:

late final WebViewController controller;

void initState() {
  controller = WebViewController()
    ..setJavaScriptMode(JavaScriptMode.unrestricted)
    ..setNavigationDelegate(
      NavigationDelegate(onPageFinished: (_) => Wovn().translateWebViews()),
    );

  Wovn().followWebViewController(controller, shouldTranslateImmediately: false);
}

translateWebViews​

Wovn().translateWebViews()

Injects translations into all tracked WebViews.

getTranslateWebViewScript​

Wovn().getTranslateWebViewScript() -> String

Returns the raw JavaScript snippet for advanced WebView scenarios.

Legacy APIs​

startVisualUpdating​

Wovn().startVisualUpdating(BuildContext context)

Legacy polling translator for non-reactive widgets. Avoid when using WovnListenableBuilder.

runAppWithWovn / init​

Wovn().runAppWithWovn(...) and Wovn().init()

Deprecated APIs from v1. Use Wovn.initialize and Wovn.wrapApp instead.

Status APIs​

Wovn.isInitialized​

Wovn.isInitialized -> bool

Returns true after Wovn.initialize completes.

Example:

if (Wovn.isInitialized) {
  debugPrint('WOVN is ready');
}

getWovnStatus​

Wovn().getWovnStatus() -> String

Returns a multi-line summary string (token, language, available languages, preview flag, client ID).

Example:

final status = Wovn().getWovnStatus();
debugPrint(status);

getClientId​

Wovn().getClientId() -> String

Returns the client ID used for Development Mode registration.

isRunningInDevelopmentMode​

Wovn().isRunningInDevelopmentMode() -> bool

Returns whether the current device has been approved in the dashboard.

token​

Wovn().token -> String

Returns the active project token.

version​

Wovn.version -> String

Returns the SDK version string.

translationPreviewMode​

Wovn().translationPreviewMode -> bool

Returns true only when preview mode is enabled and the device is verified.