phrase

Description:

phrase

Phrase Strings OTA for Flutter #
Library for Phrase Strings over-the-air translations.
Installation #
Important: this library depends on 0.18.0 version of Flutter's intl library.
Please follow this guide to add localizations support to your app.
Add the phrase dependency to your pubspec.yaml:
dependencies:
phrase: ^2.0.0
...
intl: ^0.18.0
flutter_localizations:
sdk: flutter
...

flutter:
generate: true
...
copied to clipboard
Just like intl library, phrase uses code generation to process your ARB files.
To keep it up-to-date, just run this command:
$ flutter pub run phrase
copied to clipboard
or if you're using build_runner:
$ flutter pub run build_runner watch
copied to clipboard
Usage #
Initialize Phrase Strings in your main.dart file:
import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';
import 'package:flutter_gen/gen_l10n/phrase_localizations.dart';
import 'package:phrase/phrase.dart';

void main() {
Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]");
runApp(MyApp());
}

class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
//..
localizationsDelegates: PhraseLocalizations.localizationsDelegates,
supportedLocales: PhraseLocalizations.supportedLocales,
);
}
}
copied to clipboard
That's it! You can access your messages just like you did before:
Text(AppLocalizations.of(context)!.helloWorld);
copied to clipboard
But now your app will check for updated translations in Phrase regularly and download them in the background.
Customization #
Update behavior #
By default, Phrase Strings will update OTA translations every time the app launches.
You can disable this behavior:
Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", checkForUpdates: false);
copied to clipboard
and trigger updates manually:
Phrase.updateTranslations(context).then((_) => print("Done!"));
copied to clipboard
Api host #
By default phrase uses european host. But we can set it to use the US api host if needed.
To do so, we just have to set it up during initial setup:
Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", host: PhraseHost.us);
copied to clipboard
Custom app version #
The SDK will use the app version by default to return a release which matches the release constraints for the min and max version. The app version has to use semantic versioning otherwise no translation update will be returned. In case your app does not use semantic versioning it is possible to manually override the app version:
Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", customAppVersion: "1.2.3");
copied to clipboard
Request time out #
By default the OTA requests are set with a default timeout of 30 seconds. This value can be configured in the Phrase setup:
Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", defaultTimeout: const Duration(seconds: 10));
copied to clipboard
and it can also be set when manually updating translations. In this case it will override the time out value that was set in during setup:
Phrase.updateTranslations(context, timeout: const Duration(seconds: 10));
copied to clipboard
Access OTA translation with key string literal #
You can access the OTA translation using a string literal containing the translation key. To get the translation value for
{
"textSimple": "Simple Text"
}
copied to clipboard
you can get the value using
Text(AppLocalizations.of(context).getText('textSimple'))
copied to clipboard
instead of
Text(AppLocalizations.of(context).textSimple)
copied to clipboard
It's also possible to use this method using translation parameters. To get the translation value for
{
"textWithDate": "Text with date: {date}",
"@textWithDate": {
"description": "Text with date parameter",
"placeholders": {
"date": {
"type": "DateTime",
"format": "yMd"
}
}
}
}
copied to clipboard
you can get the value using
Text(AppLocalizations.of(context).getText(
'textWithDate',
args: {'date': DateTime.utc(1996, 7, 10)},
))

copied to clipboard
instead of
Text(AppLocalizations.of(context).textWithDate(
DateTime.utc(1996, 7, 10),
)),
copied to clipboard
Notice that the argument key value must match the translation placeholder name, otherwise you will get a runtime error.
getText also supports setting a fallback value for the case where the given key is not present in the translations files. This can happen when using key values based on other variables.
Text(AppLocalizations.of(context).getText(
myKeyVariable,
fallbackValue: 'fallback for unknownKey',
))

copied to clipboard
Given that getText is a method in a class extension on AppLocalizations you have to import the file phrase_localizations.dart from the same location as it's done in setting up the App's localization. Either from package:flutter_gen/gen_l10n/phrase_localizations.dart or the one defined in l10n.yaml file's output-dir when using synthetic-package set to false. For example package:flutter_sdk_example/l10n/gen/phrase_localizations.dart.