Locale Formats and Language Tags

Several scripting functions, expression functions, and properties in Ignition accept or return a locale as a string. Because Ignition has to remain backwards compatible with older projects, more than one string format is accepted, and different parts of the product prefer different formats. This page explains the formats, where they are used, and recommended formats when writing new code.

Locale Objects and String Formats

Since Ignition runs on Java, Ignition locales are Java Locale objects. A Locale object determines how text, dates, and number values are translated based on a specified language. Regions can also be supplied to further define translation. For example, just English can be provided as the language, or it can be combined with a region, like the United States.

The two string formats that can be passed include BCP-47 language tags and the legacy underscore format.

BCP-47 Language Tag (Recommended)

A BCP-47 language tag uses a hyphen (-) to separate the language subtag from the region subtag:

• en — English
• en-US — English (United States)
• es-ES — Spanish (Spain)
• fr-CA — French (Canada)
• en-IE — English (Ireland)

The language subtag comes from the ISO 639 standard, and the region subtag from ISO 3166. Language tags are an open standard supported across the web, within Java, and within other systems that exchange data with Ignition. This is the recommended format to use when writing new code.

Legacy Underscore Format

The legacy format uses an underscore (_) instead of a hyphen:

• en
• en_US
• es_ES
• fr_CA

This is a Java-specific idiom rather than a general purpose, interoperable standard. It is still accepted in many places for backwards compatibility, but it is not recommended for new code. Some functions return this format, so you may encounter it when reading a locale back from Ignition.

note

For a language with no region, such as en on its own, the two formats look identical because there is no separator to differentiate them. The distinction only appears once a region is included (en-US versus en_US).

Where Formats are Used

The table below summarizes what format each function or property accepts as input and returns as output. Note that when both formats are accepted, the language tag format is always preferred.

Location	Accepts	Returns	Preferred
system.util.translate	Both	—	Language tag
system.util.modifyTranslation	Both	—	Language tag
translate expression function	Both	—	Language tag
system.vision.getLocale	—	Underscore	—
system.vision.getAvailableLocales	—	Underscore	—
Perspective session locale property	Language tag	Language tag	—
User Language attribute via system.user.editUser	Both	Both	Language tag

Converting Formats

If you need to compare or pass values returned from Vision functions in the underscore format to areas that expect language tags, simply convert the underscore to a hyphen.

Language Names Are Not Locale Identifiers

A locale identifier is a code such as es or es-ES, not the English (or native) name of the language. Passing a display name like "Spanish" or "Español" where a locale is expected will not match a defined locale, and the translation will silently fall back to the original term.

# Incorrect - "Spanish" is a language name, not a locale identifier
system.util.translate("Hello", "Spanish")

# Correct - use the language tag
system.util.translate("Hello", "es")

# Also correct - include a region when you need a specific variant
system.util.translate("Hello", "es-ES")

If you are unsure which locale codes are defined on your system, the locales you configure appear in the Translation Manager. See Creating Translation Lists for how languages are defined.