Gradle plugin for generating localized string resources
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
- Add dependency to the top-level
build.gradle
file. Your file should look like this:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.android.tools.build:gradle:0.14.+'
classpath 'pl.droidsonroids.gradle.localization:android-gradle-localization-plugin:1.0.+'
}
}
- Apply plugin and add configuration to
build.gradle
of the application, eg:
apply plugin: 'localization'
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
- Invoke
localization
gradle task. Task may be invoked from commandline or from Android Studio GUI.
- from commandline:
./gradlew localization
(orgradlew.bat localization
on Windows) - from GUI: menu
View->Tool Windows->Gradle
and double clicklocalization
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'sfile()
can be used to retrieve files by path relative to module location or absolutecsvFileURI
- CSV file URIcsvGenerationCommand
- 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 escapedescapeQuotes
- default=true, if set to false double quotes ("
) won't be escapedescapeNewLines
- default=true, if set to false newline characters won't be escapedescapeBoundarySpaces
- default=true, if set to false leading and trailing spaces won't be escaped so they will be effectively removed at compile timeconvertTripleDotsToHorizontalEllipsis
- default=true, if set to false triple dots (...
) won't be converted to ellipsis entity…
escapeSlashes
- default=true, if set to false slashes (\
) won't be escapednormalizationForm
- default=Normalizer.Form.NFC if set tonull
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 detailstagEscapingStrategy
- default=IF_TAGS_ABSENT, defines X(H)TML tag brackets (< and >) escaping strategy possible values:- ALWAYS - brackets are always escaped. Eg. "<" in source becomes "<" 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<4 then…". See JSoup - library used to detect tags
Advanced options:
ignorableColumns
- default=[], columns from that list will be ignored during parsingallowNonTranslatableTranslation
- default=false, if set to true resources marked non-translatable but translated are permittedallowEmptyTranslations
- default=false, if set to true then empty values are permitted
##License
MIT License
See LICENSE file.