Home

Awesome

android-gradle-localization-plugin

Maven Central Bintray Android Arsenal Build Status codecov

Gradle plugin for generating localized string resources

Overview

This plugin generates Android string resource XML files from CSV or XLS(X) file. Generation has to be invoked as additional gradle task. Java 1.8 is required.

Supported features

Applying plugin

Gradle 2.1+

In whichever build.gradle file.

plugins {
  id 'pl.droidsonroids.localization' version '1.0.19'
}

Note: exact version number must be specified, + cannot be used as wildcard.

All versions of Gradle

  1. Add dependency to the top-level build.gradle file.
 buildscript {
    repositories {
        mavenCentral()
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.3'
        classpath 'pl.droidsonroids.gradle.localization:android-gradle-localization-plugin:1.0.19'
    }
}

Note: mavenCentral() and/or jcenter() repository can be specified, + can be used as wildcard in version number.

  1. Apply plugin and add configuration to build.gradle of the application, eg:
apply plugin: 'pl.droidsonroids.localization'

Usage

Invoke localization gradle task. Task may be invoked from commandline or from Android Studio GUI.

Non existent folders will be created. WARNING existing XML files will be overwritten.

Example

The following CSV file:

name,default    ,pl       ,comment   ,translatable
file,File       ,"Plik"   ,file label,
app ,Application,,,false

will produce 2 XML files:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="file">File</string><!-- file label -->
  <string name="app" translatable="false">Application</string>
</resources>

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="file">Plik</string><!-- file label -->
</resources>

Configuration

Add localization extension in build.gradle of particular module.

localization {
        csvFile=file('translations.csv')
        OR
        csvFileURI='https://docs.google.com/spreadsheets/d/<key>/export?format=csv'
        OR
        csvGenerationCommand='/usr/bin/xlsx2csv translation.xlsx'
        OR
        xlsFile=file('translations.xlsx')
        OR
        xlsFileURI='https://docs.google.com/spreadsheets/d/<key>/export?format=xlsx'
}

Sources, exactly one of them must be specified:

Spreadsheet format:

If both nameColumnIndex and nameColumnName are specified exception is thrown.

The following options turn off some character escaping and substitutions, can be useful if you have something already escaped in source:

(X)HTML tags escaping

CSV format:

XLS(X) format:

Advanced options:

Migration from versions < 1.0.19

Since version 1.0.19 completely empty (effectively empty in case of XLS(X)) rows and columns are ignored. Moreover if qualifier (usually language code) is empty exception is thrown. Previously behavior in such cases was undefined.

Migration from versions < 1.0.13:

Obsolete, non-scoped localization plugin id is no longer supported. The only valid id is pl.droidsonroids.localization.

Migration from versions < 1.0.7:

Versions older than 1.0.7 provided escapeBoundarySpaces option, which defaulted to true. Currently strings are always escaped when corresponding parsed cell contains leading or trailing spaces, but such spaces are stripped by default CSV strategy. So effectively strings are trimmed by default. If you want to include mentioned spaces in output set appropriate csvStrategy.

License

MIT License<br> See LICENSE file.