LokaliseGradlePlugin

A Gradle plugin that can up- and downloads strings from lokalise.

Usage

Apply the plugin

Add the plugin to the build.gradle[.kts] file:

plugins {
    id("com.ioki.lokalise") version "[CURRENT_VERSION]"
}

Configuration

After you applied the plugin, you have access to the lokalise extension. You need to set up the apiToken as well as the projectId there:

lokalise {
    apiToken.set(providers.environmentVariable("LOKALISE_API_TOKEN"))
    projectId.set(providers.environmentVariable("LOKALISE_PROJECT_ID"))
}

Upload configuration

To configure the upload you can use the lokalise.uploadStringsConfig function:

val filesToUpload = provider {
  fileTree(rootDir) {
    include("**/values/strings.xml")
    exclude("**/build/**")
  }
}
lokalise {
    uploadStringsConfig {
        translationsFilesToUpload.set(filesToUpload)
        params = mapOf(
          "replace_modified" to true,
          "cleanup_mode" to true,
          "distinguish_by_file" to true,
          "lang_iso" to "en_BZ",
        )
    }    
}

The plugin provides a uploadTranslations task that uses the configuration you upload the given translation files. Which parameter you can use can be found in the Lokalise API documentation "Upload a file".

Download configuration

To configure the download you can use the lokalise.downloadStringsConfigs function. Be note that, in contrast to the upload config, you can create multiple download configurations:

lokalise {
    downloadStringsConfigs {
        register("main") {
            arguments = listOf(
                "--format", "xml",
                "--filter-langs", "en,de,de_CH,fr_CH,es,it,nl,ca,ar",
            )
        }
    }
}

The lokalise.downloadStringsConfigs function is a NamedDomainObjectContainer that configured a DownloadStringsConfig. Which parameter you can use can be found in the Lokalise API documentation "Download files". Each of the created configurations will create a Gradle tasks named like the following:

downloadTranslationsFor[name]

Mostly you don't need registering more than one. But you can register multiple ones in case you want to download only a subset of strings for a specific use case. For example, if you only want to download spanish strings you can do this:

downloadStringsConfigs {
    register("main") {
        arguments = listOf(
            "--format", "xml",
            "--filter-langs", "en,de,de_CH,fr_CH,es,it,nl,ca,ar",
        )
    }
    register("spanishOnly") {
        arguments = listOf(
            "--format", "xml",
            "--filter-langs", "es",
        )
    }
}

This will generate two tasks: downloadTranslationsForMain and downloadTranslationsForSpanishhOnly. If you run the latter, it will only download the translated strings for spanish.

There is also an downloadTranslationsForAll task that aggregates all created tasks to run all of them together.

Optional, you can set to each download config the boolean checkTranslationProcess to true. If enabled, it will check if everything is translated on Lokalise before downloading the strings. If set, and it is not translated by 100%, the build will fail. This is quite useful on CI pipelines to make sure that you don't ship half translated apps before starting a heavy build/lint task.

You can set this property like this:

lokalise {
    downloadStringsConfigs {
        register("main") {
            checkTranslationProcess = true
        }
    }
}

Polling configuration (optional, default true)

By default, the plugin will poll the Lokalise API until the upload is finished. This is helpful to catch errors with the uploaded files.

However, if you want to disable this behaviour you can set the pollUploadProcess property to false:

lokalise {
  pollUploadProcess.set(false)
}

Release

Snapshot release

By default, each merge to the main branch will create a new SNAPSHOT release. If you want to use the latest and greatest use the SNAPSHOT version of the plugin. But please be aware that they might contain bugs or behaviour changes.

To use the SNAPSHOT version you have to include the sonatype snapshot repository to your settings.gradle[.kts]

pluginManagement {
    repositories {
        maven(url = "https://central.sonatype.com/repository/maven-snapshots/")
    }
}

Proper release

• Checkout main branch
• Update the version in build.gradle.kts
• Update the version in the instrumentation test consuming of plugin publication via mavenLocal works
• Commit with message Prepare next relaese
• Tag the version with the same version and push
  • git tag [VERSION]
  • git push origin [VERSION]
• Update the version in build.gradle.kts to the next patch version +-SNAPSHOT
• Update the version in the instrumentation test consuming of plugin publication via mavenLocal works
• Commit and push
• Create a new release