Real-time preview (crowdin#27)

Author: FlutterOd

README.md

@@ -23,9 +23,10 @@ The Crowdin Flutter SDK delivers all new translations from Crowdin project to th
 ## Features
 
 - Load remote strings from Crowdin Over-The-Air Content Delivery Network
-- Built-in translations caching mechanism (enabled by default, can be disabled)
-- Network usage configuration (All, only Wi-Fi or Cellular)
-- Load static strings from the bundled ARB files (usable as a fallback for the CDN strings)
+  - Built-in translations caching mechanism (enabled by default, can be disabled)
+  - Network usage configuration (All, only Wi-Fi or Cellular)
+  - Load static strings from the bundled ARB files (usable as a fallback for the CDN strings)
+- Real-Time Preview – all the translations that are done in the Editor can be shown in your version of the application in real-time. View the translations already made and the ones you're currently typing in.
 
 ## Requirements
 
@@ -126,6 +127,121 @@ After receiving the translations, change the app locale as usual and the transla
 | `connectionType`   | Network type to be used for translations download. Supported values are `any`, `wifi`, `mobileData`, `ethernet`                                                                                       |
 | `updatesInterval`  | Translations update interval. Translations will not be updated more frequently than the designated time interval (default minimum is 15 minutes). Instead, it will use previously cached translations |
 
+## Real-Time Preview
+
+All translations done in the Crowdin Editor can be displayed in your version of the application in real-time. See the translations that have already been done and the ones you're typing.
+
+> **Note:** Real-Time Preview feature should not be used in production builds.
+> Currently, this feature is available only for Android and iOS applications.
+
+### Setup
+
+Add the following code to the Crowdin initialization:
+
+ ```dart
+ void main() async {
+   WidgetsFlutterBinding.ensureInitialized();
+
+   await Crowdin.init(
+     distributionHash: 'distribution_hash',
+     connectionType: InternetConnectionType.any,
+     updatesInterval: const Duration(minutes: 15),
+     withRealTimeUpdates: true, // use this parameter for enable/disable real-time preview functionality
+     authConfigurations: CrowdinAuthConfig(
+      clientId: 'clientId', // your clientId from Crowdin OAuth app
+      clientSecret: 'clientSecret', // your client secret from Crowdin OAuth app
+      redirectUri: 'redirectUri', // your redirect uri from Crowdin OAuth app
+      organizationName: 'organizationName' // optional (only for Crowdin Enterprise)
+     ),
+   );
+
+   // ...
+ }
+ ```
+
+Wrap your app root widget with the `CrowdinRealTimePreviewWidget`:
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return CrowdinRealTimePreviewWidget(
+    child: MaterialApp(
+      // ...
+
+      localizationsDelegates: CrowdinLocalization.localizationsDelegates,
+      supportedLocales: AppLocalizations.supportedLocales,
+      ),
+
+      // ...
+    );
+  }
+}
+```
+
+For [OAuth App](https://support.crowdin.com/creating-oauth-app/) the redirect URL should match your app scheme.
+For example, for scheme `<data android:scheme="crowdintest" />`, redirect URL in Crowdin should be `crowdintest://`.
+
+For Android app, declare the following intent filter in `android/app/src/main/AndroidManifest.xml`:
+
+  ```xml
+  <manifest ...>
+  <!-- ... other tags -->
+  <application ...>
+    <activity ...>
+      <!-- ... other tags -->
+
+      <intent-filter android:autoVerify="true">
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <!-- Accepts URIs that begin with https://YOUR_HOST -->
+        <data android:scheme="[YOUR_SCHEME]"/>
+      </intent-filter>
+      
+    </activity>
+  </application>
+</manifest>
+  ```
+
+For iOS app, declare the scheme in `ios/Runner/Info.plist`:
+
+```xml
+<?xml ...>
+<!-- ... other tags -->
+<plist>
+  <dict>
+    <!-- ... other tags -->
+
+    <key>CFBundleURLTypes</key>
+    <array>
+      <dict>
+        <key>CFBundleURLSchemes</key>
+        <array>
+          <string>[YOUR_SCHEME]</string>
+        </array>
+      </dict>
+    </array>
+
+    <!-- ... other tags -->
+  </dict>
+</plist>
+```
+
+### Config options
+
+| Config option         | Description                                                                |
+|-----------------------|----------------------------------------------------------------------------|
+| `withRealTimeUpdates` | Enable Real-Time Preview feature                                           |
+| `authConfigurations`  | `CrowdinAuthConfig` class that contains parameters for OAuth authorization |
+| `clientId`            | Crowdin OAuth Client ID                                                    |
+| `clientSecret`        | Crowdin OAuth Client Secret                                                |
+| `redirectUri`         | Crowdin OAuth redirect URL                                                 |
+| `organizationName`    | An Organization domain name (for Crowdin Enterprise users only)            |
+
+For more information about OAuth authorization in Crowdin, please check [this article](https://support.crowdin.com/creating-oauth-app/).
+
+> **Note:** To easily run your app in the Crowdin Editor, you can use [Crowdin Appetize integration](https://store.crowdin.com/appetize-app). It allows your translators to run this app in the Editor, see more context, and provide better translations.
+
 ## Notes
 
 - The CDN feature does not update the localization files. if you want to add new translations to the localization files you need to do it yourself.

example/android/app/build.gradle

@@ -47,7 +47,7 @@ android {
         applicationId "com.example.example"
         // You can update the following values to match your application needs.
         // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-build-configuration.
-        minSdkVersion flutter.minSdkVersion
+        minSdkVersion 19
         targetSdkVersion flutter.targetSdkVersion
         versionCode flutterVersionCode.toInteger()
         versionName flutterVersionName

example/lib/main.dart

@@ -1,3 +1,5 @@
+import 'dart:convert';
+
 import 'package:crowdin_sdk/crowdin_sdk.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_gen/gen_l10n/app_localizations.dart';
@@ -8,9 +10,18 @@ import 'package:intl/intl.dart';
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
   await Crowdin.init(
-    distributionHash: 'your distribution hash', //your distribution hash
+    distributionHash: 'distributionHash', //your distribution hash
     connectionType: InternetConnectionType.any,
     updatesInterval: const Duration(minutes: 25),
+
+    //uncomment next lines to enable real-time preview feature
+
+    // withRealTimeUpdates: true,
+    // authConfigurations: CrowdinAuthConfig(
+    //   clientId: 'clientId', // your clientId from Crowdin OAuth app
+    //   clientSecret: 'clientSecret', // your client secret from Crowdin OAuth app
+    //   redirectUri: 'redirectUri', // your redirect uri from Crowdin OAuth app
+    // ),
   );
   runApp(const MyHomePage());
 }
@@ -23,7 +34,8 @@ class MyHomePage extends StatefulWidget {
 }
 
 class _MyHomePageState extends State<MyHomePage> {
-  Locale currentLocale = Locale(Intl.shortLocale(Intl.systemLocale));
+  Locale currentLocale = Locale(Intl.shortLocale(Intl
+      .systemLocale)); //use system locale as default or provide one from your project, e.g. Locale('en')
   bool isLoading = true;
 
   @override
@@ -36,7 +48,9 @@ class _MyHomePageState extends State<MyHomePage> {
 
   @override
   Widget build(BuildContext context) {
-    return MaterialApp(
+    return
+        // CrowdinRealTimePreviewWidget(child:  //uncomment to enable real-time preview feature
+        MaterialApp(
       locale: currentLocale,
       localizationsDelegates: CrowdinLocalization.localizationsDelegates,
       supportedLocales: AppLocalizations.supportedLocales,
@@ -56,6 +70,7 @@ class _MyHomePageState extends State<MyHomePage> {
                 })
               },
             ),
+      // ), //uncomment to enable real-time preview feature
     );
   }
 }
@@ -145,6 +160,11 @@ class _MainScreenState extends State<MainScreen> {
               AppLocalizations.of(context)!.counter(_counter),
               style: const TextStyle(fontSize: 30),
             ),
+            const SizedBox(height: 16),
+            Text(
+              AppLocalizations.of(context)!.nThings(_counter, 'Plural example'),
+              style: const TextStyle(fontSize: 30),
+            ),
           ],
         ),
       ),

