KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #dsh #dsh-plugin #ai-agent #codex #ai-agents #deepseek-harness #claude-code #cli #react #mcp

StringPacks

★ 128 Open GitHub ↗

Extracts localized strings from an Android app and stores it in a much more efficient format.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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.

Check out [our tech talk on StringPacks from DroidCon SF 2019](https://youtu.be/npnamYPQD3g?t=812) to know more about the motivation, architecture and prospect of the StringPacks project.

## 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 versions.
- **Git** - The script uses `git ls-files` to look up files.
- **Android development environment**
- **Gradle Build System**

## Setup in Android Project

1. Copy the [scripts/](library/scripts/) and [pack.gradle](library/pack.gradle) from `library/` to the root directory of your Android project.
2. Move either [Java](library/templates/StringPackIds.java) or [Kotlin](library/templates/StringPackIds.kt) version of `StringPackIds` file from [templates/](library/templates/) directory to your project source code directory.
    - Edit package information of the file.
3. Move [template config.json](library/templates/config.json) to your Android application project directory.
    - Replace `{app}` to be your application project directory name.
    - Choose one of the two (mutually exclusive):
      - Point `pack_ids_class_file_path` to the path where you put the `StringPackIds` file.
      - Configure `resource_config_setting` to generate the necessary aapt config file.
        - `config_file_path` file path for aapt2 config to set stable id
        - `source_file_path` for file path of generated Java source
        - `string_offset` a hex string for string id offset (usually "0x7f120000")
        - `plurals_offset` a hex string for plural id offset (usually "0x7f100000")
        - `package_name` for package name.
4. Make following changes to your Android project's `build.gradle`.
   ```
   allprojects {

repositories {
       ...
       mavenCentral()
    }
    ...
   }

// Replace `{path_to_config.json}` with the path to your `config.json` file
   ext {
     stringPacksConfigFile = "$rootDir/{path_to_config.json}"
   }
   ```
   - Replace `{path_to_config.json}` with the path to your `config.json` file
5. Make following changes to your Android application's `build.gradle`
   ```
   apply from: "$rootDir/pack.gradle"

dependencies {
     ...
     ...
     implementation 'com.whatsapp.stringpacks:stringpacks:0.3.1'
   }
   ```
6. To remove old `.pack` files from the device's internal storage, on every app upgrade, add [MyPackageReplacedReceiver.java](library/src/main/java/com/whatsapp/stringpacks/receiver/MyPackageReplacedReceiver.java) and [PackFileDeletionService.java](library/src/main/java/com/whatsapp/stringpacks/service/PackFileDeletionService.java) to your `AndroidManifest.xml`
    ```
    <uses-permission android:name="android.permission.WAKE_LOCK"/>
    <application ...>
      ...
      <receiver android:name="com.whatsapp.stringpacks.receiver.MyPackageReplacedReceiver">
        <intent-filter>
            <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
        </intent-filter>
      </receiver>
      <service android:name="com.whatsapp.stringpacks.service.PackFileDeletionService" android:permission="android.permission.BIND_JOB_SERVICE" />
    </application>
    ```
> Note: If you want to delete old `.pack` files, from internal storage, at some other time instead of app upgrade, call `StringPacks.cleanupOldPackFiles(getApplicationContext())` whenever you want. You don't have to include [MyPackageReplacedReceiver.java](library/src/main/java/com/whatsapp/stringpacks/receiver/MyPackageReplacedReceiver.java) or [PackFileDeletionService.java](library/src/main/java/com/whatsapp/stringpacks/service/PackFileDeletionService.java) in your `AndroidManifest.xml`

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`](https://developer.android.com/reference/android/content/ContextWrapper) and [`Resources`](https://developer.android.com/reference/android/content/res/Resources) to help with that.

You need to add the following code to all subclasses of your Context class (like [`Activity`](https://developer.android.com/reference/android/app/Activity) and [`Service`](https://developer.android.com/reference/android/app/Service)) to ensure the strings are read from `.pack` files instead of Android system resources.

```java
// Java

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

```kotlin
// Kotlin

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

If all of the following conditions meet, you need to override `getResources()` function also in your `Activity`
1. App's `minSdkVersion` is < 17
2. You have a dependency on `androidx.appcompat:appcompat:1.2.0`
3. Your Activity extends from [`AppCompatActivity`](https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity)

```java
// Java

private @Nullable StringPackResources stringPackResources;
@Override
public Resources getResources() {
  if (stringPackResources == null) {
    stringPackResources = StringPackResources.wrap(super.getResources());
  }
  return stringPackResources;
}
```

```kotlin
// Kotlin

private @Nullable var stringPackResources:Resources? = null
override fun getResources(): Resources? {
  if (stringPackResources == null) {
    stringPackResources = StringPackResources.wrap(super.getResources())
  }
  return stringPackResources
}
```

Your Android application also needs to use a custom [`Application`](https://developer.android.com/reference/android/app/Application), which needs to include the following code to ensure the strings are read from `.pack` files.

```java
// Java

@Override
protected void attachBaseContext(Context base) {
  StringPackIds.registerStringPackIds();
  StringPacks.getInstance().setUp(base);

super.attachBaseContext(base);
}

private @Nullable StringPackResources stringPackResources;
@Override
public Resources getResources() {
  if (stringPackResources == null) {
    stringPackResources = StringPackResources.wrap(super.getResources());
  }
  return stringPackResources;
}
```

```kotlin
// Kotlin

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

super.attachBaseContext(base)
}

private @Nullable var stringPackResources:Resources? = null
override fun getResources(): Resources? {
  if (stringPackResources == null) {
    stringPackResources = StringPackResources.wrap(super.getResources())
  }
  return stringPackResources
}
```

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.

### Region specific locales & Fallback

You can map multiple regions into a single `.pack` file using `pack_id_mapping` in [config.json](library/templates/config.json). For example

```json
pack_id_mapping = {
  "es-rMX": "es",
  "es-rES": "es"
}
```

Here, translations in `"es"`, `"es-MX"` and `"es-ES"` locales would be packed into `strings_es.pack` file.

If you are supporting any of the following features, you need to implement [StringPacksLocaleMetaDataProvider.java](library/src/main/java/com/whatsapp/stringpacks/StringPacksLocaleMetaDataProvider.java) and register the provider in your custom `Application` class
1. Packing translations for multiple locales (for example, `es-MX`, `es`) in to one `.pack` file, or
2. Fallback feature, or
3. Supporting region specific locales

```java
// Java

@Nullable private final StringPacksLocaleMetaDataProvider metaData = new LocaleMetaDataProviderImpl();
@Override
protected void attachBaseContext(Context base) {
  StringPackIds.registerStringPackIds();
  StringPacks.registerStringPackLocaleMetaData(metaData);
  StringPacks.getInstance().setUp(base);

super.attachBaseContext(base);
}
```

```kotlin
// Kotlin

private @Nullable var metaData:StringPacksLocaleMetaDataProvider? = LocaleMetaDataProviderImpl()
override fun attachBaseContext(base: Context?) {
  registerStringPackIds();
  StringPacks.registerStringPackLocaleMetaData(metaData);
  StringPacks.getInstance().setUp(base);

super.attachBaseContext(base);
}
```

Take a look at [LocaleMetaDataProviderImpl.java](sample/app/src/main/java/com/whatsapp/stringpacks/sample/LocaleMetaDataProviderImpl.java)  in the sample app for reference.

### 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:
```bash
python3 ./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.

&nbsp;

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.
```

StringPacks

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README