WinCC Text Distributor: Translating PDL and Faceplate Texts

Overview: WinCC Text Translation Workflows

Translating HMI text in Siemens WinCC falls into two product generations with different toolchains. WinCC Classic (V7.x) and the PCS 7 OS use the Graphics Designer (.pdl pictures) and the Text Distributor add-in. WinCC Professional (TIA Portal) and the RT Advanced / RT Professional runtimes store multilingual text in the project library and the project text database, which is exported and re-imported through the TIA Portal project tree. Both paths handle faceplate types, user-defined objects, and self-made icons, but the export format, the import behavior, and the failure modes are not interchangeable.

This reference covers the Classic/PCS 7 Text Distributor workflow (the source of the most common "Object reference not set to an instance of an object" error), the Unicode-to-ANSI pitfall in Microsoft Excel, a VBA macro strategy that produces a clean .csv for translators, and the equivalent procedure in TIA Portal WinCC where the Graphics Designer and Text Distributor are not present.

WinCC Classic vs. TIA Portal: Two Translation Paths

Engineers maintaining older PCS 7 V8.0 SP1 plants should stay on the Classic path. New installations and migration targets should move to WinCC Professional so that all text lives in one TIA project.

Text Distributor Prerequisites

1. Install the WinCC option Text Distributor from the WinCC setup. It is a standalone executable, TxTpdist.exe, and is not always deployed with the base runtime.
2. Confirm the WinCC project is opened in WinCC Explorer, not in the Graphics Designer alone, because the Text Distributor walks the project database (Project.mcp) and the picture tree.
3. Verify the languages configured under Project Properties → Languages. Typical PCS 7 plants run English (0009), German (0007), and Russian (0019). Each language row must show a green status before export.
4. Back up the project folder and the picture tree (<Project>\GraCS\) before every export/import round; a malformed import can blank the language table.

Export Procedure for WinCC Classic (V7.x / PCS 7 V8.x)

1. Close the Graphics Designer so the .pdl files are not locked.
2. Start Text Distributor from the Windows Start menu: Start → SIMATIC → WinCC → TextDistributor.
3. Select Project source and choose the active WinCC project.
4. Set Output format to CSV for Excel-friendly translation, or leave the default TXT (UTF-16 LE) if the translation will be done in Notepad++, SDL Trados, or memoQ.
5. Set the source language and target language columns. The default export contains one column per configured language plus a comment column for the translator.
6. Click Export. The output file is written to <Project>\TextLibrary\<PictureName>.csv by default.
7. Open the file. The first column is the WinCC internal Text ID, the second column is the source text, the third column is the first target language, and so on.

The exported file mirrors every text literal in every .pdl picture, every faceplate type body, and every registered user-defined object. Custom icons built from primitive shapes (rectangle + text field + status display) are exported as their constituent text fields.

Unicode vs. ANSI in Excel: Pitfalls and Workarounds

Text Distributor writes .csv files in UTF-16 LE (Unicode) with a byte-order mark. When Microsoft Excel opens such a file directly, the Text Import Wizard does not run and the encoding is downgraded silently to the system ANSI code page when the user saves the workbook. Cyrillic (Russian, Ukrainian), Greek, CJK, and Arabic characters will become mojibake (?????? or Привет).

Object Reference Error: Root Cause and Resolution

Symptom: the export log shows rows tagged "unknown object" and "unknown subobject", and a dialog appears with the .NET message:

Root causes observed in the field, in order of frequency:

1. Stale picture cache. A .pdl was modified while the Graphics Designer was open in a second session. Close all designer instances, delete the file <Project>\GraCS\<Picture>.pdl.cache, and re-export.
2. Unregistered OCX / ActiveX control. A self-made icon wraps a third-party control (for example a chart OCX) that the Text Distributor cannot resolve. Re-register the control with regsvr32 "C:\Program Files\Common Files\Siemens\<OCX>.dll" or remove the offending object from the picture.
3. Picture compiled against a missing faceplate type. When the faceplate container references a type that has been deleted from the project, the dynamic text properties lose their ID. Restore the type from version control before exporting.
4. WinCC V7.0 SP3 without Update 1. Confirmed regression: PG_VSwitch2_Parameter.PDL exports only a subset of its text on V7.0 SP3 baseline. The fix is V7.0 SP3 Update 1 or upgrade to V7.4 / V7.5.

After applying the corrective action, re-run the export. A clean run produces no "unknown object" rows; the row count of the .csv should match the row count reported in the Text Distributor log status bar.

Translating User-Defined Objects and Self-Made Icons

Self-made icons built from WinCC smart objects (combinations of rectangle, line, polygon, text field, status display) are exported automatically. Each text property of each child object becomes one row. To verify coverage:

1. Open the icon in Graphics Designer.
2. List every text-bearing property: Text, Tooltip, Output value text, Status text.
3. Cross-check against the export .csv. Every property above must have a row; if not, the property is not configured for translation (right-click the property in the object list and tick Multilingual).

For OCX-based user-defined objects registered through Graphics Designer → Options → Customize → OCX, the Text Distributor reads the Localize interface. If the OCX does not implement IWinCCTextLibrary, its strings will not appear in the export. Siemens provides a sample stub in the WinCC Open Development Kit (ODK); replace the OCX About and label strings with calls to TXTPB_GetText().

