loco-android

🇯🇵 🇰🇷 🇩🇪 🇨🇳 🇺🇸 🇫🇷 🇪🇸 🇮🇹 🇷🇺 🇬🇧

This is a gradle plugin for easy update of text strings managed on Loco (localise.biz).

⚠️ Migration from 0.2.xx to 0.3.xx

It's no longer needed to differentiate between using this plugin for one or multiple Loco configurations.

The Gradle Loco task updateLoco will update the Strings for all configs specified inside the plugin.

⚠️ The Gradle Loco task updateLocoMultiple has been removed ! ⚠️

To support this change every config inside the plugins Loco{} declarations needs to be wrapped in a config{}

Using the plugin as of 0.3.x with one Loco configuration:

Loco {
    config {
        apiKey = 'YOUR_API_KEY'
        lang = ['de', 'fr'] // add as many languages as you want, they need to exist on localise.biz
        resDir = "$projectDir/src/main/res"
        defLang = 'de'
        // one language that will result as the default language and be put in values/strings.xml
        saveDefLangDuplicate = false
        // default (false): defLang will only be saved in values folder. If set to true, the defLang will also be saved in the specific folder (such as values-en)
        placeholderPattern = null // optional; regex pattern with leading ~, default -> null
        fileName = "strings" // optional; customise file name
        hideComments = false // optional; hide comments & loco metadata 
        tags = 'Android,!iOS'
        // optional; filter assets by comma-separated tag names. Match any tag with `*` and negate tags by prefixing with `!`. Whitespaces need to be replaced with _ (e.g. "Some tag" becomes "Some_tag").	 
        fallbackLang = 'en' // optional;, fallback language when not present
        orderByAssetId = false // optional; order assets alphabetically by Asset ID
        status = "translated"
        // optional; filter assets by status. Negate values by prefixing with !. e.g. "translated", or "!fuzzy".
        resourceNamePrefix = null
        // optional: string prefix for all resource names (default: null, no prefix)
        ignoreMissingTranslationWarnings = false
        // optional: use at your own risk, removes linting issues of missing translations
        index = null // optional: pass in a lookup key such as "id" or "text"
    }
}

Using the plugin as of 0.3.x with MORE than one Loco configuration:

Loco {
    config {
        apiKey = 'YOUR_API_KEY'
        lang = ['de', 'fr'] // add as many languages as you want, they need to exist on localise.biz
        resDir = "$projectDir/src/main/res"
        defLang = 'de' // one language that will result as the default language and be put in values/strings.xml
        saveDefLangDuplicate = false // default (false): defLang will only be saved in values folder. If set to true, the defLang will also be saved in the specific folder (such as values-en)
        placeholderPattern = null // optional; regex pattern with leading ~, default -> null
        fileName = "strings" // optional; customise file name
        hideComments = false // optional; hide comments & loco metadata 
        tags = 'Android,!iOS' // optional; filter assets by comma-separated tag names. Match any tag with `*` and negate tags by prefixing with `!`. Whitespaces need to be replaced with _ (e.g. "Some tag" becomes "Some_tag").	 
        fallbackLang = 'en' // optional;, fallback language when not present
        orderByAssetId = false // optional; order assets alphabetically by Asset ID
        status = "translated" // optional; filter assets by status. Negate values by prefixing with !. e.g. "translated", or "!fuzzy".
        resourceNamePrefix = null // optional: string prefix for all resource names (default: null, no prefix)
        ignoreMissingTranslationWarnings = false // optional: use at your own risk, removes linting issues of missing translations
        index = null // optional: pass in a lookup key such as "id" or "text"
    }
    config {
        apiKey = 'YOUR_OTHER_API_KEY'
        lang = ['de', 'fr'] // add as many languages as you want, they need to exist on localise.biz
        resDir = "$projectDir/src/main/res"
        // ...
    }
    // ...
}

Instructions

In oder to use the plugin follow those steps:

1.Add the following code to you build.gradle file in the root folder.

// Kotlin DSL
plugins {
  id("com.appswithlove.loco") version "0.3.1" apply false
}

or

buildscript {
    repositories {
        //…
        mavenCentral()
    }

    dependencies {
        //…
        classpath 'com.appswithlove.loco:loco:0.3.1'
    }
}

2.Apply the plugin in app/build.gradle.

// Kotlin DSL
plugins {
  ...
  id("com.appswithlove.loco")
}

