The plugin overview #️⃣

The plugin has several important functions:

• it integrates tightly with the Android Gradle plugin to understand your project’s structure
• it uploads strings including metadata about flavors, build types, etc. to the translation platform
• it integrates the Localazy Android library into the bytecode of your app so translations can be updated on-the-fly
• while building your app, it replaces app’s resources with updated translations

Also, when the Localazy Android library is integrated into your app, it collects stats to improve translations and to suggests languages you should translate your app into, etc.

No changes to your code #️⃣

We are committed to a simple rule “No changes to your code” which means two important things:

We never touch your source code and resources. No exceptions. All modifications to your app take place during the build process and are applied to intermediate files. The plugin also respects your project’s structure and should work correctly with any project layout, including different product flavors, build types, etc.

No work on your side. Under normal circumstances, there is no extra action needed except for adding the plugin and the Android library to your build scripts. Our defaults are suitable for the majority of apps, and no changes in your source code are needed to have your app translated with Localazy.

As a result, it’s easy to try Localazy out, and you can be sure that your project stays unmodified.

Compatibility #️⃣

The plugin is compatible with native Android apps written with Java, Kotlin and other JVM-based languages.

Your project must be built using Gradle with Android Gradle plugin (com.android.tools.build:gradle), the compatibility list follows:

AGP Version	Notes
3.5.0 - 4.2.2	Fully supported as described in this document.
7.0+	The installation is slightly different, please see the instructions for AGP 7.0+ instead of Quick start below.

If you use Android Studio for building your app, you should be good to go.

Quick start #️⃣

1. Open Android Studio, locate gradle.build file in your project’s root directory and add Localazy repository and Gradle plugin to the buildscript section.

buildscript {

    repositories {
        // ... other repositories ...
        maven { url "https://maven.localazy.com/repository/release/" }
    }

    dependencies {
        // ... other dependencies ...
        classpath "com.localazy:gradle:1.5.4"
    }

}

2. Open gradle.build file in your app’s module and add following snippet a the end of the file:

// Always be sure to add this after android { ... } section
apply plugin: 'com.localazy.gradle'

localazy {
    readKey "the-read-key-for-the-project"
    writeKey "the-write-key-for-the-project"
}

And that’s it! Your app is translated, and translations are updated automatically.

Configure the plugin #️⃣

Our defaults are suitable for the majority of apps, and extra configuration is usually not necessary except for small tweaks (excluding particular strings, disabling errors for debug builds, etc.)

The configuration of the plugin looks like:

localazy {

    readKey "the-read-key-for-the-project"
    writeKey "the-write-key-for-the-project"

    upload {
        // ...
    }

    download {
        // ...
    }

    injection {
        // ...
    }

    resources {
        // ...
    }

}

localazy #️⃣

The localazy section serves as the main configuration and contains all other options related to the plugin.

Name	Type	Default	Description
readKey	string	none	The read key to use for downloading updated translations into the app and for sending stats.
writeKey	string	none	The write key to use for uploading strings for translating.
tag	string	latest	1.5.3+ Define release tag to be used.
addPrefix	boolean	false	Adds prefix [LL] for all strings processed by Localazy OTA engine, so you can verify that the whole app is correctly translated. It’s also useful when developing custom view transformers.
allowAllLibraries	boolean	false	1.3.0+ Enables an experimental support for libraries with different build types and product flavors.
upload	struct	none	Configures string uploading. See upload.
download	struct	none	Configures string downloading. See download.
injection	struct	none	Configures the library injection. See injection.
resources	struct	none	Configures resources injection. See resources.
copyFrom	project	none	Defines another module to copy configuration from. It’s useful for integrating libraries, so you don’t need to define the configuration again. Please keep in mind, that it only copies unchanged values. It doesn’t copy data from the upload section as the upload is always processed by the app’s module only.

Defining keys in local.properties

You can define read and write keys in local.properties, so they are not committed to the version control system.

This is especially useful for open-source software with publicly available repositories.

# Path to Android SDK is typically defined here.
sdk.dir=/home/user/path/to/android

