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:
 

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):

Switching Languages in MapLibreGL.js

All styles use the native name as default. Switching the native language to another language can be achieved by using the setLayoutProperty() of MapLibre. All following examples use plain javascript and MapLibre 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 MapLibre for the name property of an element. With setLayoutProperty(), we tell MapLibre 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 MapLibre 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.