Skip to main content

Customizing UI Translations

Since Mango 5.7

Mango ships with translations for several languages bundled inside the core and each module. Starting in Mango 5.7, you can override or extend any of these translations by dropping standard Java .properties files into a translations override directory. This is useful for:

  • Renaming terminology to match your organization's conventions (for example, replacing "Data Source" with "Device Connection").
  • Adjusting labels for an industry vertical.
  • Adding a locale that is not bundled with Mango — drop in i18n_ko.properties and Korean speakers can select Korean from their user profile, no module installation required.

The feature is always-on. There is no enable flag in mango.properties. If an override file exists in the override directory, Mango loads it; if not, the bundled translations are used unchanged.

Override directory location​

Override files live in:

<paths.data>/translations/

paths.data is the Mango data directory (/opt/mango-data in most installations, or whatever you set paths.data to in mango.properties / the mango_paths_data environment variable). Create the translations/ subdirectory if it does not exist.

File naming​

Override files use the standard Java resource bundle naming convention:

File nameApplies to
i18n.propertiesAll locales (the "root" fallback)
i18n_<language>.propertiesAll regional variants of that language. Example: i18n_fr.properties applies to French (France), French (Canadian), and any other French variant.
i18n_<language>_<region>.propertiesA specific regional variant only. Example: i18n_es_MX.properties applies to Mexican Spanish only; un-overridden keys fall back to i18n_es.properties then to i18n.properties.

The language and region codes are the standard Java Locale codes (ISO 639 for language, ISO 3166 for region).

Locale fallback chain​

When Mango looks up a translation key for a given locale, it walks the chain from most-specific to least-specific:

i18n_es_MX.properties → i18n_es.properties → i18n.properties → bundled defaults

The first file that contains the key wins. This means you only need to override the keys you want to change at each level — everything else falls through to the next level in the chain.

File format​

Override files are standard Java properties files. Each line is a key=value pair:

# Rename "Data Source" to "Device Connection" everywhere
common.dataSource=Device Connection
common.dataSources=Device Connections

# Customize a button label
common.save=Apply Changes

To find the keys you want to override, look in the i18n.properties files inside Mango's web/modules/ directory and inside each module's JAR. The bundled keys cover labels, button text, error messages, help text, and most other UI strings.

Override precedence​

Override files load after the bundled translations on the classpath, so they always take precedence over Mango's built-in values. Inside a single override file, later entries do not override earlier entries — duplicate keys produce undefined behavior, so use each key only once per file.

If multiple override files in the chain define the same key, the most-specific locale wins (the file closer to the user's locale at the top of the chain).

Applying changes​

Translation files are cached in memory after first load, so dropping a new file does not take effect immediately:

  • Restart Mango to pick up changes (most reliable approach).
  • Alternatively, calling TranslationsCache.clearCache() invalidates the in-memory cache. There is currently no built-in REST endpoint or UI button that exposes this; restart is the recommended path.

After a restart, new and modified keys appear in the UI on the next page load.

Example: a custom regional dialect​

You support a Mexican utility company that prefers "Medidor" over the generic Spanish "Contador" for "Meter". Generic Spanish should be unchanged.

Create <paths.data>/translations/i18n_es_MX.properties:

common.meter=Medidor
common.meters=Medidores

Restart Mango. Users with their browser locale set to es-MX (or who pick "Mexican Spanish" in their profile) see "Medidor"; users on plain es continue to see whatever the bundled Spanish translation provides.

Adding a brand-new locale​

To add Korean (not bundled with Mango out of the box):

  1. Translate the keys you care about into Korean and save them as <paths.data>/translations/i18n_ko.properties.
  2. Restart Mango.
  3. Korean now appears as a selectable language on the user profile page. Any keys not overridden fall back to the root i18n.properties (which is the English source bundle).

You only need to translate the keys that matter for your users — there's no requirement to translate every key.

Troubleshooting​

SymptomCauseSolution
Override file dropped, but the UI still shows the old textThe translations cache has not been refreshedRestart Mango, or call TranslationsCache.clearCache()
File present but no keys are picked upFile name does not match the locale conventionVerify the file is named i18n.properties, i18n_<lang>.properties, or i18n_<lang>_<region>.properties (case-sensitive on Linux)
Some keys override, others do notThe keys may live in a more-specific locale file that is taking precedenceCheck whether a more-specific file in the chain (e.g., i18n_es_MX.properties) defines the same key — that file wins for matching locales
Properties file syntax errors are silently ignoredJava properties parser tolerates malformed linesCheck the Mango logs at startup; verify each line follows key=value and that backslashes and special characters are escaped per the Java properties format