I18N (Internationalization)

ThermalLabel SDK supports internationalization (I18N), so you can show your end users texts localized to their own culture and language. Localizable texts include:

  • Error messages thrown by the SDK (for example, "The Width of the Item must be greater than zero.", invalid item names, invalid DataSource, invalid masks, barcode validation, etc.).
  • Printing / communication messages (USB, driver, parallel, serial, IP/Ethernet and bidirectional-channel errors).
  • Visual editor texts (duplex side tags, item tooltips such as Locked or Read Only).

Support is provided through the Neodynamic.SDK.Printing.I18NResource and Neodynamic.SDK.Printing.I18N classes, and it can also be configured from plain JSON text.

  • I18NResource holds all the localizable texts as string properties. Create one instance per culture you want to support. Its CultureTwoLetterISOLanguageName property must be the culture's TwoLetterISOLanguageName, e.g. "en", "es", "it". A new instance already contains the built-in English strings, so you only need to change the properties you want to translate. ToJson() exports the instance as "<culture>": { ...all texts... }, which is handy to get the full list of keys for translators. You can also inherit from the class and override the (virtual) properties.
  • I18N holds all the supported cultures, built from a List<I18NResource> or from a JSON string, plus:
    • CurrentCulture: the culture used to look texts up.
    • FallbackCulture: the culture used when a text is missing in the current one.
    • GetResourceString(key): returns the text for a key (each property has a matching ...Key constant, e.g. I18NResource.ErrorItemRenderWidthKey).
  • Finally, assign your I18N object to the static ThermalLabel.I18N property at the very beginning of your code flow, before using any SDK feature.

How a text is resolved

For a given key the SDK looks, in order, in:

  1. the current culture;
  2. the fallback culture;
  3. the built-in English strings.

So a culture only needs to define the texts it translates; anything missing falls back automatically. Culture names are compared ignoring case, but they must be the two-letter code ("de", not "de-AT"); lowercase is recommended.

By default (new I18N()), ThermalLabel.I18N uses English for everything.

Example of I18N through .NET code

For simplicity, the sample translates just two properties: the duplex side tags shown by the visual editors.

VB

' I18N Sample - Three supported cultures
Imports System.Collections.Generic

Dim enRes As New I18NResource() ' the built-in ENGLISH strings (change it if needed!)

Dim esRes As New I18NResource() With { ' custom SPANISH strings
    .CultureTwoLetterISOLanguageName = "es",  ' MANDATORY!
    .VisualEditorDuplexBackSide = "REVERSO",
    .VisualEditorDuplexFrontSide = "ANVERSO"
}

Dim itRes As New I18NResource() With { ' custom ITALIAN strings
    .CultureTwoLetterISOLanguageName = "it", ' MANDATORY!
    .VisualEditorDuplexBackSide = "DIETRO",
    .VisualEditorDuplexFrontSide = "DAVANTI"
}

' List of supported cultures: "en", "es" and "it"
Dim myRes As New List(Of I18NResource) From {enRes, esRes, itRes}

' Sets the supported cultures and make "it" (Italian) the current one, "en" is the fallback
ThermalLabel.I18N = New I18N(myRes, "it", "en")

CS

// I18N Sample - Three supported cultures

var enRes = new I18NResource(); // the built-in ENGLISH strings (change it if needed!)

var esRes = new I18NResource() // custom SPANISH strings
{
    CultureTwoLetterISOLanguageName = "es",  // MANDATORY!
    VisualEditorDuplexBackSide = "REVERSO",
    VisualEditorDuplexFrontSide = "ANVERSO"
};

var itRes = new I18NResource() // custom ITALIAN strings
{
    CultureTwoLetterISOLanguageName = "it", // MANDATORY!
    VisualEditorDuplexBackSide = "DIETRO",
    VisualEditorDuplexFrontSide = "DAVANTI"
};

// List of supported cultures: "en", "es" and "it"
var myRes = new List<I18NResource>() { enRes, esRes, itRes };

// Sets the supported cultures and make "it" (Italian) the current one, "en" is the fallback
ThermalLabel.I18N = new I18N(myRes, "it", "en");

If the list contains two resources with the same culture, only the first one is used. A null or empty list gives the built-in English strings.

Example of I18N through JSON format

