---
title: "Locale Formats and Language Tags"
description: "Explains how Ignition represents locales as strings, the difference between the legacy underscore format and BCP-47 language tags, and which format each function or property expects."
---

# Locale Formats and Language Tags

> Explains how Ignition represents locales as strings, the difference between the legacy underscore format and BCP-47 language tags, and which format each function or property expects.

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`](https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html) 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](https://developer.mozilla.org/en-US/docs/Glossary/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`](appendix/scripting-functions/system-util/system-util-translate.md) | Both | — | Language tag |
| [`system.util.modifyTranslation`](appendix/scripting-functions/system-util/system-util-modifyTranslation.md) | Both | — | Language tag |
| `translate` [expression function](appendix/expression-functions/translation/translate.md) | Both | — | Language tag |
| [`system.vision.getLocale`](appendix/scripting-functions/system-vision/system-vision-getLocale.md) | — | Underscore | — |
| [`system.vision.getAvailableLocales`](appendix/scripting-functions/system-vision/system-vision-getAvailableLocales.md) | — | Underscore | — |
| Perspective session [`locale` property](ignition-modules/perspective/perspective-sessions/session-properties.md) | Language tag | Language tag | — |
| User `Language` attribute via [`system.user.editUser`](appendix/scripting-functions/system-user/system-user-editUser.md) | Both | Both | Language tag |

:::tip 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.

```python
# 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](platform/localization-and-languages/creating-translation-lists/creating-translation-lists.md) for how languages are defined.