Read Active HMI Language in TIA Portal via HMIRuntime.Language

Problem: Detecting the Active HMI Language

In TIA Portal projects that span multiple regions or operator nationalities, knowing which language is currently active on a Siemens HMI panel is a recurring requirement. Typical use cases include:

• Displaying a country flag on a language toggle button.
• Conditioning helper text, units, or symbols on the active project language.
• Forwarding the active language index to the PLC for logging, audit, or report header stamping.
• Driving background or color schemes that change per locale.

Project text fields handle translation natively through the "Project texts" editor, but the runtime language index is not exposed as a direct HMI tag in the HMI tag table. There is no built-in internal tag whose name resolves to the active language. The runtime does maintain the value internally; the only access path is the HMIRuntime.Language object property inside a script. Without that script path, integrators are forced to maintain a duplicate state variable that is set whenever the SetLanguage function executes, and that state variable drifts as soon as the operator selects a language from a built-in language selector, from a recipe, or via a PLC-driven SetLanguage through area pointers.

This reference documents the supported method to read the active language using HMIRuntime.Language, compares it against a graphic-list-based flag indicator, and shows how to wrap either method inside a reusable TIA Portal library type (faceplate-style object) so the same component can be dropped into 2 to 9 panels per project across 40+ project machines without per-instance rework. The target environment is TIA Portal V13 SP1 Update 9 and later (V15, V15.1, V16, V17, V18, V19) on WinCC Comfort, WinCC Advanced, and WinCC Professional. The Basic panel line (KTP400 Basic, KTP700 Basic, KTP1200 Basic) does not support scripts and must use the graphic-list path.

HMIRuntime.Language Property and Standard Language IDs

The HMIRuntime object is the runtime API entry point available in VB scripts and in the C script engine of WinCC Comfort/Advanced. Its Language property returns the language ID of the currently active runtime language. The property is documented in the Siemens Industry Online Support entry 109478713 — HMIRuntime objects in WinCC Comfort/Advanced.

Property signature (VB script, WinCC Comfort/Advanced):

The same property is writable from a script (subject to project language enablement):

Behavior on read:

• Returns the decimal language ID (LCID) of the currently displayed panel language.
• Updates whenever the operator triggers a language change, whether via the language button, a configured event, the SetLanguage PLC area pointer, or a recipe change.
• Is independent of the project editor language; it always reflects the runtime locale.
• Is available in global scheduled tasks, screen events, and tag-change triggers on Comfort, Advanced, and Professional panels.
• Returns 0 if no runtime language is enabled (configuration error, not a runtime fault).

Standard language IDs returned by HMIRuntime.Language match the WinCC language ID table. The most relevant values for European, North American, and Asian deployments are listed below.

For the full list of supported locales, see the WinCC Comfort/Advanced manual section "Supported languages and fonts" in the TIA Portal Help (Help > Contents > Visualization > Languages > Language support). Confirm any locale against the target runtime version because support has expanded between V13 and V19.

Method 1: VB Script on a Global Scheduled Task

The cleanest implementation places a single VB script on a 1-second (or 500 ms) global scheduled task that mirrors HMIRuntime.Language into an internal HMI tag. The internal tag can then be used as the source for a graphic list, for arithmetic comparison, for forwarding to the PLC, or as the binding target of any HMI object.

Procedure:

1. Open the HMI device configuration in TIA Portal.
2. In the project tree, expand "HMI tags" and create an internal tag named ActiveLanguageID of data type Int with a length of 2 bytes. Set the acquisition cycle to 1 s.
3. Right-click "Schedules" > "Global schedules" and add a new schedule (e.g. LanguagePoll_1s).
4. Set the trigger to "Cyclic" with an interval of 1 s. For sub-second resolution use 500 ms; the Comfort runtime handles this without measurable CPU impact on any panel from KTP700 Comfort upward.
5. Add a VB script event to the schedule and paste the following code:

6. Compile the project and download to the panel.

7. Open the HMI tag list online (HMI tags > Monitor) and confirm the value updates whenever you cycle the language with the SetLanguage function on a button.

The advantage of this approach is that any HMI object — buttons, IO fields, symbol libraries, graphic lists — can be linked to ActiveLanguageID through standard HMI tag references, without the script being embedded in the faceplate. The disadvantage is that the value is updated only at the trigger interval, not on the exact millisecond the language changes. For toggle-button feedback this latency is imperceptible (≤ 1 s). For audit-trail purposes, a tighter acquisition cycle on the PLC-side area pointer is recommended (see the verification section below).

To extend the same script to also forward the value to the PLC, add a second line:

where PLC_HMI_ActiveLanguageID is an HMI tag connected to a DB word in the PLC via the standard S7 connection.

