Skip to main content

Android (Kotlin)

The translate-projects-android Gradle plugin adds the ./gradlew translateProjects task: it reads res/values/strings.xml, translates the texts into each language you configure, and writes values-<language>/strings.xml.

In development

The plugin is not published yet. The version and final installation steps will be completed when it is released on the Gradle Plugin Portal.

Requirements​

  • An Android project with Gradle and the Kotlin DSL (build.gradle.kts).
  • JDK 17 or later to run Gradle.
  • A Translate Projects project and an API token. See Getting started.

1. Install the plugin​

Add the plugin to the build.gradle.kts of the app module:

app/build.gradle.kts
plugins {
    id("com.android.application")
    id("dev.translateprojects.android") version "VERSION"
}

The plugin is downloaded from the Gradle Plugin Portal, which is already in the default repositories (gradlePluginPortal() in settings.gradle.kts).

2. Configure the plugin​

app/build.gradle.kts
translateProjects {
    sourceLang = "es"
    targetLangs = listOf("en", "pt-BR", "fr")
    apiKey = providers.environmentVariable("TRANSLATE_PROJECTS_API_KEY")
}
OptionRequiredDescription
sourceLangYesLanguage of res/values/strings.xml. It must be the project's default language.
targetLangsYesTarget languages, using the API codes (en, pt-BR, zh-Hans).
apiKeyYesProject API token. Read it from an environment variable, never write it in the file.

3. Write your texts​

Write the texts in the base language in res/values/strings.xml, as in any Android app:

app/src/main/res/values/strings.xml
<resources>
    <string name="app_name" translatable="false">Ruteo</string>
    <string name="welcome">Hola, %1$s</string>
    <string name="login_button">Iniciar sesión</string>
    <plurals name="routes_count">
        <item quantity="one">%d ruta</item>
        <item quantity="other">%d rutas</item>
    </plurals>
    <string-array name="days">
        <item>Lunes</item>
        <item>Martes</item>
    </string-array>
</resources>

4. Translate​

Terminal
export TRANSLATE_PROJECTS_API_KEY=tu_token
./gradlew translateProjects

Files it generates​

app/src/main/res/
├── values/strings.xml          ← base language, not modified
├── values-en/strings.xml
├── values-pt-rBR/strings.xml   ← pt-BR uses the Android format
└── values-fr/strings.xml

The name of each text is its key in Translate Projects, so you can review and edit the translations in the panel.

What it respects​

  • Placeholders (%1$s, %d, %2$.2f) are kept intact.
  • plurals and string-array are translated item by item and keep their structure.
  • Texts with translatable="false" are not sent or copied to the other languages.
  • Apostrophes and quotes are escaped as Android requires (\', \"), and CDATA and basic HTML (<b>, <i>, <u>) are preserved.

Cache​

A second run without new texts makes two requests and translates nothing. If someone corrects a translation in the Translate Projects panel, the next run downloads it without --force; your manual edits in the file still take priority. More details in Cache and errors.

Common errors​

  • Missing token: export TRANSLATE_PROJECTS_API_KEY in the same terminal (or as a secret in CI) before running Gradle.
  • Invalid token (Token no válido): copy the project token again. Existing strings.xml files are not touched.
  • The source language is not the default: sourceLang must be the project's default language.
  • Missing AI key (MISSING_API_KEY): configure the provider, the model and the key in the project; missing strings are retried on the next run.
  • Partial translation, 5xx or network errors: incomplete languages are requested again on the next run.
Free

🚀 Automate your translations for free​

Translate Projects is free. You create your project, connect your AI provider's key, and only pay them what you spend.

  • No plans or credit card required: All features are available from day one.
  • Use your own AI: Claude, OpenAI, DeepSeek, or Gemini. Your key is stored encrypted.
  • Shared translation network: If a text has already been translated, you receive it instantly without spending your key.
  • Admin panel: Review and edit all your translations from one place.

Create free account →

Support

We're here to help​

If you have any questions, need help, or want to contribute, don't hesitate to contact me. I'm available to support you with whatever you need.

Support the Project​

If this project has been helpful to you, I invite you to buy me a coffee. Your support helps me keep improving and creating valuable content. Thanks for being here! ☕

Buy me a coffee