localazy.readKey=your-app-read-key
localazy.writeKey=your-app-write-key

Copying the configuration to library

To apply Localazy correctly to your library modules, you have to include them in the projects of the upload section and apply the Localazy Gradle plugin to them. However, the configuration is not, by default, shared between modules and so you would need to configure the library module again. With the copyFrom option, you can transfer the configuration from your app’s module like this:

apply plugin: 'com.localazy.gradle'

localazy {
    copyFrom project(":app")
}

upload #️⃣

The upload section configures how strings are uploaded from your app to the Localazy platform. The default configuration is suitable for the majority of apps, and under normal circumstances, you don’t need to make any changes.

Name	Type	Default	Description
deprecateMissing	boolean	true	If set to true, strings that are not contained in the batch are marked deprecated.
defaultLang	string	inherited	The language of values folder. Special value inherited means to use the project’s default language as defined in the Localazy platform. The language must be one recognized be the Localazy platform in format xx (eq. cs, en, de) or xx_XX (eq. cs_CZ, en_US).
defaultState	string	current	If set to current, the uploaded string is automatically used as a translation if no translation is available. If set to force_current (1.5.3+), the uploaded string is forced as the current translation even if there is an existing translation. If set to new, uploaded strings are uploaded as non-approved and must go through the review process - this is important if you are not sure of the translation quality.
showUploadAll	boolean	false	If set to true, Gradle tasks uploadAllStrings and uploadBaseStrings are available instead of uploadStrings only.
strictMode	boolean	false	1.4.0+ If set to true, the pre-upload analysis ends with error if there are some possible issues detected.
ignoreMissingDefault	boolean	false	If set to true, the plugin ignores missing default translations in flavors, which may lead to the phrase not appear correctly in the Localazy platform.
ignorePrivateStrings	boolean	false	If set to true, the plugin ignores private strings analysis. By default, Localazy warns you if the string seems to be an ad identifier, etc., and prevents upload.
strings	struct	n/a	Allows to include or exclude string keys in the upload. See strings.
files	struct	n/a	Allows to include or exclude files with strings in the upload. See files.
projects	struct	n/a	Allows to include projects that should be included in the upload. See projects.
analysis	struct	n/a	1.3.0+ Allows to exclude strings from pre-upload analysis. See analysis.
include	struct	n/a	1.4.0+ Allows to manually include strings that are excluded by the analysis. See include.

strings

Allows to include or exclude particular strings from uploading. You can include or exclude strings that match the given pattern, and it’s possible to use wildcard symbols * and ?.

By default, all strings are included except for those that are explicitly excluded here. If at least one include is used, the resolution process is switched to the include-only mode, which means that all strings are excluded by default except for those explicitly included. Excluding has higher a priority than including.

localazy {
    upload {
        strings {

            // Include key_1, apply to all subprojects
            include "key_1"

            // Include key_1 from anotherProject subproject
            include project(":anotherProject"), "key_1"

            // Exclude key_2, apply to all subprojects
            exclude "key_2"

            // Exclude key_2 from anotherProject subproject
            exclude project(":anotherProject"), "key_2"

        }
    }
}

files

Allows to include or exclude particular files from uploading. You can include or exclude files that match the given pattern, and it’s possible to use wildcard symbols * and ?.

By default, all files are included except for those that are explicitly excluded here. If at least one include is used, the resolution process is switched to the include-only mode, which means that all files are excluded by default except for those explicitly included. Excluding has a higher priority than including.

The file path to be matched is in a special format allowing for precise selection of included/excluded resources. The format is flavorName:folder/file.ext, which means that it’s usually something like main:values/strings.xml.

localazy {
    upload {
        files {

            // Include strings_specific.xml from all subprojects, folders and flavors
            include "*/strings_specific.xml"

            // Include strings_specific.xml from flavor free, folder values-v11 and project anotherProject
            include project(":anotherProject"), "free:values-v11/strings_specific.xml"

            // Exclude strings_private.xml, apply to all subprojects, folders and flavors
            exclude "*/strings_private.xml"

            // Exclude strings_private.xml from flavor free, folder values-v11 and project anotherProject
            exclude project(":anotherProject"), "free:values-v11/strings_private.xml"

        }
    }
}

