Skip to main content

Android apps

easyi18n translates a native Android app through its string resources. The base-language res/values/strings.xml is the source of truth. You add strings to it, and easyi18n writes values-<qualifier>/strings.xml for every other language.

The Android adapter needs CLI 1.0.0 or later.

What init sets up​

init with stack: auto selects Android when the repository has a res/values/strings.xml and either a Gradle script at its root (settings.gradle, build.gradle or their .kts versions) or an AndroidManifest.xml beside the res/ directory. easyi18n init --stack android names it explicitly. Other apps that carry an android/ folder keep their own stack. A Flutter app stays a Flutter project. A web app, such as React Native, Capacitor or Ionic, stays a web project when package.json depends on i18next, @ngx-translate/core or @jsverse/transloco, and an Angular project when it depends on @angular/localize and has an angular.json. To translate that app's strings.xml instead, run easyi18n init --stack android; doctor then checks it as an Android project.

init writes an easyi18n.yaml like this one:

workspace: acme
project: shop
mode: a
format: android_xml
output: app/src/main/res
source: app/src/main/res/values/strings.xml
sourceRoot: app/src/main/res/values

source is the base strings file that sync uploads. output is the res/ directory where the files of the other languages are written. When the repository has several modules, init picks the src/main one and names the others in its output; edit source and output to sync a different module. Android projects always use Mode A.

doctor checks that source exists and is a <resources> file, counts its translatable strings, lists the language files beside it, and fails when format is not android_xml.

How easyi18n reads strings.xml​

  • <string> is a text and <plurals> a plural, one form per quantity.
  • A string marked translatable="false" is not uploaded.
  • <string-array> and other resource types are skipped with a warning.
  • A comment right before a string becomes its description.
  • Escapes such as \', \n and \@ are read the way Android reads them, %1$s placeholders stay as they are, and <xliff:g> spans are kept verbatim so pull writes them back unchanged.
  • The directory names the language: values-es is es, values-zh-rTW is zh-TW and values-b+zh+Hant is zh-Hant. A directory with no language qualifier, such as values-night, is ignored.

Translate and publish​

The agent uses the file-first tools, the same ones an Xcode project uses:

  1. sync_preview uploads the base file as a dry run. It reports the keys the sync would create, the estimated credits, and in language_files the values-<qualifier>/strings.xml files the sync will upload with them.
  2. You approve the spend. sync uploads the base file and queues the translation. Right after it, sync uploads each language file of a target language of the project, so the translations you already have are stored as they are and only the missing ones are translated. A file whose language is not in the project is listed in skipped_language_files and not uploaded.
  3. fill_status polls until the translation is complete.
  4. You approve the publish.
  5. pull writes values-<qualifier>/strings.xml for each target language into output. It never writes values/strings.xml.

From a terminal or CI, easyi18n sync runs those steps in one command, and easyi18n pull downloads the published files.

Edit only the base file and review the other files in the git diff. After the first sync, do not edit a language file: the next pull or sync stops on it with edited_targets until the change is in the dashboard or discarded. Rebuild the app to see the new strings.

Limits​

  • One module per easyi18n.yaml.
  • <string-array> resources are not translated.
  • XLIFF files exported by Android Studio are not supported.