The JSON has one entry per culture; the entry name is the TwoLetterISOLanguageName and its content is the set of localizable properties. The property names must be exactly the names of the I18NResource properties (case-sensitive). To get the full list, create an I18NResource and call ToJson().

You do not need to include every property: missing ones fall back as described above. Extra names that do not correspond to any property are simply ignored.

{
  "en": {
    "VisualEditorDuplexFrontSide": "FRONT",
    "VisualEditorDuplexBackSide": "BACK"
  },
  "es": {
    "VisualEditorDuplexFrontSide": "ANVERSO",
    "VisualEditorDuplexBackSide": "REVERSO"
  },
  "it": {
    "VisualEditorDuplexFrontSide": "DAVANTI",
    "VisualEditorDuplexBackSide": "DIETRO"
  }
}

The above JSON can be used like this:

VB

' I18N Sample - Three supported cultures

' Using a JSON string
Dim jsonI18NResources As String = "{""en"":{""VisualEditorDuplexFrontSide"":""FRONT"",""VisualEditorDuplexBackSide"":""BACK""},""es"":{""VisualEditorDuplexFrontSide"":""ANVERSO"",""VisualEditorDuplexBackSide"":""REVERSO""},""it"":{""VisualEditorDuplexFrontSide"":""DAVANTI"",""VisualEditorDuplexBackSide"":""DIETRO""}}"

' Sets the supported cultures in JSON format and make "it" (Italian) the current one
ThermalLabel.I18N = New I18N(jsonI18NResources, "it", "en")

CS

// I18N Sample - Three supported cultures

// Using a JSON string
string jsonI18NResources = "{\"en\":{\"VisualEditorDuplexFrontSide\":\"FRONT\",\"VisualEditorDuplexBackSide\":\"BACK\"},\"es\":{\"VisualEditorDuplexFrontSide\":\"ANVERSO\",\"VisualEditorDuplexBackSide\":\"REVERSO\"},\"it\":{\"VisualEditorDuplexFrontSide\":\"DAVANTI\",\"VisualEditorDuplexBackSide\":\"DIETRO\"}}";

// Sets the supported cultures in JSON format and make "it" (Italian) the current one
ThermalLabel.I18N = new I18N(jsonI18NResources, "it", "en");

The JSON must be valid: an empty/whitespace string gives the built-in English texts, but malformed JSON throws an ArgumentException from the constructor (there is no silent fallback to English). Unknown keys requested through GetResourceString return the key itself.

Translating error messages

Because exception messages go through the same mechanism, translating them is just a matter of overriding the corresponding properties:

var es = new I18NResource()
{
    CultureTwoLetterISOLanguageName = "es",
    ErrorItemRenderWidth  = "El ancho del item debe ser mayor que cero.",
    ErrorItemRenderHeight = "El alto del item debe ser mayor que cero."
};
ThermalLabel.I18N = new I18N(new List<I18NResource> { es }, "es", "en");

Some messages contain placeholders such as {0} or {1} (for example the USB, BIDI and PrintAsResident messages); keep them in your translation.

Windows Visual Label Editors

The visual label editors take their texts from ThermalLabel.I18N. At runtime you can change the current culture by setting CurrentCulture and calling the UpdateBaseOnI18N() method of the editor.

Based on the examples above, to switch from Italian (it) to Spanish (es) with the Windows Visual Label Editor component:

VB

' I18N Sample - Changing current culture

' Make Spanish the new current culture
ThermalLabel.I18N.CurrentCulture = "es"

' Refresh/update the visual editor strings
thermalLabelEditor1.UpdateBaseOnI18N()

CS

// I18N Sample - Changing current culture

// Make Spanish the new current culture
ThermalLabel.I18N.CurrentCulture = "es";

// Refresh/update the visual editor strings
thermalLabelEditor1.UpdateBaseOnI18N();

Outside the editors, changing CurrentCulture takes effect immediately for any message generated afterwards.

Common mistakes

Problem Cause / fix
Translation is ignored CultureTwoLetterISOLanguageName not set (it stays "en"), or written in uppercase / with region ("DE", "de-AT"). Use the two-letter code ("de").
Texts still in English CurrentCulture does not match any entry. English is used as the last resort.
ThermalLabel.I18N set too late Set it before using the SDK.
Exception at new I18N(json, ...) Malformed JSON.