VBA Macro Strategy for Bulk Translation

The Text Distributor does not produce a single consolidated .csv for the whole project. Each picture yields a separate file, and the format is the same. A small Excel VBA macro can merge, deduplicate, and re-shape the files for a translation agency:

Sub MergeTextDistributor()
    Dim folder As String: folder = "C:\WinCC_Export\"
    Dim fso As Object: Set fso = CreateObject("Scripting.FileSystemObject")
    Dim file As Object, ws As Worksheet, row As Long
    Set ws = ThisWorkbook.Sheets(1)
    ws.Cells(1, 1).Value = "TextID"
    ws.Cells(1, 2).Value = "Source (en-US)"
    ws.Cells(1, 3).Value = "Target (ru-RU)"
    row = 2
    For Each file In fso.GetFolder(folder).Files
        If LCase(Right(file.Name, 4)) = ".csv" Then
            Dim lines() As String
            lines = Split(fso.OpenTextFile(file.Path, 1, False, -1).ReadAll, vbLf)
            Dim i As Long
            For i = 0 To UBound(lines)
                If InStr(lines(i), ";") > 0 Then
                    Dim parts() As String: parts = Split(lines(i), ";")
                    ws.Cells(row, 1).Value = parts(0)
                    ws.Cells(row, 2).Value = parts(1)
                    row = row + 1
                End If
            Next i
        End If
    Next file
    ws.Range(ws.Cells(2, 1), ws.Cells(row, 3)).RemoveDuplicates Columns:=1, Header:=xlNo
    ThisWorkbook.SaveAs "C:\WinCC_Export\merged_for_translator.xlsx", xlWorkbookDefault
End Sub

The macro reads every .csv in C:\WinCC_Export\ with OpenAsTextStream set to Unicode (the -1 argument), splits on the semicolon delimiter, and deduplicates by Text ID. Output is saved as .xlsx (UTF-8) so the translator can keep Cyrillic, Greek, or CJK characters intact. The translator returns the file, the engineer copies the translated column back into the matching .csv rows, and Text Distributor imports the result.

Re-Importing Translated Texts

1. Confirm the .csv still has the original Text ID in column 1. Do not change the ID order or value; the importer keys on it.
2. Open Text Distributor, choose Import, and select the edited .csv or .txt.
3. Set the target language column mapping. For Russian (0019), pick the third column.
4. Tick Update existing texts; untick Insert new texts unless new rows were added intentionally.
5. Click Import. The status panel must show zero errors and the same number of imported rows as exported rows.

PCS 7 V8.0 SP1 and Software Media Package Notes

Engineers maintaining PCS 7 V8.0 face the following service-pack matrix for the Text Distributor:

The Software Media Package is a paid license upgrade; Update 1 is a free patch layered on top. Engineers should always install SP1 before applying Update 1. The SP1 installer rewrites TxTpdist.exe and the associated TextDistributor.mdb schema, which is why Update 1 cannot install against the V8.0 baseline.

TIA Portal / WinCC Professional Translation Procedure

In WinCC Professional (TIA Portal V17 / V18 / V19 / V20), the Graphics Designer and Text Distributor are replaced by the project tree. Translation steps:

1. Open the TIA Portal project that contains the HMI device.
2. Switch the project language to the target language: Options → Settings → General → User interface language.
3. Navigate to Project texts → Languages & Resources in the project tree. The project text database lists every text literal in screens, faceplate types, library types, alarms, and scheduled tasks.
4. Right-click the target language row and select Export project texts. Choose XLSX for Excel-based translation or CSV for a scriptable workflow.
5. Edit the file. The first column is the TIA-internal ID, the second column is the source text, and additional columns contain the configured languages. Add a new column for the translator if none exists.
6. Re-import with Project texts → Languages & Resources → Import project texts. The .xlsx round-trip preserves all Unicode characters without the ANSI down-grade seen in Classic.

For faceplate-specific text, the TIA Portal stores the body text inside the faceplate type. Translators work in Libraries → Types → <FaceplateType> → Texts. Runtime rotation of an object inside a faceplate (e.g. rotating a status icon 90 degrees via HMIRuntime.Screens("Main").ScreenItems("Icon1").RotationAngle = 90) does not affect the text properties; the rotation is purely a layout operation documented in the TIA Portal help under Rotating an object in runtime (RT Professional).

To switch the runtime language from a button or a hotkey in TIA Portal:

Sub ChangeLanguageToRussian()
    HMIRuntime.Language = 1049  ' 0x0419 = ru-RU
End Sub

The decimal language code follows the standard Microsoft LCID list; German is 1031, English-US is 1033, Russian is 1049, Chinese-PRC is 2052.

Verification Checklist

• Export row count equals import row count.
• Zero "unknown object" or "unknown subobject" rows in the Text Distributor log.
• Switching the runtime language in WinCC Explorer (Computer → Properties → Parameters → Language) renders every text in the new language, including tooltips, button labels, and dynamic text fields driven by GetText.
• No ??? or mojibake characters in any language. Spot-check at least three pictures and two faceplate types.
• The Text ID in the imported .csv is byte-identical to the export; if any ID changed, the importer cannot resolve the row and silently drops it.
• Backup of GraCS folder and project database is stored offsite before the import cycle.

FAQ