Localization

FrontStage is a system used by users all over the world. Therefore, support for different user interface languages is a matter of course. In this article, you will learn about the localization solution in FrontStage and about translating and editing the localization in your installation.

Instead of hard strings, FrontStage uses literals, which are substituted for the actual text in the language.

LiteralLookup table

The literals in the database are stored in the LiteralLookup table.

A literal is uniquely identified by its group (the LiteralGroup column), culture (Culture) and numerical value (LiteralValue). An alternative to the numeric identification is the LiteralText text.

The translation itself is in DisplayName. Another language (culture) means a new row.

col	flags	type	desc
LiteralGroup	PK, not null	int	Skupina literálů. První část PK. Viz LiteralGroup.
LiteralValue	PK, not null	int	Číslo literálu. Druhá část PK.
Culture	PK, not null	text	ISO kultury řetězce DisplayName. Prázdný řetězec znamená neutrální text (invariant culture) - může být použit pro LiteralText.
LiteralText	None	text	Text literálu v systémové podobě (ASCII). NULL - bez systémového názvu. Využití u textových čísleníků.
DisplayName	None	text	Zobrazovaný text literálu. NULL znamená bez textu, může být platný LiteralText.
Description	None	text	Volitelný popis pro administraci.
Changed	None	text	Indikace zákaznických úprav v tabulce. NULL = nikdo needitoval, možno přepsat. Hodnota lokálního data a času = uživatel ručně změnil, nepřepisovat.

Culture

It is part of the primary key of the literal. It is a language and region code of the form of <language>-<region>, e.g. en-CZ, en-US.

Language is a two-character name in lower case according to ISO 639. Region is a two-character name in upper case according to ISO 3166.

See also

The authoritative language code list is maintained by the U.S. Library of Congress, and the list of regions is maintained directly by ISO.

glyph culture

Literals with glyph culture do not correspond to the translation in the language, but it is the expression of the literal with an “icon” in cases where it is used in the user interface. The value is the CSS class of the icon.

For example, a literal for a ready agent in English, Czech and “icon”:

LiteralGroup   LiteralValue   Culture   LiteralText   DisplayName
-----------------------------------------------------------------
30             0              cs-CZ     Ready         Připraven
30             0              en-US     Ready         Ready
30             0              glyph     Ready         fa fa-play

LiteralValue

In the database, LiteralValue is used in foreign keys to keep the table from getting too big and slow. For example, the call table of a large call center would contain Completed as the call result ten thousand times, so LiteralLookup 3 is used.

LiteralGroup   LiteralValue   Culture   LiteralText   DisplayName
-----------------------------------------------------------------
42             3              cs-CZ     Completed     Dokončeno
42             3              en-US     Completed     Completed

LiteralText

As an alternative to the numeric LiteralValue, there is the LiteralText text string for each literal. The text code is more human-friendly and is used when interacting with the user (meaning a consultant or translator).

LiteralText is a short technical key and looks like Message_MessagePhase, StartMusic etc. The translation of the latter is, e.g. for Czech, the string Start hudby na pozadí, for English the string Start background music etc.

DisplayName

DisplayName is a very important value; it is the translation itself for a given culture.

When we speak of a literal, we actually mean as many literals as we maintain cultures, each with its own translation. All literals have the same group, value and text.

For example, here is the FormAdmin_Title literal in the English and the Czech localizations:

LiteralGroup   LiteralValue   Culture   LiteralText        DisplayName
----------------------------------------------------------------------
101            7701           cs-CZ     FormAdmin_Title    Formuláře
101            7701           en-US     FormAdmin_Title    Forms

Some translations of literals may contain a variable part. For example, the number of lost calls, which is not known at the time the translation is created. In DisplayName, these variables are written as {0}, {1}, etc.

LiteralGroup   LiteralValue   Culture   LiteralText        DisplayName
-------------------------------------------------------------------------------------------------
100            8           cs-CZ     CallBackForLostCall    Zpětné volání za ztracený hovor v {0}
100            8           en-US     CallBackForLostCall    Callback for lost call at {0}

LiteralGroup

There are a huge number of literals (over several thousand). Some literals share the same beginning like Message_, Wfm_, so you can infer what module they are used in, but many others do not use a common beginning. That is why literals are divided into groups of literals.

Groups of literals group literals and are identified by a unique number. Literal groups are fixed; you cannot create your own.

Group name

Since a number is inconvenient for humans, even literal groups have an alternative text name. The name itself is a literal in Group 0.

LiteralGroup   LiteralValue   Culture   LiteralText               DisplayName
----------------------------------------------------------------------------------------------
0              100            cs-CZ     GeneralLocalisation       Lokalizace všeobecných textů
0              100            en-US     GeneralLocalisation       General text localisation
0              101            cs-CZ     ReactClientLocalisation   Lokalizace pro ReactClient
0              101            cs-CZ     ReactClientLocalisation   ReactClient UI localisation