projects

Allows to include extra Gradle projects (modules in Android Studio) when uploading strings. The project/module this configuration is placed inside is always included.

It’s useful to include projects when you need to translate also strings from your libraries, etc.

localazy {
    upload {
        projects {
            include project(":anotherProject")
        }
    }
}

analysis

Allows skipping strings with listed keys from the pre-upload analysis that checks your strings for those that you are likely to exclude from the upload, and those that don’t have default translation.

You can disable the analysis completely using ignoreMissingDefault and ignorePrivateStrings.

It’s possible to use wildcard characters * and ?.

localazy {
    upload {
        analysis {
            skip "key_1"
            skip "key_2"
            skip "key_3"
        }
    }
}

include

Allows manual including of strings that are excluded by the pre-upload analysis because they may contain private or sensitive data.

It’s possible to use wildcard characters * and ?.

localazy {
    upload {
        include {
            string "key_1"
            string "key_2"
            string "key_3"
        }
    }
}

download #️⃣

The download section tells the plugin on how to download data and how to behave if data or the internet connection is not available. The downloaded data are cached and used when building the app.

Name	Type	Default	Description
enabledForRelease	boolean	true	If set to true, download new strings from Localazy for release builds.
enabledForDebug	boolean	true	If set to true, download new strings from Localazy for debug builds.
errorOnFailureRelease	boolean	true	If set to true, fail if data cannot be downloaded for release builds. If false, silently ignore the problem and show a warning. We strongly discourage you from settings this option to false!
errorOnFailureDebug	boolean	true	If set to true, fail if data cannot be downloaded for debug builds. If false, silently ignore the problem and show a warning.
redownloadInterval	long	3600	Configures how often to re-download data from Localazy in seconds. The minimum is 900 seconds.

injection #️⃣

The injection section allows you to configure how the Android library is integrated into your app.

Name	Type	Default	Description
enabledForRelease	boolean	true	If set to false, the code injection of the Android library is disabled for release builds.
enabledForDebug	boolean	true	If set to false, the code injection of the Android library is disabled for debug builds.
library	string	androidx	1.3.0+ Automatically adds the Localazy Android library as dependency. Allowed values are none (don’t add library), androix (add AndroidX version), plain (add plain Android version), support (add version with the legacy support libraries).
installRepositories	boolean	true	1.5.0+ Do not add Localazy repository automatically. It’s important if you want to have repositories defined in settings.gradle.
dontUpdateForDebug	boolean	false	1.2.1+ If set to true, OTA updates and stats collecting is disabled for the development/debug builds.
dontCheckInternetPermission	boolean	false	1.3.0+ If set to true, the plugin doesn’t check whether INTERNET permission is granted to the app.
updateInterval	int	86400	1.2.0+ How often to check for new translations in seconds. Minimal value is 3600.
updateIntervalForFailure	int	14400	1.2.0+ How often to check for new translations in seconds if the previous request failed. Minimal value is 900.
updateDelay	int	0	1.2.0+ How many seconds to delay the first check for new translations. By settings this value, you can filter out users that install the app and remove it almost immediately.
statsInterval	int	86400	1.2.0+ How often to send collected stats to our servers. Minimal value is 900.
statsIntervalForFailure	int	14400	1.2.0+ How often to send collected stats to our server if the previous request failed. Minimal value is 900.
statsDelay	int	300	1.2.0+ How many seconds to delay the first sending of collected stats. By settings this value, you can filter out users that install the app and remove it almost immediately.
minimalStatsSize	int	2048	1.2.0+ Defines the minimal size of the collected stats package before it’s sent to our servers in bytes. Keep this small to receive stats from users.
maximalStatsSize	int	262144	1.2.0+ Defines the maximal size of the file for collecting stats. There are three files for stats, so Localazy needs storage equal to 3 x maximalStatsSize. If the maximal size is reached, stats are no longer collected until successfully sent to our servers.
updateForActivityOnly	boolean	true	1.2.0+ If set to true, translations are only updated when Activity is shown. It prevents unwanted updates (and lower the number of DAU requests) from background services and receivers.
sendStatsRegularly	boolean	false	1.2.0+ If set to true, collected stats are sent to our servers periodically. If set to false, collected stats are only sent after a translation update request (no matter if translations were updated or not). It prevents too many requests to our servers and thus lowers the number of DAU requests (and your price). If set to false, statsInterval, statsIntervalForFailure and statsDelay are ignored.
enableApplicationTransform	boolean	false	If set to true, the code injection is applied also to subclasses of android.app.Application. This is generally not needed and there are known issues with Firebase when enabled. Enable this only if you really need it.
exclude	method	n/a	Allows excluding classes from the injection process. See exclude.
installRepositories	boolean	true	1.3.0+ Automatically install Localazy repository to all subprojects of the root project, so you don’t need to do so manually.
loyalUsersOnly	method	n/a	1.3.0+ Call this method to set updateInterval, updateIntervalForFailure, updateDelay and other options to values suitable for delivering updates to only long-term loyal users.

