Over the Air (Strings)

With the SDK, the app regularly checks for updated translations and downloads them in the background.

Regularly check the latest releases of the Android SDK, especially considering upgrades.

If translations are not being updated:

If the wrong version of a translation is being used, ensure a release with the latest translations and the current app version is available and the versionName for the app set and are using the <major>.<minor>.<point>. format.

Requirements

Include the SDK

Add a new repository to the root build.gradle:

allprojects {
    repositories {
        ...
        maven { url "https://maven.download.phrase.com" }
    }
}

Add the library as a dependency:

dependencies {
    implementation "com.phrase.android:ota-sdk:3.5.0"
    ...
}

Jetpack Compose support

To enable Jetpack Compose support for OTA translations, follow these steps:

Configuration

Initialize the SDK in the application class and add the distribution ID and environment secret. Classes inheriting from Application should overwrite attachBaseContext to enable translations outside of the activity context:

public class MainApplication extends Application {
  @Override
  public void onCreate() {
      super.onCreate();
      Phrase.setup(this, "DISTRIBUTION_ID", "ENVIRONMENT_TOKEN");
      Phrase.updateTranslations();
  }

  @Override
  protected void attachBaseContext(Context newBase) {
    super.attachBaseContext(Phrase.wrapApplicationContext(newBase));
  }  
}

Iinject the SDK in each activity, e.g. by creating a base activity which all other activities inherit from:

public class BaseActivity extends AppCompatActivity {
  @NonNull
  @Override
  public AppCompatDelegate getDelegate() {
    return Phrase.getDelegate(this, super.getDelegate());
  }
}

Translations can be used as usual in layouts:

<TextView android:text="@string/translation_key" />

And inside code:

TextView text = (TextView) findViewById(R.id.text_id);
text.setText(R.string.translation_key);

Some libraries do not support automatically unwrapping the context and expect a specific class. In this case context wrapping in Jetpack Compose components can be disabled with:

Phrase(contextWrapping = false) {
    Text( text = phraseString(R.string.test) )
}

Configurations for log levels:

Change language

If not using the system language, a different language can be set in the setLocaleCode method. The language code (locale) must be present in a release.

Phrase.setLocaleCode("fr");
Phrase.updateTranslations();

Custom app version

The SDK uses the app version by default to return a release which matches the release constraints for the min and max version. The app version must use semantic versioning otherwise no translation update is returned. In case the app does not use semantic versioning it is possible to manually override the used app version.

Example:

Phrase.setAppVersion("3.2.4");

The version must be set before calling updateTranslations( ).

Set timeout

The default timeout for translation downloads is set to 10s.

The default can be changed with:

Phrase.setTimeout(10000); // Timeout in milliseconds

Update callback

If the handling of successful translation updates is required, attach a callback handler:

Phrase.updateTranslations(new TranslationsSyncCallback() {
    @Override
    public void onSuccess(boolean translationsChanged) {
    }

    @Override
    public void onFailure() {
    }
});

Translation updates can also be manually triggered:

Phrase.updateTranslations(new TranslationsSyncCallback() {
    @Override
    public void onSuccess(boolean translationsChanged) { 
    }

    @Override
    public void onFailure() {
    }
});

Configure US data center

Phrase US data center is also supported. The US data center can be configured by calling:

Phrase.setHost("https://ota.us.app.phrase.com")

Fallback

In case it is not possible to reach Phrase due to a missing network connection of the client or a service interruption, the SDK uses the bundled translations from the resource file. The regular updating of the bundled translations in the app is recommended. The SDK also caches translations locally on the device. If such a cache exists, it is used until the next translation update.

The SDK uses the most recent release for the translations. In case the versionName for the app is set, the most recent release that satisfies the version restrictions will be used.

Add a new language

Creating the new language in Phrase and create a new release. The SDK fetches the language when this is the device language of a user. Regularly adding a new strings.xml for new languages files when releasing a new app version is recommended or users will only see the fallback translations determined by Android at the first start of the app.

Auditing

The SDK is closed source and can not be viewed or modified. If it is an organization requirement, audits can be provided. Contact us for more details if required.

Custom View Support

Custom views can be translated using styled attributes. Since TypedArray does not allow overwriting the resources, slight changes in the custom view are required:

Example app

https://github.com/phrase/android-sdk-example

With the SDK, the app regularly checks for updated translations and downloads them in the background.

Requirements

This library depends on 0.17.0 version of Flutter's intl library.Follow their guide to add localizations support to the app.

Installation

