{"id":16747958,"url":"https://github.com/amake/gradle-android-l10n-fix-plugin","last_synced_at":"2026-05-04T16:37:23.432Z","repository":{"id":74600208,"uuid":"128084943","full_name":"amake/gradle-android-l10n-fix-plugin","owner":"amake","description":"A Gradle plugin to fix the Android language resource contamination problem","archived":false,"fork":false,"pushed_at":"2019-02-05T01:55:43.000Z","size":254,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-22T15:43:20.064Z","etag":null,"topics":["android","gradle","l10n","localization"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amake.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-04T15:47:12.000Z","updated_at":"2020-03-31T08:56:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"cfe33256-36e5-4804-b9b2-387c930d09b8","html_url":"https://github.com/amake/gradle-android-l10n-fix-plugin","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amake%2Fgradle-android-l10n-fix-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amake%2Fgradle-android-l10n-fix-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amake%2Fgradle-android-l10n-fix-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amake%2Fgradle-android-l10n-fix-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amake","download_url":"https://codeload.github.com/amake/gradle-android-l10n-fix-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243818205,"owners_count":20352629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","gradle","l10n","localization"],"created_at":"2024-10-13T02:11:21.747Z","updated_at":"2026-05-04T16:37:23.356Z","avatar_url":"https://github.com/amake.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gradle Android L10N Fix Plugin\n\nThis plugin provides solutions for the [compile-time and runtime language\nresource contamination\nproblems](https://gist.github.com/amake/0ac7724681ac1c178c6f95a5b09f03ce) that\nbreak display-language fallback according to user preferences on Android 7 and\nlater.\n\n## What?\n\nStarting in Android 7, instead of choosing a single language for the user\ninterface, you can set a priority list of languages. Let's say you chose:\n\n1. Spanish\n2. Italian\n3. English\n\nNow consider an app that supports both Italian and English. With your preferred\nlanguages set to the above, the OS knows to show it to you in Italian rather\nthan English. This is display-language fallback.\n\nThis mechanism can be broken in two different ways. For more details see\n[Correct localization on Android\n7](https://gist.github.com/amake/0ac7724681ac1c178c6f95a5b09f03ce).\n\n## Do I need this?\n\n- Does your app run on Android 7.0 or 7.1.1 (SDK 24 or 25)?\n- Does your app support more than one display language?\n- Do you use the AppCompat library? Any Google Play Services libraries? Anything\n  else with its own language resources in languages you don't support?\n- Do you use\n  [WebView](https://developer.android.com/reference/android/webkit/WebView.html)\n  at all?\n\nIf so, your app probably suffers from [language resource\ncontamination](https://gist.github.com/amake/0ac7724681ac1c178c6f95a5b09f03ce),\nwhich prevents some users from seeing the app in their preferred language.\n\nGo check how many localizations Google thinks you support on the Google Play Console:\n\n![Too many localizations](web/google-play-console-localizations.png)\n\nSurprised?\n\nYou can also check your APK directly yourself. Here's the result for the default\nnew project template app created by Android Studio 3.1:\n\n```\n$ ./gradlew assemble\n\nBUILD SUCCESSFUL in 5s\n51 actionable tasks: 1 executed, 50 up-to-date\n$ $ANDROID_HOME/build-tools/27.0.3/aapt d --values resources app/build/outputs/apk/release/app-release-unsigned.apk resources.arsc | grep -E 'config ([a-z]{2}(-r[A-Z]{2})?|b\\+[a-zA-Z+]+):' | sort | uniq\n      config af:\n      config am:\n      config ar:\n      config az:\n      config b+sr+Latn:\n      ⋮\n      (plus 78 more)\n```\n\n## How does it work?\n\n### Compile-time contamination fix\n\nThe compile-time fix works by inspecting your `res` folder hierarchy to detect\nwhat locales your app supports, and filters out unwanted locales by setting the\nappropriate\n[`resConfig`](https://google.github.io/android-gradle-dsl/current/com.android.build.gradle.internal.dsl.ProductFlavor.html#com.android.build.gradle.internal.dsl.ProductFlavor:resConfig%28java.lang.String%29)\nfilters.\n\nThis is essentially a reimplementation of `resConfig 'auto'`, which was\n[deprecated in Android Gradle Plugin\n3.1](https://android.googlesource.com/platform/tools/base/+/6b7799c36f1ba5194f73f5c14a7b0365a8428714%5E%21/)\ndue to issues with multi-module projects and `aar` libraries. This plugin\naddresses some of the issues, but not all. See [Limitations](#limitations) for\nimportant information.\n\n### Runtime contamination fix\n\nThe plugin offers two facilities for dealing with runtime resource contamination\nfrom e.g. referencing the Chrome-based\n[WebView](https://developer.android.com/reference/android/webkit/WebView.html)\nclass:\n\n- `L10nFixActivity`: An `Activity` class that ensures that only supported\n  locales are held by its base context. This is needed to keep locales correct\n  post-contamination through configuration changes such as device rotation.\n- `L10nUtil`: A utility class offering static methods for dealing with supported\n  locales, most importantly:\n  - `fixLocales(Resources)`: Call this on your activity's resources immediately\n    after referencing `WebView` to restore the correct locales.\n\nThe above features are backed by `BuildConfig.SUPPORTED_LOCALES`, an array of\nsupported locales generated from the information collected for the compile-time\ncontamination fix.\n\n*Note that runtime contamination appears to be fixed in Android 8+; the above\nfeatures essentially turn into no-ops when they aren't necessary, so it is safe\nto use them on Android 8+.\n\n## Requirements\n\nGradle must be invoked with Java 8 (your app need not use Java 8 language\nfeatures).\n\n## Usage\n\n1. Add the plugin to your root project\n   ([instructions](https://plugins.gradle.org/plugin/com.madlonkay.android-l10n-fix))\n2. Apply the plugin to your Android projects. These are any projects to which a\n   `com.android.*` plugin is applied.\n    ```\n    android {\n        ...\n    }\n\n    apply plugin: 'com.madlonkay.android-l10n-fix'\n    ```\n   This activates the compile-time fix*. Note:\n    - This plugin should be applied anywhere *after* the `android {}` block\n    - Apply this plugin to all Android projects that have locale-specific\n      resources\n    - *If you manually set supported locales in `resConfigs`, the plugin will\n      not attempt to automatically detect supported locales. If you want the\n      plugin to set `resConfigs` automatically, be sure to remove any manually\n      set locales. See [Limitations](#limitations) for details.\n3. (Optional) Configure the plugin with a `l10n` block. See below for options.\n4. To activate the runtime fix:\n   1. Make your `Activity` classes extend `L10nFixActivity`\n   2. Anywhere you first reference the `WebView` class (loading a layout\n      containing a `WebView`, using any `WebView` static methods), immediately\n      afterwards call `L10nUtil.fixLocales(getResources())`\n\n## Configuration\n\nIn the same project you applied the plugin to:\n\n```\nl10n {\n    defaultLocale = 'en'\n}\n```\n\nOptions:\n\n- `defaultLocale`: The locale for \"default\" resources (i.e. in `values`, not\n  `values-XX`). This defaults to `en`. Note that if you need to customize this\n  (your default resources are not in English) you should also copy your\n  resources to the appropriate `values-` directory ([see here,\n  p28](http://www.unicodeconference.org/presentations/TS1T3-Nita-Pournader.pdf)).\n\n## Limitations\n\nAn Android Studio Team member described the [reason for removing `resConfig\n'auto'`](https://www.reddit.com/r/androiddev/comments/8eb8vm/android_gradle_plugin_31x_commit_history/dy09tv1/)\nas such:\n\n\u003e `auto` only looked at the app module to figure out what to package instead of\n\u003e all your sub-modules. So if you have a very empty app module (say no UI\n\u003e strings in there), and all your UI in sub-modules, then the packaging would be\n\u003e wrong.\n\u003e\n\u003e Even if we made this work, it's impossible to know whether remote dependencies\n\u003e (consumed via `aar`) were part of your own code or were 3rd party\n\u003e libraries. (some companies publish their own shared code as `aar` via internal\n\u003e repos)\n\u003e\n\u003e So the issue is what should we consider to be yours vs not yours and how to\n\u003e make this work 100% reliably.\n\u003e\n\u003e Ultimately the most reliable way to make this work is for the dev to\n\u003e explicitly list what resource to include.\n\nThis plugin does correctly handle multiple modules if:\n\n- All of your resource locales can be determined by inspecting the filesystem\n(there is a `values-XX` folder for each supported locale)\n- All modules support the set of locales detectable from the filesystem\n\nHowever it cannot handle:\n\n- Complex setups where different modules support different sets of locales\n- Locales where resources are generated (and not detectable from the filesystem)\n- Locales present only inside `aar`s\n\nIf your app has any of the above, you should manually set your supported locales\nin `resConfigs` as officially recommended. When manually set `resConfigs` are\npresent, this plugin does not attempt to auto-detect supported locales.\n\n## License\n\nApache 2.0\n\n## See also\n\n- [Correct localization on Android\n  7](https://gist.github.com/amake/0ac7724681ac1c178c6f95a5b09f03ce)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famake%2Fgradle-android-l10n-fix-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famake%2Fgradle-android-l10n-fix-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famake%2Fgradle-android-l10n-fix-plugin/lists"}