Map constructor can take language as a string (#131)

* Map constructor can take language as a string

* adding readme entry

Author: jonathanlurie

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 2.4.1
 ### Bug Fixes
 - The class `AJAXError` is now imported as part of the `maplibregl` namespace (CommonJS limitation from Maplibre GL JS) (https://github.com/maptiler/maptiler-sdk-js/pull/129)
+- The `Map` constructor can now also take a language as a string (https://github.com/maptiler/maptiler-sdk-js/pull/131)
 
 ## 2.4.0
 ### New Features

images/screenshots/visitor_athen.png

@@ -468,14 +468,39 @@ Whenever a label is not supported in the defined language, it falls back to `Lan
 Here is a sample of some compatible languages:
 ![](images/screenshots/multilang.gif)
 
-# Built-in support for right-to-left languages
+## Built-in support for right-to-left languages
 Languages that are written right-to-left such as Arabic and Hebrew are fully supported by default. No need to install any plugins!
 
 <p align="center">
   <img src="images/screenshots/lang-arabic.jpeg" width="48%"></img>
   <img src="images/screenshots/lang-hebrew.jpeg" width="48%"></img>
 </p>
 
+## Visitor language modes
+The *visitor* language modes are special built-in modes made to display labels in two different languages, concatenated when available:
+- `Language.VISITOR` concatenates labels in the language of your system and the *local* language
+- `Language.VISITOR_ENGLISH` concatenates labels in English and the *local* language
+
+```ts
+const map = new Map({
+  // some options...
+  language: Language.VISITOR,
+})
+
+// or
+
+const map = new Map({
+  // some options...
+  language: Language.VISITOR_ENGLISH,
+})
+```
+
+We believe these two modes can be very handy to help the end users identify places, especially when the local labels are not using a latin charset. Here is how it looks like:
+
+![](images/screenshots/visitor_athen.png)
+![](images/screenshots/visitor_osaka.png)
+
+
 # Custom Events and Map Lifecycle
 ## Events
 ### The `ready` event

images/screenshots/visitor_osaka.png

@@ -75,11 +75,12 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
   style?: ReferenceMapStyle | MapStyleVariant | StyleSpecification | string;
 
   /**
-   * Define the language of the map. This can be done directly with a language ISO code (eg. "en")
+   * Define the language of the map. This can be done directly with a language ISO code (eg. "en"),
+   * the ISO code prepended with the OSM flag (eg. "name:en" or even just "name"),
    * or with a built-in shorthand (eg. Language.ENGLISH).
    * Note that this is equivalent to setting the `config.primaryLanguage` and will overwrite it.
    */
-  language?: LanguageInfo;
+  language?: LanguageInfo | string;
 
   /**
    * Define the MapTiler Cloud API key to be used. This is strictly equivalent to setting
@@ -300,7 +301,13 @@ export class Map extends maplibregl.Map {
       registerLocalCacheProtocol();
     }
 
-    this.primaryLanguage = options.language ?? config.primaryLanguage;
+    if (typeof options.language === "undefined") {
+      this.primaryLanguage = config.primaryLanguage;
+    } else {
+      const providedlanguage = toLanguageInfo(options.language, Language);
+      this.primaryLanguage = providedlanguage ?? config.primaryLanguage;
+    }
+
     this.forceLanguageUpdate =
       this.primaryLanguage === Language.STYLE || this.primaryLanguage === Language.STYLE_LOCK ? false : true;
     this.languageAlwaysBeenStyle = this.primaryLanguage === Language.STYLE;