Skip to content

translation

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

translation

README.md

Capacitor ML Kit Translation Plugin

Unofficial Capacitor plugin for ML Kit Translation.1

Use Cases

The Translation plugin is typically used to translate text directly on the device, for example:

  • Chat translation: Translate incoming messages into the language of the user.
  • Content translation: Let users translate user-generated content such as comments, reviews, or posts.
  • Offline translation: Download language models in advance so users can translate text without an internet connection.
  • Travel apps: Help travelers translate text on the go, even when roaming without a data connection.

Compatibility

Plugin Version Capacitor Version Status
8.x.x >=8.x.x Active support
7.x.x 7.x.x Deprecated
6.x.x 6.x.x Deprecated
5.x.x 5.x.x Deprecated

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-mlkit/translation` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capacitor-mlkit/translation
npx cap sync

Attention: This plugin only supports CocoaPods for iOS dependency management. Swift Package Manager (SPM) is not supported for the ML Kit SDK, see this comment.

Android

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

  • $mlkitTranslateVersion version of com.google.mlkit:translate (default: 17.0.3)

This can be useful if you encounter dependency conflicts with other plugins in your project.

iOS

Minimum Deployment Target

Make sure to set the deployment target in your ios/App/Podfile to at least 15.5:

platform :ios, '15.5'

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-mlkit-plugin-demo

Usage

The following examples show how to translate a text, download a language model, list the downloaded language models, and delete a downloaded language model.

Translate a text

Use the translate(...) method to translate a text from a source language to a target language. If the language model for the given languages is not downloaded yet, it will be downloaded automatically, which may take some time. Only available on Android and iOS:

import { Translation, Language } from '@capacitor-mlkit/translation';

const translate = async () => {
  const { text } = await Translation.translate({
    text: 'Good morning!',
    sourceLanguage: Language.English,
    targetLanguage: Language.German,
  });
  return text;
};

Download a language model

Download a language model in advance to enable offline translation. Language models are around 30MB in size, so be sure to only download the models you need and only download them using a WiFi connection unless the user has specified otherwise. Only available on Android and iOS:

import { Translation, Language } from '@capacitor-mlkit/translation';

const downloadModel = async () => {
  await Translation.downloadModel({
    language: Language.English,
  });
};

List the downloaded language models

Get the languages for which a model has already been downloaded to the device. Only available on Android and iOS:

import { Translation } from '@capacitor-mlkit/translation';

const getDownloadedModels = async () => {
  const { languages } = await Translation.getDownloadedModels();
  return languages;
};

Delete a downloaded language model

Delete the language model for a given language, for example to free up storage space on the device. Only available on Android and iOS:

import { Translation, Language } from '@capacitor-mlkit/translation';

const deleteDownloadedModel = async () => {
  await Translation.deleteDownloadedModel({
    language: Language.English,
  });
};

API

deleteDownloadedModel(...)

deleteDownloadedModel(options: DeleteDownloadedModelOptions) => Promise<void>

Delete the language model for the given language.

Only available on Android and iOS.

Param Type
options DeleteDownloadedModelOptions

Since: 0.0.1

downloadModel(...)

downloadModel(options: DownloadModel) => Promise<void>

Download a language model for offline translation.

Language models are around 30MB in size, so be sure to only download the models you need and only download them using a WiFi connection unless the user has specified otherwise.

Only available on Android and iOS.

Param Type
options DownloadModel

Since: 0.0.1

getDownloadedModels()

getDownloadedModels() => Promise<GetDownloadedModelsResult>

Get the languages for which a model has been downloaded.

Only available on Android and iOS.

Returns: Promise<GetDownloadedModelsResult>

Since: 0.0.1

translate(...)

translate(options: TranslateOptions) => Promise<TranslateResult>

Translate the given text.

If the language model for the given source and target languages is not downloaded, it will be downloaded automatically which may take some time. If you want to avoid this, use the downloadModel(...) method to download the model first.

Only available on Android and iOS.

Param Type
options TranslateOptions

Returns: Promise<TranslateResult>

Since: 0.0.1

Interfaces

DeleteDownloadedModelOptions

Prop Type Description Since
language Language The language for which to delete the model. 0.0.1

DownloadModel

Prop Type Description Since
language Language The language to download the model for. 0.0.1

GetDownloadedModelsResult

Prop Type Description
languages Language[] The languages for which a model has been downloaded.

TranslateResult

Prop Type Description Since
text string The translated text. 0.0.1

TranslateOptions

Prop Type Description Since
text string The text to translate. 0.0.1
sourceLanguage Language The source language of the text. If you don't know the source language, you can use the Language</a> Identification plugin to detect it. 0.0.1
targetLanguage Language The target language to translate the text to. 0.0.1

Enums

Language

Members Value Since
Afrikaans 'af' 0.0.1
Arabic 'ar' 0.0.1
Belarusian 'be' 0.0.1
Bulgarian 'bg' 0.0.1
Bengali 'bn' 0.0.1
Catalan 'ca' 0.0.1
Czech 'cs' 0.0.1
Welsh 'cy' 0.0.1
Danish 'da' 0.0.1
German 'de' 0.0.1
Greek 'el' 0.0.1
English 'en' 0.0.1
Esperanto 'eo' 0.0.1
Spanish 'es' 0.0.1
Estonian 'et' 0.0.1
Persian 'fa' 0.0.1
Finnish 'fi' 0.0.1
French 'fr' 0.0.1
Irish 'ga' 0.0.1
Galician 'gl' 0.0.1
Gujarati 'gu' 0.0.1
Hebrew 'he' 0.0.1
Hindi 'hi' 0.0.1
Croatian 'hr' 0.0.1
Haitian 'ht' 0.0.1
Hungarian 'hu' 0.0.1
Indonesian 'id' 0.0.1
Icelandic 'is' 0.0.1
Italian 'it' 0.0.1
Japanese 'ja' 0.0.1
Georgian 'ka' 0.0.1
Kannada 'kn' 0.0.1
Korean 'ko' 0.0.1
Lithuanian 'lt' 0.0.1
Latvian 'lv' 0.0.1
Macedonian 'mk' 0.0.1
Marathi 'mr' 0.0.1
Malay 'ms' 0.0.1
Maltese 'mt' 0.0.1
Dutch 'nl' 0.0.1
Norwegian 'no' 0.0.1
Polish 'pl' 0.0.1
Portuguese 'pt' 0.0.1
Romanian 'ro' 0.0.1
Russian 'ru' 0.0.1
Slovak 'sk' 0.0.1
Slovenian 'sl' 0.0.1
Albanian 'sq' 0.0.1
Swedish 'sv' 0.0.1
Swahili 'sw' 0.0.1
Tamil 'ta' 0.0.1
Telugu 'te' 0.0.1
Thai 'th' 0.0.1
Tagalog 'tl' 0.0.1
Turkish 'tr' 0.0.1
Ukrainian 'uk' 0.0.1
Urdu 'ur' 0.0.1
Vietnamese 'vi' 0.0.1
Chinese 'zh' 0.0.1

FAQ

Which platforms are supported by this plugin?

The plugin is available on Android and iOS. All methods are only available on Android and iOS, so there is no web implementation.

Which languages are supported?

The plugin supports more than 50 languages, including English, German, Spanish, French, Chinese, and Japanese. See the Language enum in the API section for the complete list.

Does the translation work offline?

Yes, the translation is performed on the device using downloaded language models. Use the downloadModel(...) method to download a language model in advance, for example while the device is connected to a WiFi network. Otherwise, the model is downloaded automatically on the first call to translate(...), which may take some time.

How much storage do the language models require?

Language models are around 30MB in size, so be sure to only download the models you need. You can delete a model that is no longer needed using the deleteDownloadedModel(...) method.

What if I don't know the source language of the text?

The translate(...) method requires a source language. You can use the ML Kit Language Identification plugin to detect the language of a text before translating it.

Can I install this plugin using Swift Package Manager?

No, this plugin only supports CocoaPods for iOS dependency management because the ML Kit SDK itself does not support Swift Package Manager. Also make sure to set the deployment target in your ios/App/Podfile to at least 15.5 (see Installation).

Related Plugins

  • Speech Recognition: Transcribe speech into text, for example to translate it afterwards.
  • Speech Synthesis: Synthesize speech from text, for example to read translated text aloud.
  • App Language: Manage the app's own language override, independent of the device language.

Terms & Privacy

This plugin uses the Google ML Kit:

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

Footnotes

  1. This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. ↩