Method 2: Graphic List with Country Flags

For Basic panels that do not support scripting, or for projects where the active language only drives a visual flag icon, a graphic list provides a zero-script solution. The graphic list maps integer values to PNG/SVG graphics, and the button uses the "Graphic list" mode to display the graphic whose value matches the bound tag.

Procedure:

1. Create or import the country flag graphics (PNG, 24-bit with alpha channel, suggested size 32 × 32 or 48 × 48 px) into the project graphics folder under "Project graphics".
2. Open the HMI tag list and confirm you have an internal Int tag whose value reflects the current language. If you have a PLC that already holds the language index, you may bind the graphic list to that external tag instead.
3. In the project tree, double-click "Graphic lists" and create a new list (e.g. LanguageFlagList).
4. Add one entry per supported language. Set the value to the matching HMIRuntime.Language ID and assign the flag graphic.

5. On the screen where the language toggle should appear, drop a button. Set "Width × Height" to a size that fits the flag (recommended minimum 60 × 30 px).

6. In the button properties, set "Graphic" mode to "Graphic list" and bind the list LanguageFlagList to the ActiveLanguageID tag (or to the language index tag from the PLC).

7. On the "Click" event of the button, configure the system function SetLanguage with mode "Toggle".

8. Compile and download.

The button now always shows the flag of the language the panel is currently displaying, and clicking the button cycles to the next configured language. The graphic list "default graphic" is used whenever the bound tag value does not match any entry — bind it to a neutral flag (e.g. "globe.png") to avoid blank buttons if the PLC writes an unconfigured LCID.

SetLanguage System Function: Modes and Edge Behavior

The SetLanguage system function is the only way to change the runtime language from a button, from a script, or from a PLC area pointer. It supports four modes that determine how the next language is selected.

Common pitfalls with SetLanguage:

• Index 0 is invalid. Calling SetLanguage with index 0 is a no-op or falls back to the default, depending on the firmware version. Always use 1-based indices.
• LCID must match a runtime language. The script-side write HMIRuntime.Language = 1031 fails silently if German is not enabled in the project.
• Toggle order is fixed at compile time. To re-order the cycle, reorder the entries in Project > Languages > Runtime languages and recompile.
• There is no onChange event for the language. A scheduled task that polls HMIRuntime.Language at 500 ms or 1 s is the standard mechanism to detect changes for downstream actions.

For HMIRuntime.Language to return valid data, at least one runtime language must be enabled in the project, and the script must run on a context where HMIRuntime is bound (global schedule, screen event, tag event — not on a non-script-capable object).

Building a Reusable Library Object for Multi-Project Deployment

For installations where the same toggle appears on 43+ projects and 2–9 panels each, encapsulating the solution in a TIA Portal master copy / library type pays off quickly. The recommended structure is a faceplate with a small interface, an embedded graphic list, and a button event pre-wired to SetLanguage. Updating the type once propagates to every instance on the next Library > Update instances action.

Library object interface (tags exposed by the faceplate):

Implementation steps inside the library type:

1. Create a new faceplate named LanguageToggleButton in the master library project.
2. Add a graphic list variable property mapped to LanguageIndexTag.
3. Add the button with a "Click" event calling SetLanguageToggle.
4. Inside the faceplate, add a "Change" event on the LanguageIndexTag that writes the value into a local property — this lets instances override the source tag without recompiling the faceplate.
5. Publish the faceplate to the master library with semantic version stamp (e.g. [email protected]) so a maintenance technician can confirm the deployment level in the field.

With this structure, deploying to a new project becomes a three-step action: drag the faceplate onto the screen, confirm the LanguageIndexTag name (the default matches ActiveLanguageID from the script in Method 1), and compile. There is no per-panel scripting, no per-panel graphic list configuration, and no drift between instances because the source graphics, mapping table, and script are all inside the type.

Interface Options When No Script Is Available

If the runtime platform does not support scripts (WinCC RT Basic, WinCC Flexible RT on older panels), the library object can accept a precomputed tag that the PLC keeps in sync. The PLC strategy is:

1. Define a data block tag, e.g. DB_HMI.HMI_ActiveLanguageID : INT on an S7-1200/1500 or DB100.DBW0 on a legacy S7-300/400.
2. On every operator action that changes language, the PLC also updates this tag (e.g. as part of the same FC that processes the SetLanguage bits coming from the area pointer).
3. On the first cycle after power-up, the PLC can read back the current language from a status word in the area pointer to resynchronize the tag.

This is more brittle than the script approach because the PLC and the panel can disagree during power-on, but it is the only way to drive a graphic list on Basic panels. Combine the two: keep the script on Comfort/Advanced for the language index, and mirror the value into a PLC DB tag if downstream logic needs it.

