Introduction

Phrase Over the Air for Android lets you update translations in your Android app without having to release it every single time.

By including our SDK, your app will check for updated translations in Phrase regularly and download them in the background.

Include the SDK

As a first step a new repository needs to be added to the root build.gradle:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Now the library should be added as a dependency:

dependencies {
    implementation 'com.github.phrase:android-sdk:1.1.3'
    ...
}

Configuration

Initialize the SDK in your application class and add the distribution ID and environment secret from Phrase:

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

Additionally, you need to inject the SDK in each activity, e.g. by creating a base activity which all other activities inherit from:

public class BaseActivity extends AppCompatActivity {
    @Override
    protected void attachBaseContext(Context newBase) {
       super.attachBaseContext(PhraseApp.wrap(newBase));
    }
}

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);

Change locale

In case you don't want to use the system language as the locale you can set a different locale in the init  call. The locale code needs to be present in a release from Phrase.

PhraseApp.setup(this, "DISTRIBUTION_ID", "ENVIRONMENT_TOKEN", "OPTIONAL_LOCALE_CODE");

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 we use. For example:

PhraseApp.setAppVersion("3.2.4");

The version has to be set before calling updateTranslations( )

Set timeout

The default timeout for translation downloads is set to 10s. The default can be changed with:

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

Update Callback

In case you want to handle successful translation updates you can attach a callback handler:

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

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

Additionally it is possible to manually trigger translation updates:

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

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

Making updates visible

Usually, the updated translations will be automatically visible to the user the next time the app launches. If you want to enforce the new translations to be visible immediately, you need to handle this yourself, e.g. by recreating the activity on a successful callback.

Dependencies

ViewPump

We use ViewPump (Licensed under Apache 2.0) to intercept views.

Android Support Library v7

The library uses the Android Support Library v7 to support backward compatible UI elements like the Toolbar. In case your application is using the appcombat library you are required to use the following version to prevent a version conflict:

com.android.support:appcompat-v7:28.0.0

Versioning

Phrase Over the Air lets you specify version ranges for releases to ensure the appropriate content is made available for the right version. For this feature to work you need to set the versionName for the app in semver format as <major>.<minor>.<point>.

Fallback

In case it is not possible to reach Phrase due a missing network connection of the client or in case of a service interruption, the SDK will use the bundled translations from the resource file. Therefore we recommend to regularly update the bundled translations in your app. The SDK also caches translations and in case there already has been a successful update of translations this will be used until the next translation update. 

Data

The SDK will communicate with the Phrase Over the Air service in order to check for updates and includes the following details with each request:

  • Unique identifier (e.g. "123e4567-e89b-12d3-a456-426655440000". Unique for this app and therefore does not allow tracking a specific device.)
  • App version (e.g. "1.2.0")
  • Last update of the translation file (e.g. "1542187679")
  • SDK version (e.g. "1.0.0")
  • Locale (e.g. "de-DE")
  • File format (e.g. "simple_json")
  • Client (e.g. "android")
  • Distribution ID (ID of your distribution in Phrase)
  • Environment secret (to distinguish between development from production)

SDK Version Releases

Please make sure to regularly check the latest releases of our Android SDK, especially if you think about upgrading.

Auditing

The SDK is closed source and can thus not be viewed or modified. We do provide the possibility for audits in case this is a requirements of your organisation. Please contact us for more details on code audits.

FAQ

Which release will be used by the app?

The SDK will use 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. 

How can I add a new locale to the app?

Adding a new locale to the app is as simple as creating a new locale on Phrase and creating a new release. The SDK will then fetch the language when this is the device language of a user. We still recommend to regularly add new strings.xml for new languages  files when releasing a new app version. Otherwise the user will see the fallback translations determined by Android at the first start of the app.

Do you have a demo app?

Sure. Check it out on GitHub so see how to integrate Phrase Over the Air into your Android app.

Troubleshooting

Translations are not updated

  • Make sure the distribution ID and environment secret are correct.
  • Check whether you created a release on Phrase for your current app version.
  • Updated translations are visible automatically after the next app launch. Try recreating an activity to make changes appear immediately.

The wrong version of translations are used

  • Please make sure that you have the versionName for the app set and are using the format <major>.<minor>.<point>.
  • In Phrase, check whether you do have a release with the latest translations and the current app version. 
Did this answer your question?