exclude

The injection process modifies the bytecode of produced class files. You can exclude classes for which the injection process is undesired. To exclude class, you specify its fully qualified name or use wildcard * for a single path segment or ** for everything.

It’s normally not necessary to exclude classes, and you shouldn’t do so unless there is a good reason for it.

localazy {
    injection {

        // Exclude class com.localazy.test.Class1
        exclude "com.localazy.test.Class1"

        // Exclude any class in package com.localazy.test but NOT in subpackages
        exclude "com.localazy.test.*"

        // Exclude any class in package com.localazy.test and all subpackages
        exclude "com.localazy.test.**"

        // Exclude class Class1 in any package
        exclude "**.Class1"

        // Define more rules with a single line
        exclude "package.Class1", "package.Class2", "package.Class3"

    }
}

resources #️⃣

With Localazy, you don’t need to download XML files manually. The plugin overwrites all strings in your app with the most recent version from the translation platform. It also adds languages that are available in Localazy but not in your app.

It never changes your source code nor your XML resources. All changes take place during the compilation only while the Android Gradle plugin merges resources.

The resources section configures how your resources are updated with new translations.

Name	Type	Default	Description
enabledForRelease	boolean	true	If set to true, your string resources are automatically merged with new strings from Localazy for release builds.
enabledForDebug	boolean	true	If set to true, your string resources are automatically merged with new strings from Localazy for debug building.
failOnMissingDataRelease	boolean	true	If set to true, the build process fails if data are missing and cannot be merged with release builds. If false, resources are not updated, and this step is silently skipped. We strongly discourage you from settings this option to false!
failOnMissingDataDebug	boolean	true	If set to true, the build process fails if data are missing and cannot be merged with debug builds. If false, resources are not updated, and this step is silently skipped.

Uploading strings #️⃣

When the plugin is configured, new Gradle tasks are available for uploading strings to the translation platform.

uploadStrings #️⃣

When used for the first time / in a new project, upload strings in all languages for translation.

Subsequent uses upload only changes to the base language as all future changes to strings should be made only to the base language.

This task uses hidden .localazy file in the project directory to store state information.

uploadBaseStrings #️⃣

Upload strings in the base language for translation.

For the first time, you should upload your strings in all languages with uploadAllStrings. Then, do changes to the base language only and use this task to upload changes for translation.

uploadAllStrings #️⃣

Upload strings in all languages for translation.

This should be used only for the first time. In the future, you should add new strings to the base language only and upload changes with uploadBaseStrings.

Links #️⃣

Frequently asked questions - Learn more about advanced topics related to Localazy Gradle plugin.

Localazy Android library - Dive deeper into the magic; there’s more you can do with Localazy.

What you should know before uploading strings - Learn more about key aspects to consider if you are serious about translating your app.