@americana/diplomat 0.2.1 → 0.4.0

package/README.md

@@ -2,11 +2,34 @@
 
 Diplomat prepares your interactive map for an international audience. With a few lines of code, your [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js/)–powered map will speak the user’s preferred language while informing them about local languages the world over.
 
-| Before                                                                                                                  | After                                                                                                                                                                                   |
-| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <img src="docs/navajo-nation.png" width="400" alt="Navajo Nation;Naabeehó Bináhásdzo">                                  | [<img src="docs/navajo-nation-es.png" width="400" alt="Nación Navajo (Navajo Nation • Naabeehó Bináhásdzo)">](https://americanamap.org/#map=9/36.2134/-109.2837&language=es)            |
-| <img src="docs/north-sea.png" width="400" alt="North Sea / Nordsee / Noordzee / Nordsøen / Nordsjøen / Mer du Nord">    | [<img src="docs/north-sea-la.png" width="400" alt="Mare Germanicum">](https://americanamap.org/#map=4/56/3&language=la)                                                                 |
-| <img src="docs/section-ross.png" width="400" alt="Ross Avenue;Tennesssee Avenue at Rhode Island Avenue;Section Avenue"> | [<img src="docs/section-ross-en.png" width="400" alt="Ross Avenue • Tennesssee Avenue at Rhode Island Avenue • Section Avenue">](https://americanamap.org/#map=17/39.168568/-84.460075) |
+| Before                                                                                                                 | After                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <img src="docs/navajo-nation.png" width="400" alt="Navajo Nation;Naabeehó Bináhásdzo">                                 | [<img src="docs/navajo-nation-es.png" width="400" alt="Nación Navajo (Navajo Nation • Naabeehó Bináhásdzo)">](https://americanamap.org/#map=9/36.2134/-109.2837&language=es)           |
+| <img src="docs/north-sea.png" width="400" alt="North Sea / Nordsee / Noordzee / Nordsøen / Nordsjøen / Mer du Nord">   | [<img src="docs/north-sea-la.png" width="400" alt="Mare Germanicum">](https://americanamap.org/#map=4/56/3&language=la)                                                                |
+| <img src="docs/section-ross.png" width="400" alt="Ross Avenue;Tennessee Avenue at Rhode Island Avenue;Section Avenue"> | [<img src="docs/section-ross-en.png" width="400" alt="Ross Avenue • Tennessee Avenue at Rhode Island Avenue • Section Avenue">](https://americanamap.org/#map=17/39.168568/-84.460075) |
+
+## Features
+
+Diplomat gives all parties a win-win:
+
+- Tailors labels to the user’s preferred language.
+- Respects multilingualism with optional dual language labels: both the user’s preferred language and the local native language.
+- Recognizes any language, dialect, or script out of the box with sophisticated language code matching.
+
+Diplomat lets your designer save face:
+
+- Uses space efficiently with both multiline and inline label layouts.
+- Deduplicates names within a label to avoid clutter.
+- Preserves diacritics in English exonyms where appropriate.
+- Respects right-to-left and vertical text layouts.
+
+Diplomat works quietly behind the scenes:
+
+- Changes the style on the fly at runtime – no need to publish a new style or tileset for every language.
+- You choose which style layers to localize, or localize them all automatically.
+- Supports multiple popular vector tile schemas without hacky workarounds, plus custom vector tilesets and GeoJSON sources.
+
+All localization is subject to the availability of localized names in the map data source. See [the caveats](#caveats) for more details.
 
 ## Requirements
 
@@ -21,7 +44,7 @@ With additional configuration, Diplomat supports even more vector tilesets, incl
 
 - [Mapbox Streets](https://docs.mapbox.com/data/tilesets/reference/mapbox-streets-v8/#names)
 - [OpenHistoricalMap](https://wiki.openstreetmap.org/wiki/OpenHistoricalMap/Reuse#Vector_tiles)
-- [Shortbread](https://shortbread-tiles.org/schema/): [OpenStreetMap.org](https://vector.openstreetmap.org/)
+- [Shortbread](https://shortbread-tiles.org/schema/) implementations, e.g., [OpenStreetMap.org](https://vector.openstreetmap.org/), [VersaTiles](https://github.com/versatiles-org/versatiles-generator/)
 
 ## Installation
 
@@ -35,11 +58,17 @@ Alternatively, you can include the plugin as a standalone script from a CDN such
 
 ## Usage
 
+Import Diplomat as a module:
+
+```js
+import * as Diplomat from "@americana/diplomat";
+```
+
 After creating an instance of `maplibregl.Map`, register an event listener for the `styledata` event that localizes the map:
 
 ```js
 map.once("styledata", (event) => {
-  map.localizeStyle();
+  Diplomat.localizeStyle(map);
 });
 ```
 
@@ -47,8 +76,8 @@ If your stylesheet uses a tileset that formats the name keys differently, such a
 
 ```js
 map.once("styledata", (event) => {
-  let locales = maplibregl.Diplomat.getLocales();
-  map.localizeStyle(locales, {
+  let locales = Diplomat.getLocales();
+  Diplomat.localizeStyle(map, locales, {
     localizedNamePropertyFormat: "name_$1",
   });
 });
@@ -58,15 +87,11 @@ If you set the `hash` option to a string when creating the `Map`, you can have t
 
 ```js
 addEventListener("hashchange", (event) => {
-  let oldLanguage = maplibregl.Diplomat.getLanguageFromURL(
-    new URL(event.oldURL),
-  );
-  let newLanguage = maplibregl.Diplomat.getLanguageFromURL(
-    new URL(event.newURL),
-  );
+  let oldLanguage = Diplomat.getLanguageFromURL(new URL(event.oldURL));
+  let newLanguage = Diplomat.getLanguageFromURL(new URL(event.newURL));
 
   if (oldLanguage !== newLanguage) {
-    map.localizeStyle();
+    Diplomat.localizeStyle(map);
   }
 });
 ```
@@ -75,7 +100,7 @@ Similarly, you can immediately respond to any change the user makes to their bro
 
 ```js
 addEventListener("languagechange", (event) => {
-  map.localizeStyle();
+  Diplomat.localizeStyle(map);
 });
 ```
 
@@ -95,7 +120,7 @@ Each of the supported properties may be set to a list of values separated by [se
 
 ## API
 
-This plugin adds several constants to a `maplibregl.Diplomat` namespace and adds a single method to each instance of `maplibregl.Map`.
+This plugin adds several symbols to a `maplibregl.Diplomat` namespace and adds a single method to each instance of `maplibregl.Map`. The following documentation uses the notation `maplibregl.Diplomat.*` in case you include Diplomat as a script. However, if you import Diplomat as a module, these symbols are directly imported into your code, without any namespacing.
 
 ### `maplibregl.Diplomat.localizedName`
 
@@ -213,20 +238,53 @@ Example:
 maplibregl.Diplomat.getLocales().includes("en");
 ```
 
-### `maplibregl.Map.prototype.localizeStyle()`
+### `maplibregl.Diplomat.getRelatedLanguageTags()`
+
+Returns an array of the language tags related to the given language tag, sorted from most specific to least specific.
+
+Parameters:
+ 
+- **`tag`** (`string`): The language tag that the returned language tags are related to.
+
+Returns a sorted array of related language tags, or an empty array if `tag` is malformed.
+
+Example:
+
+```js
+maplibregl.Diplomat.getRelatedLanguageTags("sr-RS").includes("sr-Cyrl");
+maplibregl.Diplomat.getRelatedLanguageTags("zh").includes("zh-Hans-CN");
+```
+
+### `maplibregl.Diplomat.localizeStyle()`
 
 Updates each style layer's `text-field` value to match the given locales, upgrading any unlocalizable layer along the way.
 
-This method ugprades unlocalizable layers to localized multiline or inline labels depending on the `symbol-placement` layout property. To add a dual language label to a layer, set its `text-field` layout property manually using the [`maplibregl.Diplomat.localizedNameWithLocalGloss`](#maplibrediplomatlocalizednamewithlocalgloss) constant.
+If neither `options.layers` nor `options.sourceLayers` is specified in `options`, this function makes localizable any style layer that gets the feature property specified in `options.unlocalizedNameProperty`, or `name` by default.
 
 Parameters:
 
-- **`layers`** (`[object]`): The style layers to localize.
+- **`map`** (`maplibregl.Map`): The map to localize.
 - **`locales`** (`[string]`): The locales to insert into each layer, as a comma-separated list of [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag). Uses the `language` URL hash parameter or browser preferences by default.
 - **`options`** (`object`):
+  - **`layers`** (`[string]`): The style layers with these IDs will be made localizable.
+  - **`sourceLayers`** (`[string]`): The style layers that use these source layers will be made localizable. These are source layer IDs, not style layer IDs.
   - **`unlocalizedNameProperty`** (`string`): The name of the property holding the unlocalized name. `name` by default.
-  - **`localizedNamePropertyFormat`** (`string`): "The format of properties holding localized names, where `$1` is replaced by an IETF language tag. `name:$1` by default.
-  - **`options.uppercaseCountryNames`** (`boolean`): Whether to write country names in all uppercase, respecting the locale’s case conventions.
+  - **`localizedNamePropertyFormat`** (`string`): The format of properties holding localized names, where `$1` is replaced by an IETF language tag. `name:$1` by default.
+  - **`glossLocalNames`** (`boolean`): Whether to format each label as a dual language label including a local name gloss.
+  - **`uppercaseCountryNames`** (`boolean`): Whether to write country names in all uppercase, respecting the locale’s case conventions.
+
+Example:
+
+```js
+maplibregl.Diplomat.localizeStyle(map, ["eo"], {
+  sourceLayers: ["place"],
+  glossLocalNames: true,
+});
+```
+
+### `maplibregl.Map.prototype.localizeStyle()`
+
+A wrapper for [`maplibregl.Diplomat.localizeStyle()`](#maplibregldiplomatlocalizestyle) that does not require passing in a `maplibregl.Map`. Only available when including Diplomat as a script.
 
 Example:
 
@@ -242,7 +300,7 @@ Diplomat only switches between languages that are present in the stylesheet’s
 
 By default, MapLibre GL&nbsp;JS does not support bidirectional text. Arabic, Hebrew, and other right-to-left languages will be unreadable unless you [install the mapbox-gl-rtl-text plugin](https://maplibre.org/maplibre-gl-js/docs/examples/add-support-for-right-to-left-scripts/).
 
-Diplomat only performs basic language fallbacks according to the [ICU locale fallback algorithm](https://unicode-org.github.io/icu/userguide/locale/#fallback). It makes no attempt to fallback to a related but distinct language code, for example from `sr-Cyrl` to `ru` or from `nb` to `no`. Instead, the user can [set their preferred languages](https://www.w3.org/International/questions/qa-lang-priorities) in their browser or operating system settings.
+Diplomat performs basic language fallbacks according to the [ICU locale fallback algorithm](https://unicode-org.github.io/icu/userguide/locale/#fallback). Additionally, it implements the [Likely Subtags](https://www.unicode.org/reports/tr35/#Likely_Subtags) algorithm of Unicode Technical Standard #35, so for example requesting either `zh` or `cmn` returns a name tagged as `zh-Hans-CN`, among other variations. However, in general, it does not fall back to a related but distinct language code, such as from `sr-Cyrl` to `ru` or from `nb` to `no`. Instead, the user can [set their preferred languages](https://www.w3.org/International/questions/qa-lang-priorities) in their browser or operating system settings.
 
 For historical reasons, [OpenStreetMap’s coverage in many reasons](https://wiki.openstreetmap.org/wiki/Multilingual_names) encodes multiple local names separated by human-readable punctuation. Diplomat makes no attempt to guess which punctuation is part of a name and which punctuation delimits two names.
 

package/dist/example/index.js

@@ -83,11 +83,10 @@ addEventListener("load", () => {
   );
 
   map.once("styledata", (event) => {
-    map.setLayoutProperty(
-      "place-labels",
-      "text-field",
-      maplibregl.Diplomat.localizedNameWithLocalGloss,
-    );
+    map.localizeStyle(maplibregl.Diplomat.getLocales(), {
+      sourceLayers: ["place"],
+      glossLocalNames: true,
+    });
     map.localizeStyle(maplibregl.Diplomat.getLocales(), {
       uppercaseCountryNames: true,
     });