Add Phrase to the pubspec.yaml:

dependencies:
  phrase: ^1.0.1 
  ...
  intl: ^0.17.0
  flutter_localizations:
    sdk: flutter
  ...

flutter:
  generate: true
  ...

Like in the intl library, code generation is used to process ARB files. Run this command to update:

flutter pub run phrase

Using build_runner:

flutter pub run build_runner watch

Usage

Initialize Phrase in the 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,
    );
  }
}

Access messages with:

Text(AppLocalizations.of(context)!.helloWorld);

Customization

Update behavior

OTA translations are updated every time the app launches. To disable this:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", 
    checkForUpdates: false);

To update manually:

Phrase.updateTranslations(context).then((_) => print("Done!"));

Custom app version

The SDK uses the app version by default to return a release which matches the release constraints for the min and max version. The app version must use semantic versioning otherwise no translation update will be returned. In case app does not use semantic versioning, the app version can be manually overridden: it is possible to manually override the app version:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]",
    customAppVersion: "1.2.3");

Configure US data center

Phrase US data center is also supported. The US data center can be selected by passing the relevant API hostname parameter in the SDK configuration:

Phrase.setup("[DISTRIBUTION_ID]", "[ENVIRONMENT_ID]", host: PhraseHost.us);

Example app

https://github.com/phrase/flutter_sdk_example

With the SDK, the app regularly checks for updated translations and downloads them in the background.

Mac Catalyst is also supported.

The SDK can be installed manually or via Swift Package Manager, Carthage or Cocoa Pods.

If translations are not being updated:

If the wrong version of a translation is being used, ensure a release with the latest translations and the current app version is available.

Swift Package Manager

Add the public repository URL (https://github.com/phrase/ios-sdk/). Xcode automatically handles the rest of the installation.

Carthage

Add the following line into your Cartfile:

binary "https://raw.githubusercontent.com/phrase/ios-sdk/master/PhraseSDK.json" ~> 3.0.0

Run carthage update and add the PhraseApp.framework  to your project as desribed in the Carthage documentation.

Cocoa Pods

Add the following line into your Podfile:

pod 'PhraseSDK'

Run pod install. If new to CocoaPods, see their documentation.

Manual installation

Follow these steps:

Configuration

Calling both functions within the AppDelegate in the applicationDidFinishLaunchingWithOptions method is recommended.

Objective-C

Integrate the SDK into the Objective-C application:

@import PhraseSDK;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [[Phrase shared] setDebugMode:true]; // Optional

  [[Phrase shared] setupWithDistributionID:@"Your Distribution ID"
                         environmentSecret:@"Your Environment Secret"];

  // OR:
  //
  //  [[Phrase shared] setupWithDistributionID:@"Your Distribution ID"
  //                         environmentSecret:@"Your Environment Secret"
  //                                   timeout:10];

  // Update translations using callback block:
  [[Phrase shared] updateTranslationsWithCompletionHandler:^(BOOL updated, NSError* error){
    NSLog(@"Updated: %@", updated ? @"true" : @"false");

    if (error) {
      NSLog(@"Domain: %@ Code: %ld Message: %@", error.domain, (long)error.code, error.localizedDescription);
    } else {
      NSLog(@"No error");
    }

    // Translate via bundle proxy:
    NSString *translation = NSLocalizedString(@"layouts.application.about", @"");
    NSLog(@"NSLocalizedString via bundle proxy: %@", translation);

    // OR:
    //
    // Translate using fallback method:
    NSString *otherTranslation = [[Phrase shared]
                                  localizedStringForKey:@"layouts.application.about" value:NULL table:NULL];
    NSLog(@"Phrase.shared localizedStringForKey: %@", otherTranslation);
  }];

  // OR:
  //
  // [[Phrase shared] updateTranslationsWithCompletionHandler:NULL]; // ignore result and errors (not recommended)

  // [...] Your other code
  
  return YES;
}

Disable swizzling

To disable swizzling, set PhraseSDKMainBundleProxyDisabled to YES in the Info.plist file.

When swizzling is disabled, updated translations are no longer be displayed. The translation will still be synced if updateTranslation is called and can be accessed with the Phrase.localizedString() method.

App version handling

To determine which release should be returned the SDK requires a semantic version of the app so translations are updated.

The SDK attempts to get a semantic version the following way:

If CFBundleShortVersionString is missing or unable to be created with a semantic version together with CFBundleVersion, the SDK throws the PhraseSetupError.appVersionNotSemantic message.

Disable translation for multiple tables