PLC Integration, Logging, and Recipe-Driven Changes

In most production environments the active language must be available in the PLC for two reasons: the controller can stamp the language into production logs and batch reports, and the controller can drive a localized error or status message overlay when the HMI is in operator mode. The integration is straightforward once the ActiveLanguageID HMI tag is established.

PLC tag definition (S7-1200/1500 example):

HMI side configuration:

1. Add a new HMI connection of type "S7-1200/1500" (or "S7-300/400" for legacy controllers).
2. Drag DB_HMI_Language.HMI_ActiveLanguageID from the PLC tag list into the HMI tag list. The HMI tag is created automatically with the matching data type.
3. On the scheduled task that runs the HMIRuntime.Language script, add a second line that writes the same value to the HMI tag pointing at the PLC DB:

4. Compile and download both the HMI and PLC projects. Confirm with a watch table that the value updates on the controller side whenever the operator changes language.

For controllers that do not support S7-optimized connections, use an absolute address such as DB100.DBW0 for the language ID. The access path is configured under the HMI connection properties and does not affect the HMIRuntime script on the panel side.

Using the Active Language for Logging and Reports

Once the language ID is in the PLC, the controller can decode it to a human-readable string and embed it in batch reports, audit trails, and email notifications. A small lookup block reduces the work for the operator when reading the log line.

The 2-character ISO code is sufficient for log lines and emails. A more verbose label can be built by indexing into a string array if the report consumer requires it. Embed #HMI_ActiveLanguageName in your batch report header template and your operators will see the panel's active language at the time of each event, not the language of the report viewer.

Recipe-Driven Language Change

Some lines drive the language from a recipe (e.g. the operator picks a recipe whose name and units are localized). The recipe transfer can include a language ID; when the recipe is loaded, the SetLanguage system function is called as part of the recipe import. The ActiveLanguageID tag follows within the next scheduled-task tick. Place the SetLanguage call in the "OnRecipeLoaded" event, not in the "OnRecipeSelected" event, to avoid an unnecessary language switch when the operator simply browses recipes.

Unicode, Fonts, and Migration from WinCC Flexible

Languages such as Russian (Cyrillic), Greek, Chinese (Simplified), and Japanese require fonts installed on the HMI panel and the corresponding project text editor locale. The HMIRuntime.Language property only reports the language ID; it does not validate that the required font is loaded. If the operator selects a language whose font is missing, text shows as boxes or "?" characters, but the language ID will still report the correct value.

Font verification procedure:

1. In the TIA Portal Help, search for "Supported languages and fonts".
2. Confirm that the locale (e.g. ru-RU) is listed in both the engineering station and the target runtime's supported fonts table.
3. If the locale is supported only on the engineering station, install the matching "WinCC ES Loadable Fonts" package on the panel or runtime PC.
4. Recompile and re-download after every font change.

Common failure mode on legacy panels: WinCC Flexible projects upgraded to TIA Portal V13 SP1 may lose the Cyrillic or Asian font references during the migration. The language ID works, the language toggle button works, but the labels still render as boxes. The fix is in Project > Languages > Runtime languages > Font assignments, not in the language toggle itself.

WinCC Flexible projects migrated to TIA Portal V13 SP1 or later also lose the "GetLanguage" C-script function call. The replacement is the same HMIRuntime.Language read documented here. Migration procedure:

1. Open the migrated project in TIA Portal.
2. Search for the string "GetLanguage" across the project. Each occurrence points to a C script that needs updating.
3. Replace the C script with a VB script equivalent, e.g. SmartTags("ActiveLanguageID") = HMIRuntime.Language.
4. Compile. The cross-compiler will flag any C scripts that still reference the old API.
5. Download to the panel and verify against the verification procedure in the next section.

For projects migrated from ProTool / WinCC Flexible ≤ 2008, the language toggle button event may still call the old SetLanguage function with a numeric language code. Confirm the parameter matches one of the enabled runtime language LCIDs, not a slot index.

Additional Edge Cases

