Philology

An easy way to dynamically replace Strings of your Android App or provide new languages Over-the-air without needed to publish a new release on Google Play.

Why should I be interested in Philology

How String resources work on Android?

Android Resources provide us with an easy way to internationalise our App: a file with all the strings used by our App and a copy of it for every language the App is translated to. Android OS does the rest choosing the proper file depending on device's language.

That is perfect and I don't want to stop using it.

The problem

These strings are hardcoded inside our App. If there's a typo or you find a better way to express something, a new version of the App needs to be deployed to include the newer translation. This is a slow process and a poor user experience. We all know users take their time to update an app (if they ever do so) and there's also the time Google Play takes to make a new version of an app available to all users.

How Philology solves this problem?

Philology doesn't replace the way you are using resources in your current Android Development. Instead, it improves the process by intercepting the value returned from your hardcoded translation files inside of the app and check if there is a newer value in the server. This allows for typo fixing, better wording or even for adding a new language. All in real time, without releasing a new version of the App.

With Philology you could replace hardcoded texts instantly and win time before the new release is done.

Getting Started

Dependency

Philology use ViewPump library to intercept the view inflate process and reword strings resources. It allows you to use other libraries like Calligraphy that intercept the view inflate process

dependencies {
    compile 'com.jcminarro:Philology:2.1.0'
    compile 'io.github.inflationx:viewpump:2.0.3'
}

Usage

Initialize Philology and ViewPump

Define your PhilologyRepositoryFactory who provides PhilologyRepository according with the selected Locale on the device. Kotlin:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        // Init Philology with our PhilologyRepositoryFactory
        Philology.init(MyPhilologyRepositoryFactory)
        // Add PhilologyInterceptor to ViewPump
        // If you are already using Calligraphy you can add both interceptors, there is no problem
        ViewPump.init(ViewPump.builder().addInterceptor(PhilologyInterceptor).build())
    }
}

object MyPhilologyRepositoryFactory : PhilologyRepositoryFactory {
    override fun getPhilologyRepository(locale: Locale): PhilologyRepository? = when (locale.language) {
        Locale.ENGLISH.language -> EnglishPhilologyRepository
        Locale("es", "ES").language -> SpanishPhilologyRepository
        // If we don't support a language we could return null as PhilologyRepository and
        // values from the strings resources file will be used
        else -> null
    }
}

object EnglishPhilologyRepository : PhilologyRepository {
    override fun getText(key: String): CharSequence? = when (key) {
        "label" -> "New value for the `label` key, it could be fetched from a database or an external API server"
        // If we don't want reword a strings we could return null and the value from the string resources file will be used
        else -> null
    }

    override fun getPlural(key: String, quantityString: String): CharSequence?  = when ("${key}_$quantityString") {
        "plurals_label_one" -> "New value for the `plurals_label` key and `one` quantity keyword"
        "plurals_label_other" -> "New value for the `plurals_label` key and `other` quantity keyword"
        // If we don't want reword a plural we could return null and the value from the string resources file will be used
        else -> null
    }

   override fun getTextArray(key: String): Array<CharSequence>? = when (key) {
        "days" -> arrayOf(
            "Monday",
            "Tuesday",
            "Wednesday",
            "Thursday",
            "Friday",
            "Saturday",
            "Saturday"
        )
        // If we don't want reword a string array we could return null and the value from the string resources file will be used
        else -> null
    }
}

object SpanishPhilologyRepository : PhilologyRepository { /* Implementation */ }

Java:

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        PhilologyRepositoryFactory repositoryFactory = new MyPhilologyRepositoryFactory();
        Philology.INSTANCE.init(repositoryFactory);
        ViewPump.init(ViewPump.builder().addInterceptor(PhilologyInterceptor.INSTANCE).build());
    }
}

