Language Support
Types of Languages

The PTV vector format supports native, localized and transliterated names for location labels (like countries or cities) and street elements, if available.

  • Native names represent the default language that is most common for the element in its native language. A town in Germany e.g. will have a native name in German.
  • Localized names are the translated variants for different languages of the native name. Also, some non-standard transliterated names are provided by this field, see the next chapter for more details.
  • Transliterated names are a Latin-1 representation of a name in a non Latin-1 character set. Moskva is for example the transliteration of Москва́.

Example Tile Data

A typical entry in the tile data for the town name property looks like this (the binary tile data was converted to json to make it readable):

"properties": {
        "country_language_code": "CZE",
        "display_class": 2,
        "name": "České Budějovice",
        "name_dan": "Ceske Budejovice",
        "name_dut": "Ceske Budejovice",
        "name_eng": "Budweis",
        "name_fin": "Ceske Budejovice",
        "name_fre": "Ceske Budejovice",
        "name_ger": "Budweis",
        "name_gre": "Τσέσκε Μπουντεγιόβιτσε",
        "name_grx": "Tseske Bountegiovitse",
        "name_hun": "Ceske Budejovice",
        "name_hux": "Ceske Budejovice",
        "name_ita": "Ceske Budejovice",
        "name_nor": "Ceske Budejovice",
        "name_pol": "Czeskie Budziejowice",
        "name_por": "Ceske Budejovice",
        "name_pox": "Czeskie Budziejowice",
        "name_rus": "Ческе-Будеёвице",
        "name_rux": "Cheske-Budeyovitse",
        "name_slo": "České Budejovice",
        "name_slx": "Ceske Budejovice",
        "name_spa": "Ceske Budejovice",
        "name_swe": "Ceske Budejovice",
        "name_trans": "Ceske Budejovice"
}

  • The name field holds the native name (in this case in Czech language). This corresponds to the default language of the element.
  • The localized names are identified through the name tag plus an underscore followed by the ISO 639-2 code of the language, e.g. `name_eng` for english.
  • The transliterated name is identified by the name_trans tag.

This pattern is the same for all elements in the style, except that the name tag itself may change. So street names have a name field called street_name, ferry names are identified by the tag ferry_name and so on.

In the map styles only the native name is set. Switching the language must be done manually and will be described later.

Country language code

The country language code for label elements is also delivered in the tile data as country_language_code. It can be used to determine if the language code of an element is the same as the country language code. Please see Example 3 for usage.

Style Labels and Field Names

List of all used name tags and their correspondent style element:

Style label name Field name Localized names supported Country code available
LBL_Country_Small name X X
LBL_Country_Medium name X X
LBL_Country_Big name X X
LBL_Hamlet name X X
LBL_CityMinorVillage name X X
LBL_CityMajorVillage name X X
LBL_CityMinorSmall name X X
LBL_CityMajorSmall name X X
LBL_CityMinorMedium name X X
LBL_CityMajorMedium name X X
LBL_CityMinorLarge name X X
LBL_CityMajorLarge name X X
LBL_CityMinorVeryLarge name X X
LBL_CityMajorVeryLarge name X X
LBL_CityMinorCapital name X X
LBL_CityMajorCapital name X X
TSP_RoadResidential_Label street_name X no
TSP_RoadLocal_Label street_name X no
TSP_RoadArterial_Label street_name X no
TSP_RoadFederal_Label street_name X no
TSP_RoadHighway_Label street_name X no
TSP_RoadFerry_Label ferry_name no no
TSP_RoadExitName_Label exit_name no no
TSP_RoadFederalArterial_Shield shield_name no no
TSP_RoadHighway_Shield shield_name no no

Not all elements contain a localized name. Exit names, shield names and ferry names only have a native name and a transliterated name - if available.

Please note that localized names are optional for the styles that support them.

Supported Languages

For the native field name and the transliterated field name_trans we deliver all available languages that HERE supports.

For localized names and non-standard transliterations, the following languages are supported (if available):