or

plugins {
    ...
    id 'com.appswithlove.loco'
}

3.Configure the Loco instance in app/build.gradle:

Single loco configuration (most common):

Loco {
    config {
        apiKey = 'YOUR_API_KEY'
        lang = ['de', 'fr'] // add as many languages as you want, they need to exist on localise.biz
        resDir = "$projectDir/src/main/res"
        defLang = 'de'// one language that will result as the default language and be put in values/strings.xml
        saveDefLangDuplicate = false // default (false): defLang will only be saved in values folder. If set to true, the defLang will also be saved in the specific folder (such as values-en)
        placeholderPattern = null // optional; regex pattern with leading ~, default -> null
        fileName = "strings" // optional; customise file name
        hideComments = false // optional; hide comments & loco metadata 
        tags = 'Android,!iOS' // optional; filter assets by comma-separated tag names. Match any tag with `*` and negate tags by prefixing with `!`. Whitespaces need to be replaced with _ (e.g. "Some tag" becomes "Some_tag").	 
        fallbackLang = 'en' // optional;, fallback language when not present
        orderByAssetId = false // optional; order assets alphabetically by Asset ID
        status = "translated" // optional; filter assets by status. Negate values by prefixing with !. e.g. "translated", or "!fuzzy".
        resourceNamePrefix = null // optional: string prefix for all resource names (default: null, no prefix)
        ignoreMissingTranslationWarnings = false // optional: use at your own risk, removes linting issues of missing translations
        index = null // optional: pass in a lookup key such as "id" or "text"
        replace = [:] // optional: replace strings with other strings, e.g. ["foo": "bar"]
    }
}

4.Done!

Usage

After installing the plugin, you should be able to find the Gradle Loco tasks in Android Studio.

"Gradle Project" Window -> Tasks -> Other -> updateLoco

Otherwise, you can call the gradle tasks via command:

./gradlew updateLoco

⚠️ Keep in mind

Executing updateLoco will override all existing strings.xml (or other, if custom fileName) files of the given languages. Any type of app specific text strings should be placed into a separate string file, such as constants.xml.

Multiple Loco Projects

Starting from Version 0.2.0, there is support for multiple Loco configs in the same project. Starting from 0.3.0 this can be easily done with the same config as for a single config. This can be done via configuration in app/build.gradle:

Loco {
    config {
        apiKey = 'YOUR_OTHER_API_KEY'
        lang = ['de', 'fr'] // add as many languages as you want, they need to exist on localise.biz
        resDir = "$projectDir/src/main/res"
        defLang = 'de'
        // ...
    }
    config {
        apiKey = 'YOUR_OTHER_API_KEY'
        lang = ['de', 'fr'] // add as many languages as you want, they need to exist on localise.biz
        resDir = "$projectDir/src/main/res"
        defLang = 'de'
        // ...
    }
    config {
        // ...
    }
    
    
}

After that you can run the same task as you would for a single config:

"Gradle Project" Window -> Tasks -> Other -> updateLoco

or

./gradlew updateLoco

---

Parameters

The parameter placeholderPattern allows to have parameters replaced in text strings. The default value is null, therefore no parameter will be replaced. If you use a custom pattern, make sure to add a tilde ~ just in front of the pattern, so that it gets recognized as a pattern from gradle.

Example for a pattern: placeholderPattern = ~/\$[^$]*\$/ will replace every parameter in the form $ANYTEXT$ , $Any Text$ (start and end with $) with %s when updating the Loco strings.

Debug

In order to debug the plugin, clean -> jar -> publishJarPublicationToMavenLocal and connect your android App to the mavenLocal-version of the android plugin by adding the following snipped to your root-folder build.gradle. Feel free to make use of our sample aswell.

buildscript {
    repositories {
        mavenLocal()
        ...
    }
    dependencies {
        classpath 'com.appswithlove.loco:loco:0.3.0'
        ...
    }
}

After that, call the following script in the terminal of your android app (replace FLAVOUR)

./gradlew updateLoco -Dorg.gradle.debug=true --no-daemon

Lastly, open the Loco Plugin in Android Studio, add an Remote build configuration with Attach to remote JVM and run the configuration on debug. Now the gradlew call you triggered before will start running and will hit the break points in the plugin. :)

Don't forget to republish the plugin-jar when doing changes.