android-gradle-localization-plugin

Gradle plugin for generating localized string resources

Overview

This plugin generates Android string resource XML files from CSV file. Generation has to be invoked as additional gradle task.

##Supported features

• non-translatable resources - translatable="false" XML attribute
• auto-escaping double quotes, apostrophes and newlines
• auto-quoting leading and trailing spaces
• syntax validation - duplicated, empty, invalid names detection
• comments

Applying plugin

Gradle 2.1+

In whichever build.gradle file.

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

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:0.14.+'
        classpath 'pl.droidsonroids.gradle.localization:android-gradle-localization-plugin:1.0.7'
    }
}

Note: mavenCentral() and/or jcenter() repository can be specified, + can be used as wildcard in version number. 2. Apply plugin and add configuration to build.gradle of the application, eg:

apply plugin: 'pl.droidsonroids.localization'

Configuration

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

csvFileURI can be any valid URI, not necessarily Google Docs' one

Usage

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

• from commandline: ./gradlew localization (or gradlew.bat localization on Windows)
• from GUI: menu View->Tool Windows->Gradle and double click localization
  

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:

• values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
  <string name="file">File</string><!-- file label -->
  <string name="app" translatable="false">Application</string>
</resources>

• values-pl/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
  <string name="file">Plik</string><!-- file label -->
</resources>

##Configuration localization extension in build.gradle can contain several configuration options. All of them except CSV source are optional and has reasonable default values.
CSV source. Exactly one of them must be specified:

• csvFile - CSV File, Gradle's file() can be used to retrieve files by path relative to module location or absolute
• csvFileURI - CSV file URI
• csvGenerationCommand - shell command which writes CSV as text to standard output. Command string should be specified like for Runtime#exec(). Standard error of the command is redirected to the standard error of the process executing gradle, so it could be seen in the gradle console.

CSV format:

• defaultColumnName - default='default', column name which corresponds to default localization (values folder)
• csvStrategy - default=null (library default strategy, equivalent of CSVStrategy.DEFAULT_STRATEGY)

• see CSVStrategy javadoc, and sources since documentation is quite incomplete

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

• escapeApostrophes - default=true, if set to false apostrophes (') won't be escaped
• escapeQuotes - default=true, if set to false double quotes (") won't be escaped
• escapeNewLines - default=true, if set to false newline characters won't be escaped
• convertTripleDotsToHorizontalEllipsis - default=true, if set to false triple dots (...) won't be converted to ellipsis entity &#8230
• escapeSlashes - default=true, if set to false slashes (\) won't be escaped
• normalizationForm - default=Normalizer.Form.NFC if set to null Unicode normalization won't be performed, see (javadoc of Normalizer)[http://docs.oracle.com/javase/8/docs/api/java/text/Normalizer.Form.html#NFC] for more details
• tagEscapingStrategy - default=IF_TAGS_ABSENT, defines X(H)TML tag brackets (< and >) escaping strategy possible values:
• ALWAYS - brackets are always escaped. Eg. "<" in source becomes "&lt;" in output XML
• NEVER - brackets are never escaped. Eg. "<" in source is passed without change to output XML
• IF_TAGS_ABSENT - Brackets aren't escaped if text contains tags. Eg. <b>bold</b>} will be passed without change, but "if x<4 then…" becomes "if x&lt;4 then…". See JSoup - library used to detect tags

Advanced options:

• ignorableColumns - default=[], columns from that list will be ignored during parsing. List should contain column names eg. ['Section', 'Notes']
• allowNonTranslatableTranslation - default=false, if set to true resources marked non-translatable but translated are permitted
• allowEmptyTranslations - default=false, if set to true then empty values are permitted
• outputFileName - default=strings.xml, XML file name (with extension) which should be generated as an output
• outputIndent - default= (two spaces), character(s) used to indent each line in output XML files

Migration from previous versions:

Versions older than 1.0.7 provided escapeBoundarySpaces option, which defaulted to true. Currently strings are always escaped when corresponding parsed CSV ceil 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
See LICENSE file.