Translator Local Feature works on the most recent version of the Microsoft Translator Android App. It allows developers to add translation capabilities to their apps, utilizing the Translator app already installed on a user device. If the user has language packs downloaded, the translations may also be done offline.

Note: The Local feature is in Preview mode. Please do not use it for any production purposes.

How to get started with the Microsoft Translator local feature:

1. Sign up for a free subscription to the Microsoft Translator text API. Learn more
2. Use the documentation below and the sample app to learn how to add online and offline translation to your Android app.
3. Start coding!

The Local Feature is still very simple -- it currently only allows for text translation.

There are only a few methods:

• Start and stop the service
• Get a list of supported Languages
• Perform a text translation from language A to language B
• Initialize offline engines for better performance

The translatorlocal library included in this repository contains the necessary classes to use the Local Feature. There is also a sample app in the app folder.

com.microsoft.translator.local.Translator is the main class for interfacing with the feature.

1. Sign up for your API key at the link above in the Get Started section

2. Check that the Translator app is installed by calling init() it should return Translator.ERROR_NONE if a version of the app that supports the feature is installed.

3. Start the service by calling start() and check for Translator.ERROR_NONE. If another value is returned, the Translator app may not have been installed on the user device, or may not support the Local Feature.

4. Check that the service is connected with isConnected()

5. Use getLanguageList to get a list of languages to translate to and from. The code field corresponds to the language codes you will need for translate. These are language codes like en for English, and es for Spanish. If the user has the offline language pack downloaded for a certain language, the isOnDevice flag will be true. You can use the nativeName to get the language in its native text, or name to get the name in the devices current locale. ( A cached list of languages will be used if the user is offline. )

6. Perform a translation with the translate method. providing your API key, a category (leave blank for now), the language codes for the to and from languages, and a list of Strings to translate.

The getLanguageList and translate methods are synchronous and may take some time to perform, so they should be done on a background thread.

Here is a simple call flow to perform a translation:

// check if Translator is available

int result = Translator.init(context);
if (result != Translator.ERROR_NONE) {
    // Translator isn't installed or version is unsupported
    return;
}

// set your api key
String API_KEY = "";

// start the service
Translator.start(context, null);

// you may need to delay before isConnected returns true

if (Translator.isConnected()) {
    // get the list of available languages
    LanguageListResult languageResult = Translator.getLanguageList();

    if (!languageResult.isError()) {
        ArrayList<String> texts = new ArrayList<>();
        texts.add("Hello World!");
        
        // perform a translation
        TextTranslationResult textResult = Translator.translate(API_KEY, null, "en", languageResult.getLanguages().get(0).code, texts);
    
        if (!textResult.isError()) {
            System.out.println("Got result: " + textResult.getData().get(0));
        } else {
            System.out.println("Got error: " + textResult.errorMessage);
        }
    }
}

//stop the service when you are finished using it.
Translator.stop();

There is a sample app provided in the app folder of this repository to play around with the API.

You will need to provide your own API key at final String API_KEY = ""; in MainActivity.java