Important groups

Literal groups <=99

Some groups have a fixed number of literals. These are different registers that the source code uses for calculations (such as the result of a call), and new literals can only be created in future versions of FrontStage.

In these groups, the consultant only maintains the translation (DislayName); they do not create new ones.

Literal groups >=100

Most attention and effort in localization focuses on this group of literals.

• 100 - general texts such as “today”, “yesterday”, “inactive”, etc.

Texts appearing in the user interface:

• 101 ReactClient (RC) user interface

• 102 WebSite (WS) user interface

• 120 TeamsClient (TC) user interface

• 150 DesktopClient (DC) user interface

Other special groups:

• 103 - ReactClientTheme - converts directory names with CSS files to localized text in DDN in Personal Settings.

• 104 - ReactClientContentParams - This one sets a part of the graphic appearance of visual editors (line height, order of tabs). The values are JSONs that are loaded by the frontend directly into an object, e.g. { "SvgRowHeight": 25, "ReversedTabOrder": true }. If group 104 is missing, the appearance of visual editors will be broken.

• 113 - StyleGlyph - Settings of other icons in the Microsoft Teams appearance. If you have FrontStage in the “Teams” look and you do not see any icons in the buttons and tabs, you are lacing literals in this group. Sample values can be found in Data/LiteralLookup.sql.

  Literals have Culture = 'teams'. Actual cultures like en-US are meaningless in this group.

• 115 - KbTagLocalisation - Tag of the knowledge base article tag.

Group 111 - DQ translation

This is the group in which each consultant will work the most. It is used to localize data queries - both column headings and cell texts.

When creating custom literals, it is very important to follow the LiteralValue convention.

• LV < 5000 are common and frequently used (in multiple DQs, in dacpac, LT starts with Cmn_)

• LV 5000 - 10000 is for standard DQs from programmers (probably used only for that DQ)

• LV > 10000 for consultants / customer translations.

See Data Query Localization.

Note

Remember to write $ at the beginning of the text to be localized when using it.

Group 111 - portlet name translations

This group is used to localize portlet names. This is purely up to the consultant.

See Portlet Localization.

Note

Remember to write $ at the beginning of the text to be localized when using it.

Automatic localization

You can automatically localize a certain LiteralGroup using the “General.Model.Db.” tool. Values saved within DisplayName columns are the subject of localization. Translations are limited to 2 million characters a month.

Localization uses the “Azure CognitiveServices Translator” technology. Connecting “General.Model.Db.” to this service requires:

• AzureTranslatorKey

• AzureTranslatorUrl

• AzureTranslatorRegion

Parameters have to be filled in the appsettings.json of “General.Model.Db.”.

Important

You can ask for the parameter values or the localization from your consultant.

Available commands

Localization commands. By running a command, all the mentioned steps will be performed.

All support the same parameter set:

• LiteralGroup - A group to be translated. Possible values: { 0, 1, 2, 3, …, 9998, 9999 } or in bulk: {“ll0” = (LG 0-999), “amll” = (LG 9000-9999)}

• LanguageFrom - en, cs

• LanguageTo - en, cs, it, hu, de, fr, vi, ar, sk, ro, pl

TranslateAll(LiteralGroup, LanguageFrom, LanguageTo)

1. It finds LiteralLookup records matching entered LiteralGroup and LanguageTo, and deletes them

2. It translates the DisplayName value of records matching entered LiteralGroup and LanguageFrom

3. Inserts translated values into DisplayName of records matching entered LiteralGroup and LanguageTo

Example

General.Model.Db.exe translateall 103 en cs

TranslateDiff(LiteralGroup, LanguageFrom, LanguageTo)

1. Generates and adds record translations where translation in LanguageTo doesn’t exist

2. Repairs mismatching record translations filtered by LanguageTo when LanguageFrom.DisplayName and LanguageTo.Description do not match (pressuming LanguageTo.Changed is not filled in - if filled in, record won’t be adjusted)

Example

General.Model.Db.exe translatediff amll en pl

LLCheck(LanguageFrom, LanguageTo)

1. Compares LiteralLookup table for provided LanguageFrom and LanguageTo

2. Prints to the console the cases where a mismatch is found in the LiteralText values for the same LiteralGroup and LiteralValue

Example

General.Model.Db.exe llcheck en cs

Localization of data queries

Data grid column names (Name) and the other user interface elements can now be fully localized to new languages. If you use <prefix><key> as a column name (e.g. $AgentWorkplace), FrontStage will try to lookup an translation of key for the current user language.

