Localized App Name — Documentation

This plugin localizes your OutSystems mobile app's home-screen icon label based on the device language. When a user's phone is set to Portuguese, the icon reads "Cartão Continente". When it's set to English, it reads "Continente Card". Locales you don't ship fall back to the default app name automatically.

1. Installation

Step 1 — Reference the plugin module

This Forge component is a thin OutSystems Plugin Module that wraps the underlying Cordova plugin. In your mobile app:

1. Open the mobile app module in Service Studio
2. Go to Manage Dependencies (Ctrl+Q)
3. Find Localized App Name Plugin and tick its public elements
4. Apply

Step 2 — Add the iOS preference

In your mobile app's Extensibility Configurations property, add:

{
  "preferences": {
    "ios": [
      { "name": "CFBundleAllowMixedLocalizations", "value": "true" }
    ]
  }
}

This is required on iOS. Without CFBundleAllowMixedLocalizations, iOS silently ignores localized display names and falls back to your default app name on every device.

If you already have other preferences in this JSON, merge the iOS array carefully — keep your existing entries and add the new one.

Step 3 — Upload locale JSON files as Module Resources

For each language you want to support, create a JSON file named after the locale code and upload it as a Module Resource in Service Studio:

1. Right-click Resources in the mobile app module → Import Resource
2. Select the JSON file (e.g., en.json)
3. Set Deploy Action to Deploy to Target Directory
4. Repeat for each locale

Typical set: en.json, pt.json, es.json, fr.json, de.json, it.json — ship what your users actually use.

Step 4 — Publish and build

1. 1-Click Publish your mobile app
2. In Service Center / LifeTime, trigger a new MABS build for iOS and/or Android
3. Distribute the resulting IPA/APK as you normally would

2. JSON file format

Each locale file is a tiny JSON with two sections — one for iOS, one for Android:

{
  "config_ios": {
    "CFBundleDisplayName": "Cartão Continente"
  },
  "config_android": {
    "app_name": "Cartão Continente"
  }
}

Field reference

Both fields are optional individually — if you only have config_ios, the plugin only updates iOS (and vice versa). But typically you want both.

3. Locale codes

Name each JSON file after the locale you want it to apply to. The plugin handles platform-specific differences automatically.

Recommendation: use simple two-letter codes (en, pt, es) unless you specifically need regional differentiation. For Chinese on Android, prefer zh-CN.json / zh-TW.json over zh-Hans / zh-Hant.

4. What the plugin does at build time

On every MABS build, the plugin's after_prepare hook runs and:

1. Discovers your locale JSON files (in www/ for MABS, or other known Cordova locations)
2. For each locale, writes <locale>.lproj/InfoPlist.strings for iOS
3. Registers each iOS locale in App.xcodeproj/project.pbxproj so xcodebuild bundles it
4. Purges cordova-ios's in-memory pbxproj cache so the registration survives later signing operations
5. For each locale, writes values-<locale>/strings.xml for Android

You don't need to know any of this to use the plugin — but the build log will show these steps if you ever need to debug.

5. Testing on a device

1. Install the IPA/APK from your MABS build on a real device (or an emulator/simulator built with the appropriate simulator SDK)
2. Change the device's system language: Settings → System → Languages
3. Reboot or reinstall the app. Both iOS and Android only refresh the home-screen icon label on install or language change — restarting the app is not enough
4. The home-screen icon label should now match the new language

Note: standard MABS IPAs are device-only builds (iphoneos SDK). They cannot be installed on the iOS Simulator directly. Use a real device for iOS verification.

6. Troubleshooting

The home-screen label still shows the default name

Check, in order:

1. Did you reinstall the app after changing the language? The label only refreshes on install or language change. Restarting the app or rebooting the device alone is not enough.
2. Is CFBundleAllowMixedLocalizations set to true? On iOS, without this preference, localized display names are silently ignored.
3. Are the JSON file names exactly correct? The filename (minus .json) must be a valid locale code — pt.json not Portuguese.json.
4. Are the JSON contents valid? Open each file and confirm it parses as JSON and has a config_ios.CFBundleDisplayName or config_android.app_name key.
5. Is the device's language one you shipped? If you only have en.json and pt.json, a device set to Spanish will fall back to the default — that's expected behavior.

Plugin doesn't appear in the build at all

If cordova_plugins.js in the APK doesn't list cordova-plugin-localized-app-name, the plugin isn't being installed by MABS. Check:

• The Plugin Module is referenced in your mobile app's Manage Dependencies, with public elements ticked
• The Plugin Module has been 1-Click Published after any change to its Extensibility Configurations
• Your mobile app has been 1-Click Published after the Plugin Module was updated (consumer apps cache a snapshot of dependencies)
• If you've changed the plugin URL or version, bump the Plugin Module's metadata.version to a new value — otherwise OutSystems may serve consumer apps a cached snapshot

iOS build succeeds but no .lproj folders are in the IPA

If you can grab the MABS build log, search for lines starting with [localized-app-name]. You should see:

[localized-app-name] Reading locale files from www (N file(s): ...)
[localized-app-name] iOS  -> en.lproj/InfoPlist.strings = "..."
[localized-app-name] iOS: wrote N locale file(s).
[localized-app-name] iOS: registered N new locale(s) in Xcode project.
[localized-app-name] iOS: purged cordova-ios project file cache via ...

If the purge line is missing, you're likely running an older version. Upgrade to 1.0.5 or later.

Android build succeeds but the icon label doesn't change

Inspect the APK with unzip -p app.apk resources.arsc | strings | grep -i "values-pt" (or similar). If you don't see your locale folders, the plugin didn't run — check the build log for [localized-app-name] Android -> lines. If you do see them but the label still doesn't change, your AndroidManifest.xml probably references a string key the plugin isn't writing. By default the plugin writes app_name, launcher_name, and activity_name — which covers every Cordova-generated manifest.

7. Compatibility

8. Resources

• Source code: github.com/promonteiro89/cordova-plugin-localized-app-name
• Latest release: Releases page
• License: MIT