Gradle plugin for generating localized string resources
MIT License
Gradle plugin for generating localized string resources
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.
translatable
XML attributeformatted
XML attributetools:locale
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.
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.
build.gradle
of the application, eg:apply plugin: 'pl.droidsonroids.localization'
Invoke localization
gradle task. Task may be invoked from commandline or from Android Studio GUI.
./gradlew localization
(or gradlew.bat localization
on Windows)View->Tool Windows->Gradle
and double click localization
Non existent folders will be created. WARNING existing XML files will be overwritten.
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>
<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>
<string name="file">Plik</string><!-- file label -->
</resources>
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'
}
csvFileURI
and xlsFileURI
can be any valid URI, not necessarily Google Docs' onexlsFile
and xlsFileURI
accepts both XLSX and XLS files. If filename ends with xls
file willSources, exactly one of them must be specified:
csvFile
, xlsFile
- CSV/XLS(X) file, Gradle's file()
can be used to retrieve files by path relative to module location or absolutecsvFileURI
, xlsFileURI
- CSV/XLS(X) file URIcsvGenerationCommand
- shell command which writes CSV as text to standard output.defaultColumnName
- default='default'
, name of the column which corresponds to default localizationvalues
folder)nameColumnIndex
- default=unset (nameColumnName
is taken into account), index of the column containing key names (source for the name
XML attribute)nameColumnName
- default='name'
(if nameColumnIndex
is not present), name of the column containing key names (source for the name
XML attribute)translatableColumnName
- default='translatable'
, name of the column containing translatable flagstranslatable
XML attribute)commentColumnName
- default='comment'
, name of the column containing commentsformattedColumnName
- default='formatted'
, name of the column formatted flags (source for the formatted
XML attribute)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:
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 escapedconvertTripleDotsToHorizontalEllipsis
- 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 to null
Unicode normalization won't be performed, see javadoc of NormalizertagEscapingStrategy
- default=IF_TAGS_ABSENT
, defines X(H)TML tag brackets (< and >) escaping strategyALWAYS
- brackets are always escaped. E.g. "<" in source becomes "<" in output XMLNEVER
- brackets are never escaped. E.g. "<" in source is passed without change to output XMLIF_TAGS_ABSENT
- Brackets aren't escaped if text contains tags or CDATA section. E.g.tagEscapingStrategyColumnName
- default=unset (no column), name of the column containing non-default tag escaping strategy, if cell is non-empty then strategycsvStrategy
- default=null
(library default strategy, equivalent ofsheetName
- default=<name of the first sheet>
, name of the sheet to be processed, only one can be specified,useAllSheets
is set to trueuseAllSheets
- default=false
, if set to true all sheets are processed and sheetName
is ignoredevaluateFormulas
- default=false
, if set to true evaluates formulas in cellsignorableColumns
- default=[]
, columns from that list will be ignored during parsing. List should['Section', 'Notes']
. Columns containing only empty cells are always ignored.allowNonTranslatableTranslation
- default=false
, if set to true resources markedallowEmptyTranslations
- default=false
, if set to true then empty values are permittedhandleEmptyTranslationsAsDefault
- default=false
, if set to true empty values do not result in entries in non-default languages,true
then allowEmptyTranslations
is ignored for all but default languageoutputFileName
- default=strings.xml
, XML file name (with extension) which should be generated as an outputoutputIndent
- default=
(two spaces), character(s) used to indent each line in output XML filesskipInvalidName
- default=false
, if set to true then rows with invalid key names will be ignored insteadskipDuplicatedName
- default=false
, if set to true then rows with duplicated key names will be ignored insteaddefaultLocaleQualifier
- language (eg. es
) and optionally region (eg. es_US
) ISO codes of default translations.null
(unset) which effectively means English en
, if set then value will be placed in tools:locale
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.
Obsolete, non-scoped localization
plugin id is no longer supported. The only valid id is pl.droidsonroids.localization
.
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
.
MIT License See LICENSE file.