Besides data grid column names, this mechanism can also be used to localize names:

• Localize names in the data query converters of ProjectName, LanguageName, OutboundListActivity, CampaignActivity, GatewayName, PilotName and StatusName

• Display names in contacts (field names for the model)

• Display names in issues for topic, subtopic and phases

The prefix sign can be defined using the LiteralLookupPrefix configuration item (configuration section System), which has the default value of $ (dollar sign). If you change the prefix, any string that contains the original prefix will be displayed including the original prefix. For example, when you change $ to #, $AgentWorkplace will be displayed.

The literal group of PrefixedLocalisation is reserved for such localized strings.

Example of a localized data grid column name

The column name now has the value of Agent Workplace and it displays as such in all languages. You want it to be called Pracoviště agenta in Czech and the original value to be kept in English.

1. Rename the column to $AgentWorkplace.

2. In the administration interface in Portal ‣ LiteralLookups ‣ LiteralLookups, select the PrefixedLocalisation translation group.

3. Check in this translation group whether $AgentWorkplace translations already exist. If not, create an item for Czech (cs-CZ) and an item for English (en-US) with a corresponding translation.

   Caution

   The literal number (LiteralValue) must be used such that has never been used in the group before!

4. If there is no translation for the user’s language, the value without a prefix will be used – for the $AgentWorkplace key, the user will see the following translation: AgentWorkplace.

5. In order for the change to manifest in the users’ browsers, you need to clear the cache and then reload the user’s page in the browser (Ctrl-F5).

Portlet localization

A new localization group No. 112 – PrefixedPortletLocalisation – was created for this purpose.

Necessary condition

In the LiteralLookup localization table, the Group 112 entry (the value in the Number column) must exist for all required languages – in this case, for example, “cs-CZ” (our default language) and “en-US” (target language). To verify this, go to Portal -> Localization in the administration interface.

Localization is applied using the prefix of the character used in the replacement string.

The prefix character is configurable by the LocalizationPrefix configuration item (configuration section System), which has a default value of $``(the dollar sign). If you change the prefix, each string where the original prefix is used will be displayed including the original prefix. For example, changing ``$ `` to ``# `` will show ``$MyInCalls (see below).

Attention

The LocalizationPrefix parameter is used not only by Group 112, but also by Group 111 – PrefixedLocalisation.

Progress

The following procedure shows how to localize the name of the :guilabel: My inbound calls` data grid. The default language is Czech – culture code: cs-CZ. We will localize to English – en-US.

1. Create items in the localization table

   1. In the administration interface, navigate to Portal -> Localization -> Bulk Editing, select the PrefixedPortletLocalisation group and click on the right side on the Search button

   2. Switch to the :Guilabel: ‘cs-CZ’ tab

   3. Click on the Add new item active link below to create the desired default item for the portlet name that you want to localize.

      • The item name will be in the Text field and the name to be displayed in the Name field

   4. Enter values for the default language in the fields:

      Language

      Group name	Number	Culture	Text	Name
      112	100	cs-CZ	MyInCalls	My inbound calls

      Attention

      The selected value of the Number item may not yet been used in this group.

   5. Save by clicking on Save and back below; you will see the item that you just created

   6. Switch to the next tab en-US, and enter values for the localized name:

      Target language

      Group name	Number	Culture	Text	Name
      112	100	en-US	MyInCalls	My Inbound Calls

      Save your changes. In the same way, you can create entries for a portlet name with the same number for other languages.

   7. Clear the cache for the change to take effect without delay.

2. Localize the portlet name

   1. Switch to the user page to the Calls tab

   2. In the page edit mode, select the portlet whose name you want to localize – in the My inbound calls`portlet, click on :guilabel:`Edit element

   3. In the Element name field, enter the exact name of the localization item created in the localization table, prefixed with the $MyInCalls character, then save (use the Save button below)

   4. Click on the Save and Finish editing buttons in the bottom-right corner to exit edit mode

3. Display your localized name

   1. Press the Personal settings button in the top-right corner to open the settings dialog

   2. In the Choose your language field, change the language to English and save the change

   3. Refresh the page by pressing Ctrl-F5

   4. The original name of the Mé příchozí hovory data grid is displayed in a localized version – My Inbound Calls

      

Encoding localization

You can specify encodings available for visual editors and Fronstage functions in general by creating records in the LiteralLookup database table. This purpose serves the LiteralGroup = 197, where you can create the record as follows:

• LiteralValue - A rank of the records in the DDN.

• Culture - Notation of the chosen language according to the international standard.

• LiteralText - The numeric indication of the selected character set (encoding). It must be filled in; this parameter links the selection in the DDN with the installed character set.

• DisplayName - A name displayed in the DDN.

Next   Previous