Based on MARC country codes Language
BOS Bosnian
BOX Bosnian, transliterated
BUL Bulgarian
BUX Bulgarian, transliterated
CHI Chinese
CZE Czech
CZX Czech, transliterated
DAN Danish
DUT Dutch
ENG English
EST Estonian
ESX Estonian, transliterated
FIN Finnish
FRE French
GER German
GLE Irish
GRE Greek, modern
GRX Greek, modern, transliterated
HIN Hindi
HIX Hindi, transliterated
HUN Hungarian
HUX Hungarian, transliterated
IND Indonesian
ITA Italian
JPN Japanese
KOR Korean
KOX Korean, transliterated
LAV Latvian
LAX Latvian, transliterated
LIT Lithuanian
LIX Lithuanian
NOR Norwegian
POR Portuguese
POL Polish
POX Polish, transliterated
SPA Spanish, Castilian
RUM Romanian
RMX Romanian
RUS Russian
RUX Russian, transliterated
SCR Croatian
SLO Slovak
SLX Slovak, transliterated
SLV Slovenian
SIX Slovenian, transliterated
SRX Croatian, transliterated
SRB Serbian
SCX Serbian, transliterated
SWE Swedish
TUR Turkish
TUX Turkish, transliterated
UKR Ukrainian
UKX Ukrainian, transliterated
URD Urdu
VIE Vietnamese
THA Thai

Switching Languages in MapBoxGL.js

All styles use the native name as default. Switching the native language to another language can be achieved by using the setLayoutProperty() of MapBox. All following examples use plain javascript and MapBox expressions.

Example 1 - Switching the name of all arterial roads to the transliterated version
map.setLayoutProperty('TSP_RoadArterial_Label', 'text-field', ['get', 'street_name_trans']);

text_field is the internal name from MapBox for the name property of an element. With setLayoutProperty(), we tell MapBox to use the street_name_trans value in the tile for the `text-field`. Please note: Not all transliterated names are filled, so we should use a fallback like in Example 2.

Example 2 - Switching the name of the style element LBL_City to english (with fallback to the native name)
map.setLayoutProperty('LBL_CityMajorCapital', 'text-field', ['coalesce',['get','name_eng'],['get', 'name']]);

['coalesce',['get','name_eng'],['get', 'name']] is a MapBox expression. The ['coalesce',...] statement returns the first element in the parameter list that is not null. So the statement ['get','name_eng'] tries to retrieve the name_eng property for an element from the tile. If this property is null, coalesce will return the value of ['get', 'name'] as the native language fallback.

Example 3: Show the localized and the native name for a town at the same time

This is a more complex example on how to display the town name with the localized name above the native name:

First, we check if the language and the country language is the same. If this is true, it makes no sense to show both names because they are identical, so we only show the native name. The localized name and the native name will be displayed if the localized name exists. If not, we try to load the transliterated name. If the transliterated name exists, we show the transliterated and the native name. Otherwise, we only show the native name. There are many fallbacks and checks, just have a look at the code:

var language = "deu";
 map.setLayoutProperty('LBL_CityMajorCapital', 'text-field',
        ['case',
        ['==', ['get', 'country_language_code'], ['upcase', language]], // if country_language is the same as language, show only native name
        ['get', 'name'],
        ['==', ['get', 'name'], ['get','name_' + language]], // if names are same, show only native
        ['get', 'name'],
        ['==', ['get','name_' + language], null], // if localized name is null show transliterated if available, else show native
        ['case',
            ['!=', ['get','name_trans'], null], // check if transliterated name exists, if not show only native
            ['format',
                ['get','name_trans'],  // show formatted string with transliterated name above native name
                { 'font-scale': 1.0 },
                '\n',
                ['get', 'name'],
                { 'font-scale': 0.8, 'text-font': ['literal', ['Noto Sans Italic']] }
            ],
            ['get', 'name']
        ],
        ['!=', ['get','name_' + language], null], //if localized name exists, show it above the native name
        ['format',
                ['get','name_' + language],
                { 'font-scale': 1.0 },
                '\n',
                ['get', 'name'],
                { 'font-scale': 0.8, 'text-font': ['literal', ['Noto Sans Italic']] }
        ],
        ['get', 'name']]);  // fallback: set the native name

You can add this code to your index.html. Just add a button or parse the url to set the language code (instead of the hardcoded "deu" in the example above) and then call the example code to switch the language for a LBL_City town dynamically.