You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Replaced localizeLayers with a more encapsulated localizeStyle that can automatically manipulate all the layers and upgrade unlocalizable layers. Added the rest of the country code conversion functionality from OSM Americana.
Copy file name to clipboardExpand all lines: README.md
+53-40Lines changed: 53 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,36 +39,18 @@ After creating an instance of `maplibregl.Map`, register an event listener for t
39
39
40
40
```js
41
41
map.once("styledata", (event) => {
42
-
// Prepare layers to be localized.
43
-
map.setLayoutProperty(
44
-
"country-labels",
45
-
"text-field",
46
-
maplibregl.Diplomat.localizedName,
47
-
);
48
-
map.setLayoutProperty(
49
-
"city-labels",
50
-
"text-field",
51
-
maplibregl.Diplomat.localizedNameWithGloss,
52
-
);
53
-
map.setLayoutProperty(
54
-
"road-labels",
55
-
"text-field",
56
-
maplibregl.Diplomat.localizedNameInline,
57
-
);
58
-
59
-
// Localize the layers.
60
-
constlocales=maplibregl.Diplomat.getLocales();
61
-
conststyle=map.getStyle();
62
-
map.localizeLayers(style.layers, locales);
63
-
map.setStyle(style);
42
+
map.localizeStyle();
64
43
});
65
44
```
66
45
67
46
If your stylesheet uses a tileset that formats the name keys differently, such as OpenHistoricalMap or Shortbread, set the format when localizing the layers, for example:
Similarly, you can immediately respond to any change the user makes to their browser language preference in real time:
75
+
76
+
```js
77
+
addEventListener("languagechange", (event) => {
78
+
map.localizeStyle();
79
+
});
80
+
```
81
+
95
82
> [!NOTE]
96
83
> By default, MapLibre GL 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/).
97
84
98
85
## Schema
99
86
100
87
Diplomat can manipulate any GeoJSON or vector tile source, as long as it includes the following properties on each feature:
101
88
102
-
-**`name`** (`string`): The name in the local or official language. You can customize this property by setting the `unlocalizedNameProperty` option when calling [`maplibregl.Map.prototype.localizeLayers()`](#maplibreglmapprototypelocalizelayers).
103
-
-**<code>name:<var>xyz</var></code>** (`string`): The name in another language, where <var>xyz</var> is a valid [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). For example, <code>name:zh</code> for Chinese, <code>name:zh-Hant</code> for Traditional Chinese, <code>name:zh-Hant-TW</code> for Traditional Chinese (Taiwan), and <code>name:zh-Latn-pinyin</code> for Chinese in pinyin. You can customize this format by setting the `localizedNamePropertyFormat` option when calling [`maplibregl.Map.prototype.localizeLayers()`](#maplibreglmapprototypelocalizelayers).
89
+
-**`name`** (`string`): The name in the local or official language. You can customize this property by setting the `unlocalizedNameProperty` option when calling [`maplibregl.Map.prototype.localizeStyle()`](#maplibreglmapprototypelocalizestyle).
90
+
-**<code>name:<var>xyz</var></code>** (`string`): The name in another language, where <var>xyz</var> is a valid [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag). For example, <code>name:zh</code> for Chinese, <code>name:zh-Hant</code> for Traditional Chinese, <code>name:zh-Hant-TW</code> for Traditional Chinese (Taiwan), and <code>name:zh-Latn-pinyin</code> for Chinese in pinyin. You can customize this format by setting the `localizedNamePropertyFormat` option when calling [`maplibregl.Map.prototype.localizeStyle()`](#maplibreglmapprototypelocalizestyle).
104
91
105
92
For compatibility with the [OpenMapTiles](https://openmaptiles.org/schema/) schema, `name_en` and `name_de` are also recognized as alternatives to `name:en` and `name:de` for English and German, respectively, but only in the `transportation_name` layer. For performance reasons, Diplomat does not look for this format by default for any other language or layer.
106
93
@@ -114,6 +101,8 @@ This plugin adds several constants to a `maplibregl.Diplomat` namespace and adds
114
101
115
102
An expression that produces the names in the user's preferred language, each on a separate line.
116
103
104
+
Use this constant if you are building the entire stylesheet programmatically before initializing a `maplibregl.Map` and want more fine-grained control over which layers have which label layout than [`maplibregl.Map.prototype.localizeStyle()`](#maplibreglmapprototypelocalizestyle) provides.
105
+
117
106
This expression is appropriate for labeling a type of feature that almost always has a familiar translation in the user’s preferred language, such as the name of a country. It is also appropriate for minor features like points of interest, for which an extra local-language gloss would clutter the map.
118
107
119
108
Example:
@@ -130,6 +119,8 @@ map.setLayoutProperty(
130
119
131
120
An expression that produces the names in the user's preferred language, all on the same line.
132
121
122
+
Use this constant if you are building the entire stylesheet programmatically before initializing a `maplibregl.Map` and want more fine-grained control over which layers have which label layout than [`maplibregl.Map.prototype.localizeStyle()`](#maplibreglmapprototypelocalizestyle) provides.
123
+
133
124
This expression is appropriate for labeling a linear feature, such as a road or waterway. The symbol layer’s [`symbol-placement`](https://maplibre.org/maplibre-style-spec/layers/#symbol-placement) layout property should be set to either `line` or `line-center`.
134
125
135
126
Example:
@@ -146,6 +137,8 @@ map.setLayoutProperty(
146
137
147
138
An expression that produces the name in the user's preferred language, followed by the name in the local language in parentheses if it differs.
148
139
140
+
Use this constant if you are building the entire stylesheet programmatically before initializing a `maplibregl.Map` and want more fine-grained control over which layers have which label layout than [`maplibregl.Map.prototype.localizeStyle()`](#maplibreglmapprototypelocalizestyle) provides.
141
+
149
142
This expression is appropriate for labeling a type of feature that is only sometimes translated into user’s preferred language, such as the name of a city or town. The extra local-language gloss respects local customs and keeps the user informed, but it can also risk [information overload](https://en.wikipedia.org/wiki/Information_overload) and crowd out other useful labels.
> Use [`maplibregl.Diplomat.getGlobalStateForLocalization()`](#maplibregldiplomatgetglobalstateforlocalization) to populate the global state required by this expression, then call [`maplibregl.Map.prototype.localizeStyle()`](#maplibreglmapprototypelocalizestyle). Otherwise, this expression evaluates to the raw country code.
Returns the global state that Diplomat needs to fully localize the style.
180
+
181
+
If you are building a stylesheet programmatically, you can use this method to populate a `state` property at the root of the stylesheet before initializing a `maplibregl.Map`. You can add additional global state properties besides the ones that come from this object, as long as you avoid making a deep clone of the object.
182
+
183
+
If your stylesheet is powered by OpenMapTiles, you need to set this global state object in order to localizing boundary edge labels that come from the [`boundary`](https://openmaptiles.org/schema/#boundary) layer. Otherwise, the user will see only ISO 3166-1 alpha-3 codes, because OpenMapTiles only provides these codes instead of the full country name on either side of a boundary.
184
+
185
+
Parameters:
186
+
187
+
-**`locales`** (`string`): The locales for formatting the country names.
188
+
-**`options.uppercaseCountryNames`** (`boolean`): Whether to write the country names in all uppercase, respecting the locale’s case conventions. Enable this option if you intend to display the boundary edge labels in uppercase, because the `upcase` expression operator is locale-insensitive.
Updates localizable variables at the top level of each layer's `text-field` expression based on the given locales.
208
+
Updates each style layer's `text-field` value to match the given locales, upgrading any unlocalizable layer along the way.
209
+
210
+
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.
194
211
195
212
Parameters:
196
213
@@ -199,18 +216,14 @@ Parameters:
199
216
-**`options`** (`object`):
200
217
-**`unlocalizedNameProperty`** (`string`): The name of the property holding the unlocalized name. `name` by default.
201
218
-**`localizedNamePropertyFormat`** (`string`): "The format of properties holding localized names, where `$1` is replaced by an IETF language tag. `name:$1` by default.
202
-
203
-
> [!NOTE]
204
-
> This method modifies the `layers` structure in place. If it comes from the return value of [`maplibregl.Map.prototype.getStyle()`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#getstyle), you must manually synchronize the layers with the style afterwards by calling [`maplibregl.Map.prototype.setStyle()`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#setstyle).
219
+
-**`options.uppercaseCountryNames`** (`boolean`): Whether to write country names in all uppercase, respecting the locale’s case conventions.
0 commit comments