Skip to content
Extracts localized strings from an Android app and stores it in a much more efficient format.
Java Python Kotlin
Branch: master
Clone or download
Ider Merge pull request #1 from nisrulz/patch-1
Fixing spelling of `Resoruces` to `Resources` inside Readme
Latest commit 4802989 Nov 4, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
library Initial Commit Oct 31, 2019
sample Initial Commit Oct 31, 2019
.gitignore Initial Commit Oct 31, 2019
CODE_OF_CONDUCT.md Initial Commit Oct 31, 2019
CONTRIBUTING.md Initial Commit Oct 31, 2019
LICENSE
README.md Fixing spelling of `Resoruces` to `Resources` inside Readme Nov 3, 2019

README.md

StringPacks

StringPacks is a library to store translation strings in a more efficient binary format for Android applications, so that it reduces the Android APK size.

Requirements

  • Python 3 - The StringPacks python scripts are written in Python 3.
  • minSdkVersion 15 - The library default min sdk version is 15, but it should work for lower SDK verions.
  • Git - The script uses git ls-files to look up files.
  • Android development environment
  • Gradle Build System

Setup in Android Project

  1. Copy the library/ directory from this project to the root directory of your Android project.
    • Rename the directory to stringpacks to make it more clear and avoid naming conflicts..
  2. Move either Java or Kotlin version of StringPackIds file from templates/ directory to your project source code directory.
    • Edit package information of the file.
  3. Move template config.json to your Android application project directory.
    • Replace {app} to be your application project directory name.
    • Point pack_ids_class_file_path to the path where you put the StringPackIds file.
  4. Include this library to your Android Project by adding include ':stringpacks' to the settings.gradle file.
  5. Add implementation project(':stringpacks') to dependencies{ } block of the build.gradle file in your application project.

You now have StringPacks available in your Android project.

Getting Started

There are a few steps to walk through before you can really use packed strings in your application. But don't worry, most of them only need to be done once.

Runtime

Since the translated strings are moved to our special binary format (.pack files), your application needs a way to read those strings during runtime. The library provides a wrapper class for Context and Resources to help with that.

You need to add the following code to all subclasses of your Context class (like Activity and Service) to ensure the strings are read from .pack files instead of Android system resources.

// Java

@Override
protected void attachBaseContext(Context base) {
    super.attachBaseContext(StringPackContext.wrap(base));
}
// Kotlin

override fun attachBaseContext(base: Context?) {
    super.attachBaseContext(StringPackContext.wrap(base))
}

Your Android application also needs to use a custom Application, which needs to include the following code to ensure the strings are read from .pack files.

// Java

@Override
protected void attachBaseContext(Context base) {
  StringPackIds.registerStringPackIds();
  StringPacks.getInstance().setUp(base);
  
  super.attachBaseContext(StringPackContext.wrap(base));
}
// Kotlin

override fun attachBaseContext(base: Context?) {
    registerStringPackIds()
    StringPacks.getInstance().setUp(base)

    super.attachBaseContext(StringPackContext.wrap(base))
}

You only need to do this each time you add a new context component. You don't need to do this for each component if you add them to a base class.

Generate .pack files

You have added the StringPackIds file to your project, but it has nothing in it yet. It is supposed to hold the mapping from android resource IDs (R.string) to string pack IDs. The content would be automatically filled in when you run the script that provided by this library.
The mapping information would also be used for generating the .pack files, so they are correctly loaded at runtime.

Execute the python script from your project root directory to assemble the string packs:

python3 ./stringpacks/scripts/assemble_string_packs.py --config ./{path_to}/config.json

You will see:

  • The StringPackIds file has been updated with the pack ID mapping information;
  • The translation strings, which are packable, have been moved to different directory, so that they won't be compiled into the APK;
  • The .pack file for different language have been generated under the project assets/ directory.

When you update translations, or change a string in the project, you may run the script again to generate .pack files with latest content.

Those string resource IDs that are not listed in the StringPackIds file, will continue to be kept in the Android system resources, and the StringPacks runtime would automatically fall back to read from there.

 

Now, you can use gradle to build your application as usual. The application should correctly retrieve the strings from StringPacks.

License

Copyright (c) Facebook, Inc. and its affiliates.

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.
You can’t perform that action at this time.