---
title: "Localization Keys"
---
# Localization Keys
> Ignition's localization features allow you to present your project in multiple languages without duplicating views or windows. This page outlines best practices for working with project terms, component overrides, naming keys, and managing long text.
## Project Terms vs Component Terms
Project terms are shared across all components in the project. Use them for any text that appears in multiple places to avoid duplication and ensure consistency.
Component terms apply only to a single component. Use them when a component needs wording that differs from the project-wide translation. If both a project term and a component term exist with the same key, the component term takes precedence.
:::note Important
Review component definitions if translations do not appear as expected.
:::
## Using Naming Conventions with Keys
Always define a **key** for each translation term instead of using literal text. Keys act as stable identifiers that map to the correct translation, even if the visible text changes. Use unique keys that are unlikely to conflict with regular words, such as by prefixing with `#` or using dot notation like `dialog.save_changes`. Once a key is in use, keep it stable. Renaming a key breaks its mapping to translations. Keys are especially helpful for long text strings such as introductions or paragraphs, since they prevent accidental matches across multiple components.
### Preventing Unwanted Translations
Using common words as keys (such as “Auto” or “Off”) can sometimes trigger unintended translations if a project term with the same text exists. To avoid this, you can define the values as unique keys by prefixing them with `#`. This convention applies in both Perspective and Vision, although the configuration steps differ between the two modules.
#### Perspective
In Perspective, the Multi-State Button component's states, **Hand**, **Off**, and **Auto** are defined in the `states[#].text` property as `#Hand`, `#Off`, and `#Auto`. Using the prefix ensures these words are treated as keys rather than matching existing project terms.
The keys appear in the Translation Manager, where translations are defined in English and Spanish. When `session.props.locale` is set to `en-US`, the button displays the English values.
When `session.props.locale` is switched to `es-US`, the button displays the Spanish translations.
#### Vision
In Vision, the Multi-State Button component's states, **Hand**, **Off**, and **Auto** are defined in the **Multi-State Button Customizer** as `#Hand`, `#Off`, and `#Auto`. Using the prefix ensures these words are treated as keys rather than matching existing project terms.
The keys appear in the Translatable Terms panel, where translations are defined in both the component and global columns.
In Design Mode, the button displays the untranslated keys.
In Preview Mode, the button displays the translated states in English and Spanish.
### Overriding Vision Components
In this example, a Label component was added to the window and its text was set to `#Barrel`. This created a key in the Translatable Terms panel. The global term translates `#Barrel` to **Tanque**, while a component term with the same key translates it to **Barril**. Because component terms take precedence, the Label displays **Barril** instead of the project-wide value.
In Design Mode, the Label shows the raw key.
In Preview Mode, the Label displays the component translation, overriding the global term.
### Overriding Built-in Vision Messages
In addition to project and component terms, some system dialogs in Vision also use fixed text that can be overridden. These messages are not exposed as component properties, but you can still localize them by adding their text as keys in the Translation Manager. The most common examples are the **Access Denied** and **Screen Locked** dialogs.
#### Access Denied Message
When a Vision window is restricted with **Do Not Open**, an Access Denied popup appears. The text in this popup is fixed, but you can override it by adding a key in the Translation Manager.
1. In the Designer, go to **Tools** > **Translation Manager**.
2. Click the **plus**  icon, paste the following value into the **Add Item** field, and click **OK**.
```html title="Access Violation - Key"
ACCESS VIOLATION.
You do not have the privileges to open window '%s'.
```
:::note
The `%s` placeholder is replaced with the window name at runtime.
:::
3. Add a translation for the key. For example:
```html title="Access Violation - Translated Term"
ACCESS VIOLATION.
Sorry! You are not allowed to access '%s'
So sorry!
```
Now, when a user without the required permission attempts to open the window, the popup displays the translated text.
#### Screen Locked Message
The [system.vision.lockScreen](appendix/scripting-functions/system-vision/system-vision-lockScreen.md) function in a [Client Timer Script](ignition-modules/vision/scripting-in-vision/client-event-scripts/client-event-scripts.md) displays a popup when the client is locked. The message text is not configurable, but you can override it with a key in the Translation Manager.
1. In the Designer, go to **Tools** > **Translation Manager**.
2. Click the **plus**  icon, paste the following value into the **Add Item** field, and click **OK**.
```html title="Screen Locked - Key"
This screen has been locked by
%s
```
:::note
The `%s` placeholder is replaced with the current username at runtime.
:::
3. Add a translation for the key. For example:
```html title="Screen Locked - Translated Term"
This screen is now locked!
Either log out or type in the password for :
%s
```
Now, when the screen is locked in the client, the popup displays your translated text.
## Wrapping Long Text in Vision
In Vision you can use basic HTML tags to wrap long text values inside components that display text. This allows translations with long sentences or paragraphs to break across multiple lines.
In this example, a Label component is configured with the key `#intro_text`, and HTML wrapping is used so its text displays neatly in both English and Spanish.
1. In the **Property Editor** of a Label component, set the `text` property to a unique key. In the example below, we use `#intro_text`.
2. Open the **Translatable Terms** panel and double-click the term row to add translation values for each language.
:::note
You can open the **Translatable Terms** panel by right-clicking the component and selecting **Translations**.
:::
3. Begin the value with `` to enable wrapping.
```text title="Translation Values"
# English
This is some long text and I want it to wrap
# Spanish
Este es un texto largo y quiero que se envuelva
```
4. In **Preview Mode**, the Label displays the text across multiple lines in English and Spanish. If the component is not large enough to fit the text, only part of the wrapped content will be visible.