To prevent OTA from translating any tables in the main iOS bundle other than the default Localizable table, set the following option:

Phrase.shared.configuration.ignoreOtherTables = true

Callbacks

Attach a callback handler to handle successful translation updates:

Phrase.shared.updateTranslation { result in
            switch result {
            case .success(let updated):
            case .failure:
            }
        }

Making updates visible

Updated translations are usually automatically visible to the user the next time app launches. To enforce new translations to be immediately visible, reload the ViewController on a successful callback:

func reloadRootViewController() {
  DispatchQueue.main.async {
    let storyboard = UIStoryboard.init(name: "Main", bundle: nil)
    let appDelegate = UIApplication.shared.delegate as! AppDelegate
    appDelegate.window?.rootViewController = storyboard.instantiateInitialViewController()
  }
}

Debug mode

If further information is required, enable the debug mode to get additional logging of the PhraseSDK.framework into the console:

Phrase.shared.configuration.debugMode = true

Set timeout for requests

Set a timeout for the requests against Phrase by calling:

Phrase.shared.configuration.timeout = TimeInterval(20)

The default timeout is 10 seconds and connections taking longer than 10 seconds will be closed.

Provide manual language override

If not using the system language as the locale, a different locale can be set in the init call. The locale code needs to be present in a release from Phrase:

Phrase.shared.configuration.localeOverride = "en-US"

Fallback

In case new translations cannot be fetched from Phrase via the SDK, the latest translation files that the installation received are used. If the App never received new files from Phrase, it uses the compiled translation files of app. This prevents errors in case of any technical difficulties or networking errors. Keeping your translation files that are compiled into the app up to date with every release is recommended.

Auditing

The SDK is closed source and can not be viewed or modified. If it is an organization requirement, audits can be provided. Contact us for more details if required.

With the SDK, the app regularly checks for updated translations and downloads them in the background.

The library for OTA translations only works with the react-i18next library.

To install the React Native SDK, follow these steps:

Sample i18next.js file

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import ChainedBackend from "i18next-chained-backend";
import resourcesToBackend from "i18next-resources-to-backend";
import translationEN from "./locales/en/translation.json";
import translationRU from "./locales/ru/translation.json";
import Phrase from "react-native-phrase-sdk";

const localResources = {
  en: {
    translation: translationEN,
  },
  ru: {
    translation: translationRU,
  },
};

let phrase = new Phrase(
    "YOUR_DISTRIBUTION_ID",
    "YOUR_ENVIRONMENT_ID",
    require('./package.json').version,
    "i18next"
);

const backendPhrase = resourcesToBackend((language, namespace, callback) => {
    phrase.requestTranslation(language)
        .then((remoteResources) => {
            callback(null, remoteResources);
        })
        .catch((error) => {
            callback(error, null);
        });
});

const backendFallback = resourcesToBackend(localResources)

i18n
  .use(ChainedBackend)
  .use(initReactI18next)
  .init({
    backend: {
        backends: [backendPhrase, backendFallback]
    },
    debug: true,
    lng: "en",
    fallbackLng: "en",
    interpolation: {
      escapeValue: false, // not needed for react as it escapes by default
    }
  });

Example app

https://github.com/phrase/react_native_sdk_example

The i18next-phrase-backend library implements an example backend for i18next which retrieves the translations from OTA releases.

To create a new release, the i18next platform needs to be set for the distribution and be part of a release.

Usage

To initialize Phrase:

import i18n from "i18next";
import { I18nextPhraseBackend } from "@phrase/i18next-backend";

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribution: 'DISTRIBUTION_ID',
      secret: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
    }
  });

Caching

The library is caching translations and will not check for new translations for 5 minutes. Caching can be configured by setting the cacheExpirationTime option in the backend configuration for testing purposes.

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribution: 'DISTRIBUTION_ID',
      secret: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
      cacheExpirationTime: 60 * 5, // time in seconds
    }
  });

Example app

https://github.com/phrase/ota-web-demo

The phrase-ota-i18n library implements an example backend for the I18n gem which retrieves the translations from OTA releases. With the library, the application regularly checks for updated translations and downloads them in the background.

The library is valid for any Ruby application using the i18n gem.

To create a new release, the Rails platform needs to be set for the distribution and be part of a release.

Installation

Usage

To generate the configuration:

bundle exec rails generate phrase_ota:install --distribution-id <DISTRIBUTION_ID> --secret-token <SECRET>

Debugging

The gem has a debug configuration which can be enabled in the initializer by setting:

config.debug = true