On-device Translation

Last updated: 2023-08-22 07:28
Content overview

Service Introduction

With the support of an on-device model, the on-device translation service can translate text from the source language into the target language when no Internet service is available. Currently, this service supports text in 54 languages. For details, please refer to Languages Supported by Translation.

Use Cases

Similar to the real-time translation service, the on-device translation service can be widely used in scenarios where translation between different languages is required. For example, travel apps can integrate this service to translate road signs and menus in other languages into tourists' native languages, providing more considerate services for them. Different from real-time translation, on-device translation does not require the Internet connection. You can easily use the translation service even if the Internet is disconnected.

Precautions

To use the on-device translation service, you need to download translation models for both the source language and target language.

Development Process

Before app development, you need to make necessary development preparations, configure the Maven repository address for the HMS Core SDK, and integrate the on-device translation SDK.

  1. Set authentication information for your app. For details, please refer to Notes on Using Cloud Authentication Information.
  2. Create a local offline translator. You can create the translator using the MLLocalTranslateSetting class.
    Java
    Kotlin
    Collapse
    Dark theme
    Copy code
    1. // Create an offline translator.
    2. MLLocalTranslateSetting setting = new MLLocalTranslateSetting.Factory()
    3.     // Set the source language code. The ISO 639-1 standard is used. This parameter is mandatory. If this parameter is not set, an error may occur.
    4.     .setSourceLangCode("zh") 
    5.     // Set the target language code. The ISO 639-1 standard is used. This parameter is mandatory. If this parameter is not set, an error may occur.
    6.     .setTargetLangCode("en")
    7.     .create();
    8. final MLLocalTranslator mlLocalTranslator = MLTranslatorFactory.getInstance().getLocalTranslator(setting);
    Collapse
    Dark theme
    Copy code
    1. // Create an offline translator.
    2. val setting = MLLocalTranslateSetting.Factory() // Set the source language code. The ISO 639-1 standard is used. This parameter is mandatory. If this parameter is not set, an error may occur.
    3.          .setSourceLangCode("zh") // Set the target language code. The ISO 639-1 standard is used. This parameter is mandatory. If this parameter is not set, an error may occur.
    4.          .setTargetLangCode("en")
    5.          .create()
    6.  val mlLocalTranslator = MLTranslatorFactory.getInstance().getLocalTranslator(setting)
  3. Query the languages supported by on-device translation.
    • Sample code for calling the asynchronous method:
      Java
      Kotlin
      Collapse
      Dark theme
      Copy code
      1. MLTranslateLanguage.getLocalAllLanguages().addOnSuccessListener(
      2.     new OnSuccessListener<Set<String>>() {
      3.         @Override
      4.         public void onSuccess(Set<String> result) {
      5.             // Languages supported by on-device translation are successfully obtained.
      6.         }
      7. });
      Collapse
      Dark theme
      Copy code
      1. MLTranslateLanguage.getLocalAllLanguages().addOnSuccessListener {     // Languages supported by on-device translation are successfully obtained.
      2. }
    • Sample code for calling the synchronous method:
      Java
      Kotlin
      Collapse
      Dark theme
      Copy code
      1. Set<String> result = MLTranslateLanguage.syncGetLocalAllLanguages();
      Collapse
      Dark theme
      Copy code
      1. val result = MLTranslateLanguage.syncGetLocalAllLanguages()
  4. On-device models can be download in either of the following ways:
    • Method 1: Use MLLocalModelManager to manually download the required model package.
      Java
      Kotlin
      Collapse
      Dark theme
      Copy code
      1. // After the download is successful, translate text in the onSuccess callback.
      2. // Obtain the model manager.
      3. MLLocalModelManager manager = MLLocalModelManager.getInstance();
      4. MLLocalTranslatorModel model = new MLLocalTranslatorModel.Factory(sourceLangCode).create();
      5. // Set the model download policy.
      6. MLModelDownloadStrategy downloadStrategy = new MLModelDownloadStrategy.Factory()
      7.     .needWifi() // It is recommended that you download the package in a Wi-Fi environment.
      8. // Set the site region. Currently, the following values are supported: REGION_DR_CHINA, REGION_DR_GERMAN, REGION_DR_SINGAPORE, and REGION_DR_RUSSIA. (The site region must be the same as the access site selected in AppGallery Connect.)
      9.     .setRegion(MLModelDownloadStrategy.REGION_DR_CHINA)
      10.     .create();
      11. // Create a download progress listener.
      12. MLModelDownloadListener modelDownloadListener = new MLModelDownloadListener() {
      13.     @Override
      14.     public void onProcess(long alreadyDownLength, long totalLength) {
      15.         runOnUiThread(new Runnable() {
      16.             @Override
      17.             public void run() {
      18.                 // Display the download progress or perform other operations.
      19.             }
      20.         });
      21.     }
      22. };
      23. // Download the model. After the model is downloaded, translate text in the onSuccess callback.
      24. manager.downloadModel(model, downloadStrategy, modelDownloadListener).addOnSuccessListener(new OnSuccessListener<Void>() {
      25. @Override
      26.     public void onSuccess(Void aVoid) {
      27.         // Called when the model package is successfully downloaded.
      28.     }
      29. }).addOnFailureListener(new OnFailureListener() {
      30.     @Override
      31.     public void onFailure(Exception e) {
      32.         // Called when the model package fails to be downloaded.
      33.     }
      34. });
      Collapse
      Dark theme
      Copy code
      1. // After the download is successful, translate text in the onSuccess callback.
      2. // Obtain the model manager.
      3. val manager = MLLocalModelManager.getInstance()
      4. val sourceLangCode: String? = null
      5. val model = MLLocalTranslatorModel.Factory(sourceLangCode).create()
      6. // Set the model download policy.
      7. val downloadStrategy = MLModelDownloadStrategy.Factory()
      8.                  .needWifi() // It is recommended that you download the package in a Wi-Fi environment.
      9.                  .create()
      10. // Create a download progress listener.
      11. val modelDownloadListener = MLModelDownloadListener { alreadyDownLength, totalLength ->
      12.        runOnUiThread {
      13.                  // Display the download progress or perform other operations.
      14.              }
      15.          }
      16.          // Download the model. After the model is downloaded, translate text in the onSuccess callback.
      17. manager.downloadModel(model, downloadStrategy, modelDownloadListener).addOnSuccessListener {
      18.              // Called when the model package is successfully downloaded.
      19.      }.addOnFailureListener {
      20.              // Called when the model package fails to be downloaded.
      21.      }
    • Method 2: Use preparedModel to automatically download the required model package.
      Java
      Kotlin
      Collapse
      Dark theme
      Copy code
      1. // Set the model download policy.
      2. MLModelDownloadStrategy downloadStrategy = new MLModelDownloadStrategy.Factory()
      3.     .needWifi() // It is recommended that you download the package in a Wi-Fi environment.
      4.     .create();
      5. // Create a download progress listener.
      6. MLModelDownloadListener modelDownloadListener = new MLModelDownloadListener() {
      7.     @Override
      8.     public void onProcess(long alreadyDownLength, long totalLength) {
      9.         runOnUiThread(new Runnable() {
      10.             @Override
      11.             public void run() {
      12.                 // Display the download progress or perform other operations.
      13.             }
      14.         });
      15.     }
      16. };
      17. mlLocalTranslator.preparedModel(downloadStrategy, modelDownloadListener).
      18.     addOnSuccessListener(new OnSuccessListener<Void>() {
      19.         @Override
      20.         public void onSuccess (Void aVoid){
      21.             // Called when the model package is successfully downloaded.
      22.         }
      23.     }).addOnFailureListener(new OnFailureListener() {
      24.         @Override
      25.         public void onFailure (Exception e){
      26.             // Called when the model package fails to be downloaded.
      27.         }
      28. });
      Collapse
      Dark theme
      Copy code
      1. // Set the model download policy.
      2. val downloadStrategy = MLModelDownloadStrategy.Factory()
      3.          .needWifi() // It is recommended that you download the package in a Wi-Fi environment.
      4.          .create()
      5. // Create a download progress listener.
      6. val modelDownloadListener = MLModelDownloadListener { alreadyDownLength, totalLength ->
      7.     runOnUiThread {
      8.          // Display the download progress or perform other operations.
      9.      }
      10.  }
      11. val mlLocalTranslator: MLLocalTranslator? = null
      12. mlLocalTranslator!!.preparedModel(downloadStrategy, modelDownloadListener).addOnSuccessListener {
      13.      // Called when the model package is successfully downloaded.
      14.  }.addOnFailureListener {
      15.      // Called when the model package fails to be downloaded.
      16. }
  5. Implement translation.
    • Sample code for calling the asynchronous method:
      Java
      Kotlin
      Collapse
      Dark theme
      Copy code
      1. // input is a string of less than 5000 characters.
      2. final Task<String> task = mlLocalTranslator.asyncTranslate(input);
      3. // Before translation, ensure that the models have been successfully downloaded.
      4. task.addOnSuccessListener(new OnSuccessListener<String>() {
      5.     @Override
      6.     public void onSuccess(String s) {
      7.        // Processing logic for detection success.
      8.     }
      9. }).addOnFailureListener(new OnFailureListener() {
      10.     @Override
      11.     public void onFailure(Exception e) {
      12.        // Processing logic for detection failure.
      13.     }
      14. });
      Collapse
      Dark theme
      Copy code
      1. // input is a string of less than 5000 characters.
      2. val input: String? = null
      3.  val task = mlLocalTranslator.asyncTranslate(input)
      4.  // Before translation, ensure that the model is successfully downloaded.
      5. task.addOnSuccessListener {
      6.      // Processing logic for detection success.
      7. }.addOnFailureListener {
      8.      // Processing logic for detection failure.
      9.  }
    • Sample code for calling the synchronous method:
      Java
      Kotlin
      Collapse
      Dark theme
      Copy code
      1. try {
      2.     // input is a string of less than 5000 characters.
      3.     String output = mlLocalTranslator.syncTranslate(input);
      4.     // Processing logic for detection success.
      5. } catch (MLException e) {
      6.     // Processing logic for detection failure.
      7. }
      Collapse
      Dark theme
      Copy code
      1. try {
      2.      // input is a string of less than 5000 characters.
      3.      val output = mlLocalTranslator.syncTranslate(input)
      4.      // Processing logic for detection success.
      5. } catch (e: MLException) {
      6.      // Processing logic for recognition failure.
      7.  }
      NOTICE

      The execution of the synchronous method may take a long time. To avoid slow response and no response, do not directly call the synchronous method in the UI thread.

  6. Delete an unnecessary model package.
    Java
    Kotlin
    Collapse
    Dark theme
    Copy code
    1. // Obtain the model manager.
    2. MLLocalModelManager manager = MLLocalModelManager.getInstance();
    3. MLLocalTranslatorModel model = new MLLocalTranslatorModel
    4.     .Factory("zh") // Set the target language code for the model, which complies with the ISO 639-1 standard.
    5.     .create();
    6. // Delete a model package.
    7. manager.deleteModel(model).addOnSuccessListener(new OnSuccessListener<Void>() {
    8.     public void onSuccess(Void aVoid) {
    9.         // Called when the model package is successfully deleted.
    10.     }
    11. }).addOnFailureListener(new OnFailureListener() {
    12.     @Override
    13.     public void onFailure(Exception e) {
    14.         // Called when the model package fails to be deleted.
    15.     }
    16. });
    Collapse
    Dark theme
    Copy code
    1. // Obtain the model manager.
    2. val manager = MLLocalModelManager.getInstance()
    3.  val model = MLLocalTranslatorModel.Factory("zh") // Set the target language code for the model. The ISO 639-1 standard is used.
    4.          .create()
    5.  // Delete a model package.
    6. manager.deleteModel(model).addOnSuccessListener {
    7.      // Called when the model package is successfully deleted.
    8. }.addOnFailureListener {
    9.      // Called when the model package fails to be deleted.
    10. }
    11. 

    12.
  7. Release resources after the translation is complete.
    Java
    Kotlin
    Collapse
    Dark theme
    Copy code
    1. if (mlLocalTranslator!= null) {
    2.     mlLocalTranslator.stop();
    3. }
    Collapse
    Dark theme
    Copy code
    1. if (mlLocalTranslator != null) {
    2.      mlLocalTranslator.stop()
    3.  }
NOTE

Before downloading an on-device model, you need to understand the download principle and how to use the on-device model. For details, please refer to How to Download and Use an On-device Model.

Search
Enter a keyword.