Skip to content

Latest commit

 

History

History
348 lines (289 loc) · 13.4 KB

README.md

File metadata and controls

348 lines (289 loc) · 13.4 KB
Raw

🛑 Docs out-of-date notice! 🛑

This documentation is not updated anymore. All documentation of Respresso moved to https://respresso.io/docs.

✔️ Up-to-date docs for Android is here:

Get started with Respresso

Content Link
Add Respresso to new or exiting Android project https://respresso.io/docs/guides/android-project-setup
Get started with Respresso CLI (auto-sync) https://respresso.io/docs/get-started-with-respresso-sync
Migrate from legacy Gradle plugin to the new CLI https://respresso.io/docs/guides/migrate-from-legacy-android-gradle-plugin

Learn more - Docs for Android Devs

Content Link
All about Respresso CLI setup in Gradle build https://respresso.io/docs/android-gradle-resource-sync
Respresso CLI reference (auto-sync) https://respresso.io/docs/respresso-cli-reference
Respresso CLI config reference (auto-sync) https://respresso.io/docs/respresso-cli-config-reference
Import existing resources from Android project Localization, Image (raster or drawable), Color
Localization format - strings.xml https://respresso.io/docs/localization/android-strings-xml-format
Localization variables in Respresso https://respresso.io/docs/localization/variables
Localization variable formatting https://respresso.io/docs/localization/variable-formatting
Localization variable placeholders https://respresso.io/docs/localization/custom-variable-placeholders

Seriously, 🛑 stop 🛑 here and go to the new docs!

Respresso Android client Tweet

Respresso is a centralized resource manager for shared Android, iOS and Web frontend projects. It allows you to simply import the latest assets into your workspace. You may store several versions of the same resource in the cloud and pick the ones you need to import. Respresso currently supports six types of resources:

  • Images
  • App icons
  • Localization
  • Fonts
  • Colors
  • Raw

Table of contents

Usage

The plugin aar needs to be defined in the classpath of your build script. It is directly available on Maven central. This snippet shows how to add repositories to your root build.gradle:

buildscript {

    dependencies {
        classpath "hu.ponte.respresso:client-android:1.0.0"
    }
}

To use the Respresso Android plugin, include this snippet in your app's build.gradle (app/build.gradle):

apply plugin: "hu.ponte.respresso"

respresso {
    projectToken "YOUR_PROJECT_TOKEN_HERE"
    resources {
        require "localization:1.0.0"
        require "color:1.0.0"
        require "appIcon:1.0.0"
        require "image:1.0.0"
        require "font:1.0.0"
    }

    server "https://app.respresso.io"
}

Please note that you must remove or comment out unused resources types. Now you can build your project and Respresso will import all resources that were stored at https://app.respresso.io previously. After the first successful build Respresso will create a "respressofile.lock" file on your project's root directory. This file contains information about current assets’ metadata.

Automatic usage

Simply press the Run button for your "app". Respresso will synchronize all resources before builds since its plugin is built into your build flow.

Manual usage

To synchronize resources without building, use gradle. Use the GUI "Tasks/other/getRespressoResForDebug"

Respresso synchronize GUI

or use terminal and type:
Windows:

gradlew getRespressoResForDebug

Linux:

./gradlew getRespressoResForDebug

Mac:

./gradlew getRespressoResForDebug

Note! Respresso will remove all resources that do not belong to it. If you would like to use unfollowed or client-specific resources, read the Tips section.

Breakdown of the plugin configuration

  • Include the project token received during initialization of your project in the Respresso web interface. This is done in the same manner as the host with the keyword "project_token" and your token inside double quotation marks
  • Specify the required resources inside the resources section using the following format: require "[resource_name]:[version_number]"

The currently accepted resource names are:

  • image
  • appIcon
  • color
  • localization
  • font
  • raw

Accepted version formats are:

  • [major].[minor].[patch] eg. 1.2.0
  • [major].[minor].[patch]+ eg. 1.2.0+ (not available in strict mode)
  • [major].[minor]+ eg. 1.2+ (not available in strict mode)

Optional arguments

####### server Specify the server of your assets in the last line by writing "server" and your URL in double quotation marks separated by a space. By omitting this argument Respresso will use its default host URL for syncing.

server "https://app.respresso.io"

####### strictMode Enabling strict mode will guarantee you get the same results each time you sync your assets. If set to true, you may only specify exact version numbers in your Respressofile. This option is set to false by default. Usage example:

strictMode true

####### enabled You can turn off synchronization. Default value is true.

enabled false

Tips

Android Studio is unable to find a resource

Android Studio may sometimes ignore new resource files. If this is the case, use the "File/Invalidate caches / Restart..." option.

Use your own resources

You can create a new module for Respresso. Respresso will synchronize all followed resources into the "module's res" folder in this case and your main module can contain unique resources.

Live Localization

Respresso serve a real-time preview about your localized strings. It shows you that how the translations are going to look like in your mobile app or web. No need to wait for a next deployment.

Obligation

Live localization is a higher abstraction layer over Respresso core. That is why Respresso usage is mandatory.

Usage

Add this dependency in your app's build.gradle (app/build.gradle):

dependencies {
	...
	implementation "hu.ponte.respresso:live-edit-android:1.0.0"
	...
}

