Localize expressions more thoroughly (#11651)

* [ios] Removed changelog entry for Terrarium

The broader feature is new to v4.0.0 as well.

* [ios, macos] Localize expressions more thoroughly

Replaced the MGLStyle.localizesLabels property with a -localizeLabelsIntoLocale: method that allows the caller to specify the locale to localize into. Also exposed a per-expression localization method for developers who want to vary behavior from layer to layer.

* [macos] Offer English labels if preferred language is unsupported

* [ios, macos] Removed dead code

* [ios] Use new localization method in iosapp

* [ios, macos] Fixed local name labels

* [ios, macos] Convert tokens to key path expressions in stop dictionaries

* [ios, macos] Streamlined token upgrading

Separated token upgrading into a separate process that only happens as part of the MGLSymbolStyleLayer.text and MGLSymbolStyleLayer.iconImageName properties’ getters, so that it’s easy to remove later when mbgl changes obviate this workaround. Removed the replacesTokens parameter to the expression localization methods.

* [ios, macos] Preserve whitespace between tokens

* [ios, macos] Moved token replacement to a consistent category

Fixed a build warning.

* [ios, macos] Replace tokens in all string-typed getters

For consistency, replace tokens with key paths in all string-typed style paint and layout properties.

* [ios, macos] Test token replacement

Added tests for replacement of tokens with key paths in expressions. Fixed token replacement for raw strings in stop dictionaries. Avoid sticking a single string inside an mgl_join: call.

* [ios, macos] Test token replacement, localization

Added unit tests of token replacement and localization of expressions. Only NSExpression is responsible for resolving the preferred language now, since NSLocale tends to tack a region code onto the locale identifier and the NSExpression method can be called independently anyways. Added a private variation of +[MGLVectorTileSource preferredMapboxStreetsLanguage] that takes an array of preferred languages. Fixed localization of non-expressions in stop dictionaries.

* [ios, macos] Dictionary keys aren’t necessarily zoom levels

1 files changed, 16 insertions, 0 deletions

diff --git a/platform/darwin/src/NSExpression+MGLAdditions.h b/platform/darwin/src/NSExpression+MGLAdditions.h
index 66d306ad06..a0081cb428 100644
--- a/platform/darwin/src/NSExpression+MGLAdditions.h
+++ b/platform/darwin/src/NSExpression+MGLAdditions.h
@@ -44,6 +44,22 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nonatomic, readonly) id mgl_jsonExpressionObject;
 
+/**
+ Returns a copy of the receiver localized into the given locale.
+ 
+ This method assumes the receiver refers to the feature attributes that are
+ available in vector tiles supplied by the
+ <a href="https://www.mapbox.com/vector-tiles/mapbox-streets-v7/#overview">Mapbox Streets source</a>.
+ On iOS, the user can set the system’s preferred language in Settings, General
+ Settings, Language & Region. On macOS, the user can set the system’s preferred
+ language in the Language & Region pane of System Preferences.
+ 
+ @param locale The locale into which labels should be localized. To use the
+    system’s preferred language, if supported, specify `nil`. To use the local
+    language, specify a locale with the identifier `mul`.
+ */
+- (NSExpression *)mgl_expressionLocalizedIntoLocale:(nullable NSLocale *)locale;
+
 @end
 
 NS_ASSUME_NONNULL_END