Need help with android-gradle-localization-plugin?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

koral--
100 Stars 18 Forks MIT License 165 Commits 7 Opened issues

Description

Gradle plugin for generating localized string resources

Services available

!
?

Need anything else?

Contributors list

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

  • string arrays - see Arrays
  • plurals - see Plurals
  • non-translatable resources -
    translatable
    XML attribute
  • auto-escaping double quotes, apostrophes and newlines
  • auto-quoting leading and trailing spaces
  • syntax validation - duplicated, empty, invalid names detection
  • comments
  • formatted strings -
    formatted
    XML attribute
  • default locale specification -
    tools:locale
  • evaluate cell formulas

Applying plugin

Gradle 2.1+

In whichever

build.gradle
file.
groovy
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:
    groovy
    apply plugin: 'pl.droidsonroids.localization'
    

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:

csv
name,default    ,pl       ,comment   ,translatable
file,File       ,"Plik"   ,file label,
app ,Application,,,false
will produce 2 XML files: *
values/strings.xml
:
xml


  File
  Application

*
values-pl/strings.xml
:
xml


  Plik

Configuration

Add

localization
extension in
build.gradle
of particular module.
groovy
 localization {
         csvFile=file('translations.csv')
         OR
         csvFileURI='https://docs.google.com/spreadsheets/d//export?format=csv'
         OR
         csvGenerationCommand='/usr/bin/xlsx2csv translation.xlsx'
         OR
         xlsFile=file('translations.xlsx')
         OR
         xlsFileURI='https://docs.google.com/spreadsheets/d//export?format=xlsx'
}
*
csvFileURI
and
xlsFileURI
can be any valid URI, not necessarily Google Docs' one *
xlsFile
and
xlsFileURI
accepts both XLSX and XLS files. If filename ends with
xls
file will be treated as XLS, XLSX otherwise

Sources, 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 absolute *
csvFileURI
,
xlsFileURI
- CSV/XLS(X) 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.

Spreadsheet format:

  • defaultColumnName
    - default=
    'default'
    , name of the column which corresponds to default localization (
    values
    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 flags (source for the
    translatable
    XML attribute)
  • commentColumnName
    - default=
    'comment'
    , name of the column containing comments
  • formattedColumnName
    - 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 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
*
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 for more details

(X)HTML tags escaping

  • tagEscapingStrategy
    - default=
    IF_TAGS_ABSENT
    , defines X(H)TML tag brackets (< and >) escaping strategy possible values:
    • ALWAYS
      - brackets are always escaped. E.g. "<" in source becomes "&lt;" in output XML
    • NEVER
      - brackets are never escaped. E.g. "<" in source is passed without change to output XML
    • IF_TAGS_ABSENT
      - Brackets aren't escaped if text contains tags or CDATA section. E.g. <b>bold</b> will be passed without change, but "if x<4 then…" becomes "if x&lt;4 then…".
    • tagEscapingStrategyColumnName
      - default=unset (no column), name of the column containing non-default tag escaping strategy, if cell is non-empty then strategy defined there is used instead of global one

CSV format:

XLS(X) format:

  • sheetName
    - default=
    , name of the sheet to be processed, only one can be specified, 
    ignored if 
    useAllSheets
    is set to true
  • useAllSheets
    - default=
    false
    , if set to true all sheets are processed and
    sheetName
    is ignored
  • evaluateFormulas
    - default=
    false
    , if set to true evaluates formulas in cells

Advanced options:

  • ignorableColumns
    - default=
    []
    , columns from that list will be ignored during parsing. List should contain column names e.g.
    ['Section', 'Notes']
    . Columns containing only empty cells are always ignored.
  • 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
  • handleEmptyTranslationsAsDefault
    - default=
    false
    , if set to true empty values do not result in entries in non-default languages, i.e. no empty XML entries for non-default languages are created. If set to
    true
    then
    allowEmptyTranslations
    is ignored for all but default language
  • 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
  • skipInvalidName
    - default=
    false
    , if set to true then rows with invalid key names will be ignored instead of throwing an exception
  • skipDuplicatedName
    - default=
    false
    , if set to true then rows with duplicated key names will be ignored instead of throwing an exception. First rows with given key will be taken into account.
  • defaultLocaleQualifier
    - language (eg.
    es
    ) and optionally region (eg.
    es_US
    ) ISO codes of default translations. Default=
    null
    (unset) which effectively means English
    en
    , if set then value will be placed in
    tools:locale
    XML attribute. See Tools Attributes for more information.

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
See LICENSE file.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.