cookpad / StringsPatcher

An android lib for updating string resources on the fly

[DEPRECATED]

⚠️ This repository is no longer actively maintained ⚠️

Strings Patcher

It's very common (at least in our company) that just after a new release, someone discovers a translation that is wrong, or even missing in a specific language (we support over 10 different languages).

When this happens we have 2 options: Create a patch release with the missing translation and release again, whith all the work and overhead that it implies, or wait until next week for a release with the translation fixed.

Of course, most of this problems can be avoided by being very careful when adding a new translation, but we are humans and we make mistakes. This library has been made for making those mistakes a little bit less painful.

Features

• Update (Patch) String values on the fly.
• Serverless implementation, relying on Google Spreadsheets for data storage

Setup

Adding the library to your project

Add to top level gradle.build file

allprojects {
    repositories {
        maven { url "https://jitpack.io" }
    }
}

Add to app module gradle.build file

dependencies {
    compile 'com.github.cookpad:StringsPatcher:0.1.0'
}

Setting up the spreadhseet

We recomend that, if you can, you use the first setup (A). The drawback is that your string patches spreadhseet has to be public. If you want your spreadsheets to be private use the setup (B).

A - (Easy) Public spreadhseet

1 Getting the spreadsheet key

• Go to google Drive and create a new spreadsheet
• Add this 3 words into the first 3 columns, on the firt row: lang, key & value

- Click on File > Publish to the web > Publish - Copy the Spreadsheet key which is a long string of numbers and letters that you can get from the displayed url `https://docs.google.com/a/cookpad.jp/spreadsheets/d/[spreadsheet-id]/pubhtml` and don't loose it, you'll need it when setting up the library.

2 Other spreasheet setups

• Name your worksheet (bottom tab) with the same name as your android build number (this is optional but you have to, at least, name the worksheet with something you'll remember)
• [optional] You can create multiple worksheets named after each android build number, that way you can mantain different String patches for different versions of your app

B - (Hard) Private spreadhseet

1 Getting the spreadsheet key

• Go to google Drive a create a new spreadsheet
• Add this 3 words into the first 3 columns, on the firt row: lang, key & value
• Copy the Spreadsheet key which is a long string of numbers and letters that you can get from the url https://docs.google.com/spreadsheets/d/[spreadsheet-id]/edit#gid=0 and don't loose it, you'll need it when setting up the library.

2 Other spreasheet setups

• Name your worksheet (bottom tab) with the same name as your android build number (this is optional but you have to, at least, name the worksheet with something you'll remember)
• [optional] You can create multiple worksheets named after each android build number, that way you can mantain different String patches for different versions of your app

3 Getting Google App credentials

• Go to Google Dev Console https://console.developers.google.com and create a new App
• In Dashboard enable: Google Sheets in order to access the spreadsheets
• Now go to Credentials > Create Credential > OAuth client ID > Web application
• Add http://localhost to Authorized JavaScript origins
• Also add http://localhost and https://developers.google.com/oauthplayground to Authorized redirect URIs
• Copy somewhere your client ID and Secret

4 Getting a Refresh Token

• Now go to https://developers.google.com/oauthplayground/
• Click on the top-right settings icon to open the settings drawer
• Check Use your own OAuth credentials and add your client ID and client Secret

• Now on the left input bow that says input your own scopes type https://www.googleapis.com/auth/spreadsheets.readonly and press Authorize APIs

• You will see a google login form. Login with the same user that you used to create the spreadhseet. Press Allow (this only allows the app to read your spreadsheets, not modify anything)

• Wait for the playground to load and then press Exchange authorization code for tokens

• Copy your Refresh token somewhere, you'll need it too. (You might need to press in Step 2Exchange authorization code for tokens to see the tokens)

• You should now have the client ID, client Secret and Refresh Token. You're ready!

Usage

Call syncStringPatcher() in your Android Application class, supplying the context and your spreadSheetKey as the only mandatory parameters.

class StringsPatcherApp : Application() {
    override fun onCreate() {
        super.onCreate()

        val spreadSheetKey = "YOUR_SPREAD_SHEET_KEY"
        syncStringPatcher(this, spreadSheetKey)
    }
} 

Programmatically

syncStringPatcher expose next optional params:

• worksheetName: the worksheet name (The spreadsheet may be composed by several worksheets). This param has as default value the versionCode of the application. That way, your spreadsheet should have as many worksheets as release versions (1,2,3,4,...).
• locale: the locale used to filter strings. As default value the system locale is assigned.
• logger: callback function to listen for errors emission. As default a dummy implementation does nothing.
• resourcesClass: supply the auto-generated R.string::class of your app only if it is required patching strings set from xml layouts.
• googleCredentials: only supply these credentials if the spreadSheet has private access.

Once StringPatches has been initialized, in order to access the patches, you must retrieve string resources at runtime by calling either Context::getSmartString or Resources::getSmartString. For formatting strings, Context::getSmartString(formatArgs) and Resources::getSmartString(formatArgs) are exposed.

If there is no patch for a given key, the library fallbacks to the system resources.

XML layout

It's possible to patch strings which have been set from XML layouts (currently lib only supports text and hint property of any View extending from TextView). Call bindStringsPatchers supplying the View root from which you want to start replacing strings recursively (be aware that this may be a penalty performance for very nested views). An standard way of using it may be calling it onStart Activity event and supplying its view root, another more holistic approach would be using ActivityLifecycleCallbacks to configure the previous behaviour in a row for every single Activity of your application. For a working example, take a look to the app_test module.

Debug

By setting stringPatcherDebugEnabled as true the lib will append to the value its associated key, as such as a pencil emoji. This is intended to make clear which values are handled by the lib and, therefore, eligible to be updated by changing its value from the spreadsheet.