public class MyPhilologyRepositoryFactory extends PhilologyRepositoryFactory {
    @Nullable
    @Override
    public PhilologyRepository getPhilologyRepository(@NotNull Locale locale) {
        if (Locale.ENGLISH.getLanguage().equals(locale.getLanguage())) {
            return new EnglishPhilologyRepository();
        }
        return null;
    }
}

public class EnglishPhilologyRepository extends PhilologyRepository {
    @Nullable
    @Override
    public CharSequence getText(@NotNull Resource resource) { /* Implementation */}
}

Inject into Context

Wrap the Activity Context. Kotlin:

class BaseActivity : AppCompatActivity() {
    override fun attachBaseContext(newBase: Context) {
        super.attachBaseContext(ViewPumpContextWrapper.wrap(Philology.wrap(newBase)))
    }
}

Java:

public class BaseActivity extends AppCompatActivity {
    @Override
    protected void attachBaseContext(Context newBase) {
        super.attachBaseContext(ViewPumpContextWrapper.wrap(Philology.INSTANCE.wrap(newBase)));
    }
}

That is all

CustomViews

Philology allows you to reword your own CustomViews, the only that you need to do is provide an implementation of ViewTransformer that rewords the text fields used by your CustomView. The Context used to inflate your CustomView is already wrapped by the library, so, you can assign the @StringRes used on the .xml file that will be provided on the reword() method.

Kotlin:

object MyCustomViewTransformer : ViewTransformer {
    override fun reword(view: View, attributeSet: AttributeSet): View = view.apply {
        when (this) {
            is MyCustomView -> reword(attributeSet)
        }
    }

    private fun MyCustomView.reword(attributeSet: AttributeSet) {
        @StringRes val textResId = context.getStringResourceId(attributeSet, R.styleable.MyCustomView_text)
        if (textResId > 0) setTextToMyCustomView(textResId)
    }
}

Java:

public class MyCustomViewTransformer extends ViewTransformer {
    private static String MY_CUSTOM_ATTRIBUTE_NAME = "text";
    @NotNull
    @Override
    public View reword(@NotNull View view, @NotNull AttributeSet attributeSet) {
        if (view instanceof MyCustomView) {
            MyCustomView myCustomView = (MyCustomView) view;
            int textResId = getStringResourceId(myCustomView.getContext(), attributeSet, R.styleable.MyCustomView_text);
            if (textResId > 0) {
                myCustomView.setTextToMyCustomView(textResId);
            }
        }
        return view;
    }
}

After you implement your ViewTransformer you need to provide it to Philology injecting a ViewTransformerFactory by the init() method Kotlin:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Philology.init(MyPhilologyRepositoryFactory, MyViewTransformerFactory)
        ViewPump.init(ViewPump.builder().addInterceptor(PhilologyInterceptor.INSTANCE).build());
    }
}

object MyViewTransformerFactory : ViewTransformerFactory{
    override fun getViewTransformer(view: View): ViewTransformer = when (view) {
        is MyCustomView -> MyCustomViewTransformer
        else -> null
    }
}

Java:

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        PhilologyRepositoryFactory repositoryFactory = new MyPhilologyRepositoryFactory();
        ViewTransformerFactory viewTransformerFactory = new MyCustomViewTransformerFactory();
        Philology.INSTANCE.init(repositoryFactory, viewTransformerFactory);
        ViewPump.init(ViewPump.builder().addInterceptor(PhilologyInterceptor.INSTANCE).build());
    }
}

public class MyCustomViewTransformerFactory implements ViewTransformerFactory {
    @Nullable
    @Override
    public ViewTransformer getViewTransformer(@NotNull View view) {
        if (view instanceof MyCustomView) {
            return new MyViewTransformer();
        }
        return null;
    }
}

Do you want to contribute?

Feel free to add any useful feature to the library, we will be glad to improve it with your help. I'd love to hear about your use case too, especially if it's not covered perfectly.

Developed By

• Jc Miñarro - josecarlos.minarro@gmail.com

License

Copyright 2018 Jc Miñarro

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.