Setting up Respresso in an Android project

To get started, you need a project in Respresso.
Respresso projects' are designed to be shared across platforms. If your app is implemented for iOS or Web you can use their Respresso project.

Set up a new Android project

  1. Install the Respresso CLI on all the machines you want to use to sync resource files.
  2. Go to the project dashboard in Respresso and find your project token at the top.
  3. In your app/module directory, run respresso init --token <your project token>. This will create the respresso.json file. This file should be added to your VCS (aka. Git).
  4. Run respresso sync. This will create the respresso.lock file and download/upload all the requested resource files. For VCS include or ignore dilemmas, see the get started page of the Respresso CLI.
  5. Optionally, add the following Gradle snippet to your app/module level build.gradle to run sync before each build:
task respressoSync(type: Exec) {
    commandLine 'respresso', 'sync'
}
preBuild.dependsOn respressoSync

For other Gradle setups, see the Android Gradle Sync page

The Respresso CLI is highly customizable. You can learn more about it in the get started page of the CLI.

Available categories and groups

All resource categories in Respresso are supported for Android. This includes localizations, images, colors, app icons, fonts and raw configs.

As Android resource files have strict formats and exact locations within a project, Respresso packs them in a single sync group named android.

Migrate an existing Android app

  1. Go to your Respresso project and import your resource files in each resource category.
  • Localization: Go to the localization category and import your localizations.
    1. You will need to add a default language. It should be the one you use in the res/values/strings.xml localizations file.
    2. Drag and drop your res/values/strings.xml file or select it using the Import button. All settings will be fine, just press the Import button.
    3. If you have multiple languages, you need to add them using the Language Management Toolbar
    4. Import each language one by one, by selecting the language from the toolbar, them importing it. Make sure you import it to the proper language! (The localization file is usually placed in res/values-<language code>/strings.xml)
  • Images: Go to the image category and import your icons and images.
    • Drag and drop your res/drawable directory or select it with Upload button. You might get some errors for non image files, like layer lists. You can ignore them.
    • For raster images (png, jpg) you will need to upload only the largest resolution. If your project is consistent, then you will only need to upload the drawable-xxxhdpi directory.
    • Once you uploaded the images, you need to press the Save button. The first save will take a while. If you added more than 10 images, it may show an Unknown error due to a timeout, but the save will eventually finish in the background. Just come back in a few minutes and refresh the page.
  • Colors: Go to the color category and import your colors. Drag and drop your res/values/colors.xml file or select it using the Import button.
  • App icons: Go to the App icon category. If you have a single layer app icon, you can upload it to the single image section, for dynamic app icons, you will have to upload a foreground and a background image. Don't forget to press the Save button at the bottom of the page.
  1. Set up your project as you would with a new project. Instructions above.
  2. When you run your first respresso sync you might need to confirm some file overrides. For this reason, you must run the first sync from a terminal and not from Gradle.
  3. After your sync finishes, your build will probably fail due to duplicate resources. You will have to remove some of your old resources:
  • Localization:
    • Remove all <string name="...">...</string> tags from your res/values[-<language code>]/strings.xml files that are not marked with translatable="false". (Android Studio will mark them due to duplication as the new respresso.strings.xml file contains them.)
    • Currently, plurals and arrays are not supported, so the import will ignore them. Similarly, strings with translatable="false" are ignored during import. You will have to manage them manually like you did previously.
  • Color: You can remove your res/values/colors.xml file as it is replaced by the res/values/respresso.colors.xml file.
  1. Hurray! Your project is good to go. If you change something in Respresso and run a sync, it will magically appear in your project.

Keep in mind, that importing the same resources from multiple platforms may cause unexpected behaviour. Imports merge the imported resources with the existing ones. (Usually overriding the pre-existing ones.) If you import your iOS resources then import the same ones from your Android project will result in a mixture or the resources unless you named them exactly the same. In that case, the Android version will be used as it was imported later.