How to turn on/off

Use this snipet if you would like to build your apk without live localization option.

buildTypes {
	...
	develop {
		buildConfigField "Boolean", "RespressoPreRelease", 'true'
	}
	release {
		buildConfigField "Boolean", "RespressoPreRelease", 'false'
	}
}

How to setting up

Create an application class and register it in your manifest file. Append this snipet into the class:
Kotlin:

override fun onCreate() {
	super.onCreate()

	Respresso.init(this, BuildConfig.RespressoPreRelease)
}

Java:

@Override
public void onCreate() {
	super.onCreate();

	Respresso.init(this, BuildConfig.RespressoPreRelease);
}

Use these configurations in you activity. (It's recommended that use a BaseActivity).
Kotlin:

override fun attachBaseContext(newBase: Context) {
	val context = Respresso.wrapContext(newBase)
	super.attachBaseContext(context)
}

override fun onResume() {
	super.onResume()
	Respresso.create(this)
}

override fun onDestroy() {
	super.onDestroy()
	Respresso.destroy(this)
}

Java:

@Override
protected void attachBaseContext(Context newBase) {
	Context context = Respresso.wrapContext(newBase);
	super.attachBaseContext(context);
}

@Override
protected void onResume() {
	super.onResume();
	Respresso.create(this);
}

@Override
protected void onDestroy() {
	super.onDestroy();
	Respresso.destroy(this);
}

Update text in a view

The easiest usage when you bind your text and view by Respresso.

Respresso.with(context).text(R.string.id_from_strings_xml).withAutoUpdate().into(view)

Let see some alternatives:

Respresso.with(context).hint(R.string.hint_id).withAutoUpdate().into(view)
Respresso.with(context).error(R.string.error_id).withAutoUpdate().into(view)
Respresso.with(context).title(R.string.title_id).withAutoUpdate().into(view)
Respresso.with(context).subtitle(R.string.subtitle_id).withAutoUpdate().into(view)

The technique is really simple. You have to use

Respresso.with(context).text() -> instead of view.setText() Respresso.with(context).hint() -> instead of view.hint() Respresso.with(context).title() -> instead of Toolbar/ActionBar/MenuItem.setTitle() etc.

and you concatenate more modifiers when a view has more options, like an EditTextView: Respresso.with(context).text(R.string.text_id_from_strings_xml).hint(R.string.hint_id_from_strings_xml).withAutoUpdate().into(edit_text_view)

Update text in a CustomView

Some cases Respresso unable to fill the view with demanded text(s). Don't worry, You can get notification about changes. Use this form in case of single text:

Respresso.with(context).string(R.string.text_id_from_strings_xml).into(view).dataReadyText = { view.setTextSomehow = it }
Respresso.with(context).string(R.string.text_id_from_strings_xml).into(view).setOnDataReadyText(new DataReadyText() {
	@Override
	public void onDataReady(@Nullable String text) {
		view.setTextSomehow(text)
	}
});

Use this form in case of multiple texts:
Kotlin:

Respresso.with(context).strings(arrayOf(
			RespressoStrings(R.string.first_text_id_from_strings_xml)
			RespressoStrings(R.string.second_text_id_from_strings_xml, "TAG")
		)
	).into(view).dataReadyTexts = {
		view.setTextSomehow1 = it[0].text
		if(it[1].TAG == "TAG")
			view.setTextSomehow2 = it[1].text
	}

Java:

Respresso.with(this).strings(new RespressoStrings[]{
			new RespressoStrings(R.string.name, 1),
			new RespressoStrings(R.string.name, 2)
        }).into(tv1).setOnDataReadyTexts(new DataReadyTexts() {
            @Override
            public void onDataReady(@Nullable RespressoText[] texts) {
                view.setTextSomehow1 = it[0].getText())
				if(it[1].getTAG() == "TAG")
					view.setTextSomehow2 = it[1].getText()
            }
        });

Update possibilities

withAutoUpdate will update your texts whenever it changes if it can.

Respresso.with(context).text(R.string.id).withAutoUpdate().into(view)

withNotifyUpdate will send you a notification into dataReady listener and you can handle it. It is not refresh your views content automatically.

Respresso.with(context).text(R.string.id).withNotifyUpdate().into(view)

noUpdate will fill your view only once. It is not send notification and not update your text.

Respresso.with(context).text(R.string.id).noUpdate().into(view)

How to use it

  1. Check above instructions
  2. Go to respresso(https://app.respresso.io) sign in and choose a project
  3. Click localization in the left panel and select the same version that you synked into your project
  4. Get your phone and shake it
  5. Switch on 'Localization / Connection' in the popup window

Now your modifications are going to appearance when you click the 'Save' button on the web

  1. For using Live Edit Module* shake your phone again and switch on 'Localization / Live Editor' in the popup window
  2. On web click on the 'Live Editor' button on the top right area
  3. Scan the QR Code with your phone which visible in your web browser's top right section

Let see what happened after 7th option. You activated a visible items filter and your list have less elements than before and don't have to use Save button to get updated texts. Be careful, this modification stored just in your phone's memory and you can lose it. Use the Save button to store your modifications.

* Live Edit Module: shows real-time preview how the translations will look like in your mobile app. Check the translations’ accuracy, length and the UI experience in real-time.