example/pubspec.yaml

@@ -6,7 +6,7 @@ publish_to: 'none' # Remove this line if you wish to publish to pub.dev
 version: 1.0.0+1
 
 environment:
-  sdk: '>=2.12.0 <3.0.0'
+  sdk: '>=2.12.0 <4.0.0'
 
 dependencies:
   flutter:

lib/crowdin_sdk.dart

@@ -1,3 +1,5 @@
 library crowdin_sdk;
 
 export 'src/crowdin.dart';
+export 'src/real_time_preview/crowdin_auth_config.dart';
+export 'src/real_time_preview/crowdin_real_time_preview_widget.dart';

lib/src/crowdin.dart

@@ -5,10 +5,12 @@ import 'package:crowdin_sdk/src/crowdin_api.dart';
 import 'package:crowdin_sdk/src/crowdin_storage.dart';
 import 'package:crowdin_sdk/src/crowdin_extractor.dart';
 import 'package:crowdin_sdk/src/crowdin_mapper.dart';
+import 'package:crowdin_sdk/src/real_time_preview/crowdin_preview_manager.dart';
 import 'package:flutter/widgets.dart';
 
 import 'common/gen_l10n_types.dart';
 import 'crowdin_logger.dart';
+import 'real_time_preview/crowdin_auth_config.dart';
 
 enum InternetConnectionType { wifi, mobileData, ethernet, any }
 
