feat: Localized patch description and localized patch option descriptions

[LisoUseInAIKyrios]

Patch descriptions and options should be localizable, which means patches need to bundle their own English and localized text files.

 

Localized file types

The main file options are Json, property files, or xml, but only property and xml files have Java/Android built-in support to automatically load the correct localized resource for the environment:

// Loads the correct translation file for patches-strings.xml based on the device environment
val bundle = ResourceBundle.getBundle("patch-strings", locale)

 

How will patcher discovers the localized string files

To be determined.

Easiest is to use a fixed file name or a fixed sub directory inside the patches mpp file, and patcher always load patch string resource files from there.

 

Where do patches declare their strings?

To be determined.

The easiest is to have one language file for each language in a repo, and all patches declare their patch description and option descriptions inside that single English file. Using a single English file for an entire repo makes localization easy, and dramatically reduces the complexity at the cost that deleting a patch means being more careful cleaning up unused patch strings that may go unnoticed.

[LisoUseInAIKyrios]

I'm adding this now, and I'm trying to make the decision to use json or property files.

Json

✅ Allows spaces for keys so patch name can be a direct key to a dictionary of other values (name, title, patch options, etc).
✅ Can organize patch options as a nested dictionary inside the patch element. This is both good and bad because it's more complicated than a flat structure like properties.
❌ Requires using JSON lib. Not much of a concern since Kotlin provides json, but still not as great as built in java properties.
❌ Does not automatically handle loading of localized resources. Will require using outside code or writing our own to handle looking up the correct localized json file for the environment. This is one of the biggest drawbacks.
❌ Cannot add comments to JSON. No informal comments, no instructions for translation context, no informal comments to organize the json. This is a big downside for translations since any context must be manually added on Crowdin after uploading (which is also after the AI translations have already run without any context).
❌ No reason to need nested data structures when patch names and patch option keys must already be unique -- patch names and option keys are suitable as lookup keys.

Example json localized file:

{
  "Enable debugging": {
    "name": "Enable debugging",
    "description": "Adds options for debugging and exporting Morphe logs to the clipboard."
  },

  "GmsCore support": {
    "name": "GmsCore support",
    "description": "Allows the app to work without root by using a different package name when patched using a GmsCore instead of Google Play Services."
  },

  "Theme": {
    "name": "Theme",
    "description": "Adds options for theming and applies a custom background theme (dark background theme defaults to pure black).",
    "options": {
      "darkThemeBackgroundColor": {
        "title": "Dark theme background color",
        "description": "Can be a hex color (#RRGGBB) or a color resource reference.",
        "values": {
          "pure_black": "Pure black",
          "material_you": "Material You",
          "classic_(old_youtube)": "Classic (old YouTube)"
        }
      }
    }
  }
}

Property files:

✅ Simple. Use flat file with no nested json objects. Easier to edit by hand.
✅ Handles localization at the java library level. No third party or custom code required. IDE even shows all localized files as a single bundle. Looking up string is as simple as ResourceBundle bundle = ResourceBundle.getBundle("messages", locale); bundle.getString("enable_debugging.name");
❌ Doesn't allow spaces for key names. Localized patch names must sanitize the name into a key by spaces with - or_
❌ Requires using adhoc key naming system for patch options, which isn't as rigidly structured as JSON. This isn't so much of a concern since patch option keys are unique and the patch preference title/description/entry/values already uses adhoc system of _title / _description / _entries / entry_values / etc so this is just a continuation of that.

Example property file entries:

# "Enable debugging" patch
enable_debugging.name=Enable debugging
enable_debugging.description=Adds options for debugging and exporting Morphe logs to the clipboard.

# "GmsCore support" patch
gmscore_support.name=GmsCore support
gmscore_support.description=Allows the app to work without root by using a different package name when patched using a GmsCore instead of Google Play Services.


# "Theme" patch
theme.name=Theme
theme.description=Adds options for theming and applies a custom background theme (dark background theme defaults to pure black).

darkThemeBackgroundColor.title = Dark theme background color
darkThemeBackgroundColor.description = Can be a hex color (#RRGGBB) or a color resource reference.
darkThemeBackgroundColor.values.pure_black = Pure black
darkThemeBackgroundColor.values.material_you = Material You
darkThemeBackgroundColor.values.classic_(old_youtube) = Classic (old YouTube)

[LisoUseInAIKyrios]

The last option is XML, which I don't think is a good choice over property files.

XML

✅ Same file type as Morphe localized string resources, but this is specific to Morphe and third party patches would be more appropriate to use json or property files to avoid resource decoding/compilation and the hassle of adding strings to the existing app strings.xml files. In hindsight the patches could have used json or property files for all string resources and avoided the hassle of adding string resources to the patched app and instead it looks up strings from it's own json/property files.
✅ Java resource bundles support localized lookup of XML (only XML and properties have this feature)
❌ Requires using an xml library which is more complicate and less convenient than using java natively supported property files with simple key lookups.
❌ XML nested structures do not play nice with Crowdin and xml strings must be a flat file with no nested elements, meaning no nested benefit that JSON provides.
❌ Uses different string declaration rules than Android strings.xml files, particularly no raw strings like Android strings. The same string declaration in the patches add resources strings.xml cannot always be used exactly as-is, creating confusion and two different sets of rules for android strings vs patch XML strings.
❌ Provides no tangible benefit over property files while being very similar to, but requires more complexity to use.

So, basically the only benefit of xml is the familiarity to the existing patch extension string files. But I think that's not a great reason to accept the compromises and extra hassles of xml.

[LisoUseInAIKyrios]

I am leaning towards using property files because they're simpler and Java has native built in support.

[LisoUseInAIKyrios]

After realizing there is no way to add comments to the json to include comments for translations, I think JSON is eliminated just for that reason.

[LisoUseInAIKyrios]

Going to initially use properties. There are diffences how raw strings are handled by Android strings.xml files and handled by Java XML parser.

So the main benefit of using XML because it's the same as the patches strings.xml is mostly lost, and using the same file type actually becomes a potential for mistakes because the two files looks the same but some of the semantics are different and each require slightly different rules. Two different file types makes it clear it's different.