Guides

Integration

1. Add Linguist to your app

Make sure you have jcenter maven repository in your config.

In root of your project build.gradle

allprojects {
    repositories {
        jcenter()
    }
}

Add Linguist dependency in your module's build.gradle

dependencies {
    ...
    compile 'mobi.klimaszewski.linguist.sdk.android:linguist:2.0'
}

2. Configure Linguist

  • Implement Translatable interface in your class extending Application
  • in onCreate() method initialise Linguist
    • call setAutoTranslatedLanguages to define Languages that you are will/did translate in Linguist Services
    • call setSupportedLanguages to define languages that your app already supports and don't need automatic translation
    • call addStrings to provide app string class, which will be used to fetch resources. Keep in mind that R.string.class will contain all merged string resources of your app and any library you use
    • call excludeStrings to remove strings that you don't need to translate, eg. from support library.
    • call build to apply all the changes and build options, which will be used to configure Linguist
Options options = new Options.Builder(this, Language.English)
        .setAutoTranslatedLanguages(Language.values())
        .setSupportedLanguages(Language.Polish)
        .addStrings(R.string.class)
        .excludeStrings(android.support.v7.appcompat.R.string.class)
        .build();
linguist = Linguist.init(options);
    • Since Android O, context needs to be wrapped in order to force different language
@Override
protected void attachBaseContext(Context newBase) {
    super.attachBaseContext(Linguist.wrap(newBase));
}
    • In your activity onResume call showTranslationHint to show pop-up for user to switch from default locale to translated one. You can show the hint for the user only once by using return value of this method.
...
@Override
protected void onResume() {
    super.onResume();
    Linguist linguist = Linguist.get(this);
    if (!isTranslationHintShown) {
        isTranslationHintShown = linguist.showTranslationHint(this);
    }
}

Example:

public class App extends Application implements Translatable {

    private Linguist linguist;

    @Override
    public Linguist getLinguist() {
        return linguist;
    }

    @Override
    public void onCreate() {
        super.onCreate();
        Options options = new Options.Builder(this, Language.English)
                .setAutoTranslatedLanguages(Language.values())
                .setSupportedLanguages(Language.Polish)
                .addStrings(R.string.class)
                .excludeStrings(android.support.v7.appcompat.R.string.class)
                .build();
        linguist = Linguist.init(options);
    }
}
...
public class MainActivity extends AppCompatActivity {

    private boolean isTranslationHintShown;

    @Override
    protected void attachBaseContext(Context newBase) {
        super.attachBaseContext(Linguist.wrap(newBase));
    }

    ...

    @Override
    protected void onResume() {
        super.onResume();
        Linguist linguist = Linguist.get(this);
        if (!isTranslationHintShown) {
            isTranslationHintShown = linguist.showTranslationHint(this);
        }
    }
}

Optional

Linguist finds non-translatable strings by comparing app default language and one of supported languages. However if your app has only one language, then you may need to exclude strings you don't want to translate by hand eg. links or hash-codes from different frameworks.

Example of app using firebase, google services and links

.excludeString(R.string.app_name, R.string.default_web_client_id, R.string.firebase_database_url, R.string.gcm_defaultSenderId, R.string.google_api_key, R.string.google_app_id, R.string.google_crash_reporting_api_key, R.string.google_storage_bucket, R.string.project_id, R.string.google_play_url, R.string.url_help, R.string.firebase_database_url, R.string.google_app_id, R.string.google_api_key, R.string.google_storage_bucket)

3. Install Linguist Services

All your translations are stored within Linguist Services. Thanks to that you can re-use them to translate your other applications.

4. Generate translations in simple 3 steps

Before you start, preview the strings to translate and confirm that Linguist is set up as you wish.

  1. Pick languages you would like to generate translations to

2. Press Translate button to start translations

3. Press Export to send translations from the application to eg. your email or Google Drive, unzip the package and apply new resources to your project as you would with any other string resources.

See full example on GitHub