@@ -23,7 +25,7 @@ class Crowdin {
   static AppResourceBundle? _arb;
 
   @visibleForTesting
-  set arb(AppResourceBundle? value) {
+  static set arb(AppResourceBundle? value) {
     _arb = value;
   }
 
@@ -35,17 +37,34 @@ class Crowdin {
   /// contains certain distribution file paths for locales
   static int? _timestamp;
 
+  static List<String> _mappingFilePaths = [];
+
   static final CrowdinStorage _storage = CrowdinStorage();
 
   static late int? _timestampCached;
 
   static final _api = CrowdinApi();
 
+  static bool _withRealTimeUpdates = false;
+
+  static bool get withRealTimeUpdates => _withRealTimeUpdates;
+
+  @visibleForTesting
+  static set withRealTimeUpdates(bool value) {
+    _withRealTimeUpdates = value;
+  }
+
+  static late CrowdinPreviewManager crowdinPreviewManager;
+
+  static late CrowdinAuthConfig? _authConfig;
+
   /// Crowdin SDK initialization
   static Future<void> init({
     required String distributionHash,
     Duration? updatesInterval,
     InternetConnectionType? connectionType,
+    bool withRealTimeUpdates = false,
+    CrowdinAuthConfig? authConfigurations,
   }) async {
     await _storage.init();
 
@@ -75,6 +94,21 @@ class Crowdin {
 
       /// fetch manifest file to check if new updates available
       _timestamp = manifest['timestamp'];
+
+      _mappingFilePaths = (manifest['mapping'] as List<dynamic>)
+          .map((e) => e.toString())
+          .toList();
+    } else {
+      CrowdinLogger.printLog(
+          "something went wrong. Crowdin couldn't download manifest file for your project");
+    }
+
+    _withRealTimeUpdates = withRealTimeUpdates;
+
+    _authConfig = authConfigurations;
+
+    if (withRealTimeUpdates && _authConfig != null) {
+      setUpRealTimePreviewManager(_authConfig!);
     }
   }
 
@@ -98,6 +132,10 @@ class Crowdin {
         distribution = _storage.getTranslationFromStorage(locale);
         if (distribution != null) {
           _arb = AppResourceBundle(distribution);
+          if (_withRealTimeUpdates) {
+            crowdinPreviewManager.setPreviewArb(
+                _arb!); // set default translations for real-time preview
+          }
           return;
         }
       }
@@ -134,6 +172,18 @@ class Crowdin {
       _arb = null;
       return;
     }
+    if (_withRealTimeUpdates) {
+      crowdinPreviewManager.setPreviewArb(_arb!);
+    }
+  }
+
+  @visibleForTesting
+  static void setUpRealTimePreviewManager(CrowdinAuthConfig authConfig) {
+    crowdinPreviewManager = CrowdinPreviewManager(
+      config: authConfig,
+      distributionHash: _distributionHash,
+      mappingFilePaths: _mappingFilePaths,
+    );
   }
 
   static final Extractor _extractor = Extractor();
@@ -148,7 +198,7 @@ class Crowdin {
       try {
         return _extractor.getText(
           locale,
-          _arb!,
+          _withRealTimeUpdates ? crowdinPreviewManager.previewArb : _arb!,
           key,
           args,
         );

lib/src/crowdin_api.dart

@@ -34,4 +34,39 @@ class CrowdinApi {
       return null;
     }
   }
+
+  Future<Map<String, dynamic>?> getMapping({
+    required String distributionHash,
+    required String mappingFilePath,
+  }) async {
+    try {
+      var response = await http.get(Uri.parse(
+          'https://distributions.crowdin.net/$distributionHash$mappingFilePath'));
+      Map<String, dynamic> responseDecoded =
+          jsonDecode(utf8.decode(response.bodyBytes));
+      return responseDecoded;
+    } catch (ex) {
+      rethrow;
+    }
+  }
+
+  Future<Map<String, dynamic>?> getMetadata({
+    required String accessToken,
+    required String distributionHash,
+    String? organizationName,
+  }) async {
+    try {
+      String organizationDomain =
+          organizationName != null ? '$organizationName.' : '';
+      var response = await http.get(
+          Uri.parse(
+              'https://${organizationDomain}api.crowdin.com/api/v2/distributions/metadata?hash=$distributionHash'),
+          headers: {'Authorization': 'Bearer $accessToken'});
+      Map<String, dynamic> responseDecoded =
+          jsonDecode(utf8.decode(response.bodyBytes));
+      return responseDecoded;
+    } catch (ex) {
+      return null;
+    }
+  }
 }

lib/src/gen/crowdin_generator.dart

@@ -7,6 +7,8 @@ import 'package:path/path.dart' as path;
 import '../common/gen_l10n_types.dart';
 import 'l10n_config.dart';
 
+///todo refactor to reuse getKeys in real-time preview
+
 class CrowdinGenerator {
   static Future<void> generate() async {
     final String projectDirectory = Directory.current.path;