• Operator vs. service mode. On Comfort panels the language list in the control bar is not always reachable from service mode. Place a language toggle button on a screen accessible in both modes to give service technicians a way to switch without exiting.
• Multiple language toggle buttons on the same screen. Two buttons on the same screen will both react to HMIRuntime.Language; if they use the same graphic list, both update simultaneously. If they use different lists (e.g. one with the flag and one with the ISO code), bind both to the same ActiveLanguageID tag.
• SetLanguage area pointer conflicts. The Coordination area pointer uses bit 4 to trigger a language change. If a button uses both the system function SetLanguage and the area pointer, the last writer wins. Pick one mechanism per panel and document the choice.
• Multi-runtime PC installations. On WinCC Runtime Professional with multiple monitors, each window can have its own language. The HMIRuntime object is per-window. To get the language of a specific monitor, scope the script to that window's screen object.
• V13 SP1 Update 9 specifics. On V13 SP1 Update 9 the HMIRuntime.Language read is supported but the property is not present in the IntelliSense of the script editor; type it manually. Code completion for HMIRuntime was expanded in V15.
• Graphic sizing rules. Button size 60 × 30 px (Comfort 4"): 24 × 16 flag. Button size 100 × 40 px (Comfort 7" / 9"): 32 × 24 flag plus optional ISO code. Button size 140 × 60 px (Comfort 12" / 15"): 48 × 32 flag plus optional label. On Basic panels, the maximum recommended size is 32 × 32 to keep the toggle button compact in the control bar.

Cross-Version and Cross-Panel Compatibility

The V13 SP1 Update 9 baseline is the version originally referenced. The same code compiles and runs without modification on every subsequent release. From V18 onward, the system function GetLanguage lets a button read the active language into a tag without any VB script at all — this is the preferred path for new projects on the latest TIA Portal versions, falling back to the script method described above only when V13 / V15 / V16 compatibility is required.

Verification Procedure and Test Plan

Field verification is a 7-step procedure that confirms the wiring from the operator click to the PLC mirror.

1. Download the project to the panel.
2. Open the HMI tag list in TIA Portal (online > HMI tags > Monitor) and observe ActiveLanguageID.
3. Click the language toggle button. The tag value should change to the next runtime language ID within one cycle of the scheduled task.
4. Click the language button a second time to confirm the cycle returns to the start of the runtime language list.
5. Power-cycle the panel. After restart, the panel keeps the last-selected language; the ActiveLanguageID tag should report the same value as the displayed language within one scheduled-task tick.
6. Force a change from the PLC side using the SetLanguage area pointer. The tag should follow without a script recompile.
7. If the value is mirrored to the PLC, open a watch table on the controller and confirm the DB word updates within one acquisition cycle (default 1 s).

Pass criteria: ActiveLanguageID matches the on-screen language in every test, including after power cycle, language change from PLC, and language change via the built-in language selector on the control bar. If the tag is mirrored to a PLC DB word, the watch table value matches the HMI tag value with at most one acquisition cycle of skew.

Test Plan and Acceptance Criteria

A complete test plan covers the basic toggle, the power cycle, the PLC-driven change, the recipe-driven change, the logging integration, and the multi-button scenario. The matrix below maps each test case to the expected value of ActiveLanguageID.

Run the full matrix on at least one panel per panel family in the fleet. A Comfort 7" toggle that passes is not necessarily representative of a Comfort 15" with a different firmware revision; the script behavior is identical, but the display refresh and the SetLanguage acquisition cycle can differ.

Troubleshooting Matrix

Field Commissioning Tips and Related References

• Don't duplicate the script. If the same polling script is placed on multiple tasks, the last writer wins. A single global scheduled task is sufficient for the entire project.
• Don't bind the graphic list to a string tag. The list uses the raw integer value; binding to a string tag will always display the "no match" graphic.
• Watch the cycle time on the area pointer. The SetLanguage area pointer on Comfort panels updates at the configured acquisition cycle. 1 s is typical; lower it to 200 ms for snappier operator feedback if the PLC supports it.
• Translate the flag tooltip. A common miss: the flag graphic is language-aware, but the tooltip text is not. Add the tooltip to "Project texts" so it follows the runtime language.
• Document the library object version. A library type that is updated on a 43-project fleet needs a version stamp inside the faceplate (visible on screen 1) so a maintenance technician can confirm the deployment level.
• Tag the scheduled task. Rename the global schedule to LanguagePoll_1s instead of the default Schedule_1 so it survives renames and project merges.
• Avoid language bit conflicts. The Coordination area pointer's bit 4 is the "language change" bit. If you repurpose the same word for other coordination (date/time, user change, etc.), keep the bit assignments documented at both the PLC and HMI ends.

Related Properties, Functions, and Documentation

For deeper coverage, the Siemens Industry Online Support entry 109478713 — HMIRuntime objects in WinCC Comfort/Advanced documents every property of the HMIRuntime object, and the WinCC Comfort/Advanced manual section "Working with system functions" in the TIA Portal Help enumerates the four SetLanguage modes. The TIA Portal V13 SP1 Update 9 release notes confirm that HMIRuntime.Language was available from V12 SP1 onward, so projects migrated from WinCC Flexible can be updated in place without rewiring the language infrastructure.

FAQ