[ios] adapt Mapbox Streets–sourced layers for user preferred language (#9582)

* [ios] Update label localization

* [ios, macos] Move MGLVectorSource+MBXAdditions.h to darwin.

* [ios, macos] Adapt Mapbox Streets to the user preferred language.

* [ios, macos] Clarify style localization documentation.

* [ios, macos] Update localization examples

* [ios, macos] Add style language reset to original.

* [ios, macos] Update changelogs.

* [ios, macos] Rename Vector Source Additions to MGL standard.

* [ios, macos] Add suport for stop localization.

4 files changed, 219 insertions, 0 deletions

diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 8ffd7db2b2..8c009d22c6 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -610,6 +610,21 @@ MGL_EXPORT
  */
 @property (nonatomic, strong) MGLLight *light;
 
+#pragma mark Localizing Map Content
+
+/**
+ A Boolean value that determines whether the style attempts to localize labels in 
+ the style into the system’s preferred language.
+ 
+ When this property is enabled, the style automatically modifies the text property 
+ of any symbol style layer whose source is 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.
+ */
+@property (nonatomic) BOOL localizesLabels;
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/MGLStyle.mm b/platform/darwin/src/MGLStyle.mm
index eb838085d7..1e0a2e02b7 100644
--- a/platform/darwin/src/MGLStyle.mm
+++ b/platform/darwin/src/MGLStyle.mm
@@ -21,6 +21,7 @@
 #import "MGLSource.h"
 #import "MGLTileSource_Private.h"
 #import "MGLVectorSource.h"
+#import "MGLVectorSource+MGLAdditions.h"
 #import "MGLRasterSource.h"
 #import "MGLShapeSource.h"
 
@@ -48,11 +49,34 @@
     #import "NSImage+MGLAdditions.h"
 #endif
 
+/**
+ Model class for localization changes.
+ */
+@interface MGLTextLanguage: NSObject
+@property (strong, nonatomic) NSString *originalTextField;
+@property (strong, nonatomic) NSString *updatedTextField;
+
+- (instancetype)initWithTextLanguage:(NSString *)originalTextField updatedTextField:(NSString *)updatedTextField;
+
+@end
+
+@implementation MGLTextLanguage
+- (instancetype)initWithTextLanguage:(NSString *)originalTextField updatedTextField:(NSString *)updatedTextField
+{
+    if (self = [super init]) {
+        _originalTextField = originalTextField;
+        _updatedTextField = updatedTextField;
+    }
+    return self;
+}
+@end
+
 @interface MGLStyle()
 
 @property (nonatomic, readwrite, weak) MGLMapView *mapView;
 @property (readonly, copy, nullable) NSURL *URL;
 @property (nonatomic, readwrite, strong) NS_MUTABLE_DICTIONARY_OF(NSString *, MGLOpenGLStyleLayer *) *openGLLayers;
+@property (nonatomic) NS_MUTABLE_DICTIONARY_OF(NSString *, NS_DICTIONARY_OF(NSObject *, MGLTextLanguage *) *) *localizedLayersByIdentifier;
 
 @end
 
@@ -116,6 +140,7 @@ static NSURL *MGLStyleURL_emerald;
     if (self = [super init]) {
         _mapView = mapView;
         _openGLLayers = [NSMutableDictionary dictionary];
+        _localizedLayersByIdentifier = [NSMutableDictionary dictionary];
     }
     return self;
 }
@@ -609,4 +634,115 @@ static NSURL *MGLStyleURL_emerald;
             self.URL ? [NSString stringWithFormat:@"\"%@\"", self.URL] : self.URL];
 }
 
+#pragma mark Style language preferences
+
+- (void)setLocalizesLabels:(BOOL)localizesLabels
+{
+    if (_localizesLabels != localizesLabels) {
+        _localizesLabels = localizesLabels;
+    } else {
+        return;
+    }
+    
+    if (_localizesLabels) {
+        NSString *preferredLanguage = [MGLVectorSource preferredMapboxStreetsLanguage];
+        NSMutableDictionary *localizedKeysByKeyBySourceIdentifier = [NSMutableDictionary dictionary];
+        for (MGLSymbolStyleLayer *layer in self.layers) {
+            if (![layer isKindOfClass:[MGLSymbolStyleLayer class]]) {
+                continue;
+            }
+            
+            MGLVectorSource *source = (MGLVectorSource *)[self sourceWithIdentifier:layer.sourceIdentifier];
+            if (![source isKindOfClass:[MGLVectorSource class]] || !source.mapboxStreets) {
+                continue;
+            }
+            
+            NSDictionary *localizedKeysByKey = localizedKeysByKeyBySourceIdentifier[layer.sourceIdentifier];
+            if (!localizedKeysByKey) {
+                localizedKeysByKey = localizedKeysByKeyBySourceIdentifier[layer.sourceIdentifier] = [source localizedKeysByKeyForPreferredLanguage:preferredLanguage];
+            }
+            
+            NSString *(^stringByLocalizingString)(NSString *) = ^ NSString * (NSString *string) {
+                NSMutableString *localizedString = string.mutableCopy;
+                [localizedKeysByKey enumerateKeysAndObjectsUsingBlock:^(NSString * _Nonnull key, NSString * _Nonnull localizedKey, BOOL * _Nonnull stop) {
+                    NSAssert([key isKindOfClass:[NSString class]], @"key is not a string");
+                    NSAssert([localizedKey isKindOfClass:[NSString class]], @"localizedKey is not a string");
+                    [localizedString replaceOccurrencesOfString:[NSString stringWithFormat:@"{%@}", key]
+                                                     withString:[NSString stringWithFormat:@"{%@}", localizedKey]
+                                                        options:0
+                                                          range:NSMakeRange(0, localizedString.length)];
+                }];
+                return localizedString;
+            };
+            
+            if ([layer.text isKindOfClass:[MGLConstantStyleValue class]]) {
+                NSString *textField = [(MGLConstantStyleValue<NSString *> *)layer.text rawValue];
+                NSString *localizingString = stringByLocalizingString(textField);
+                if (![textField isEqualToString:localizingString]) {
+                    MGLTextLanguage *textLanguage = [[MGLTextLanguage alloc] initWithTextLanguage:textField
+                                                                                 updatedTextField:localizingString];
+                    [self.localizedLayersByIdentifier setObject:@{ textField : textLanguage } forKey:layer.identifier];
+                    layer.text = [MGLStyleValue<NSString *> valueWithRawValue:localizingString];
+                }
+            }
+            else if ([layer.text isKindOfClass:[MGLCameraStyleFunction class]]) {
+                MGLCameraStyleFunction *function = (MGLCameraStyleFunction<NSString *> *)layer.text;
+                NSMutableDictionary *stops = function.stops.mutableCopy;
+                NSMutableDictionary *cameraStops = [NSMutableDictionary dictionary];
+                [stops enumerateKeysAndObjectsUsingBlock:^(NSNumber *zoomLevel, MGLConstantStyleValue<NSString *> *stop, BOOL *done) {
+                    NSString *textField = stop.rawValue;
+                    NSString *localizingString = stringByLocalizingString(textField);
+                    if (![textField isEqualToString:localizingString]) {
+                        MGLTextLanguage *textLanguage = [[MGLTextLanguage alloc] initWithTextLanguage:textField
+                                                                                     updatedTextField:localizingString];
+                        [cameraStops setObject:textLanguage forKey:zoomLevel];
+                        stops[zoomLevel] = [MGLStyleValue<NSString *> valueWithRawValue:localizingString];
+                    }
+                    
+                }];
+                if (cameraStops.count > 0) {
+                    [self.localizedLayersByIdentifier setObject:cameraStops forKey:layer.identifier];
+                }
+                function.stops = stops;
+                layer.text = function;
+            }
+        }
+    } else {
+        
+        [self.localizedLayersByIdentifier enumerateKeysAndObjectsUsingBlock:^(NSString *identifier, NSDictionary<NSObject *, MGLTextLanguage *> *textFields, BOOL *done) {
+            MGLSymbolStyleLayer *layer = (MGLSymbolStyleLayer *)[self.mapView.style layerWithIdentifier:identifier];
+            
+            if ([layer.text isKindOfClass:[MGLConstantStyleValue class]]) {
+                NSString *textField = [(MGLConstantStyleValue<NSString *> *)layer.text rawValue];
+                [textFields enumerateKeysAndObjectsUsingBlock:^(NSObject *originalLanguage, MGLTextLanguage *textLanguage, BOOL *done) {
+                    if ([textLanguage.updatedTextField isEqualToString:textField]) {
+                        layer.text = [MGLStyleValue<NSString *> valueWithRawValue:textLanguage.originalTextField];
+                    }
+                }];
+
+            }
+            else if ([layer.text isKindOfClass:[MGLCameraStyleFunction class]]) {
+                MGLCameraStyleFunction *function = (MGLCameraStyleFunction<NSString *> *)layer.text;
+                NSMutableDictionary *stops = function.stops.mutableCopy;
+                [textFields enumerateKeysAndObjectsUsingBlock:^(NSObject *zoomKey, MGLTextLanguage *textLanguage, BOOL *done) {
+                    if ([zoomKey isKindOfClass:[NSNumber class]]) {
+                        NSNumber *zoomLevel = (NSNumber*)zoomKey;
+                        MGLConstantStyleValue<NSString *> *stop = [stops objectForKey:zoomLevel];
+                        NSString *textField = stop.rawValue;
+                        if ([textLanguage.updatedTextField isEqualToString:textField]) {
+                            stops[zoomLevel] = [MGLStyleValue<NSString *> valueWithRawValue:textLanguage.originalTextField];
+                        }
+                    }
+                }];
+
+                function.stops = stops;
+                layer.text = function;
+            }
+
+        }];
+
+        self.localizedLayersByIdentifier = [NSMutableDictionary dictionary];
+    }
+}
+
 @end
diff --git a/platform/darwin/src/MGLVectorSource+MGLAdditions.h b/platform/darwin/src/MGLVectorSource+MGLAdditions.h
new file mode 100644
index 0000000000..43b0aba747
--- /dev/null
+++ b/platform/darwin/src/MGLVectorSource+MGLAdditions.h
@@ -0,0 +1,15 @@
+#import <Mapbox/Mapbox.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface MGLVectorSource (MGLAdditions)
+
++ (NSString *)preferredMapboxStreetsLanguage;
+
+- (NS_DICTIONARY_OF(NSString *, NSString *) *)localizedKeysByKeyForPreferredLanguage:(nullable NSString *)preferredLanguage;
+
+@property (nonatomic, readonly, getter=isMapboxStreets) BOOL mapboxStreets;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/MGLVectorSource+MGLAdditions.m b/platform/darwin/src/MGLVectorSource+MGLAdditions.m
new file mode 100644
index 0000000000..a305388117
--- /dev/null
+++ b/platform/darwin/src/MGLVectorSource+MGLAdditions.m
@@ -0,0 +1,53 @@
+#import "MGLVectorSource+MGLAdditions.h"
+
+@implementation MGLVectorSource (MGLAdditions)
+
++ (NS_SET_OF(NSString *) *)mapboxStreetsLanguages {
+    // https://www.mapbox.com/vector-tiles/mapbox-streets-v7/#overview
+    static dispatch_once_t onceToken;
+    static NS_SET_OF(NSString *) *mapboxStreetsLanguages;
+    dispatch_once(&onceToken, ^{
+        // https://www.mapbox.com/vector-tiles/mapbox-streets-v7/#overview
+        mapboxStreetsLanguages = [NSSet setWithObjects:@"ar", @"de", @"en", @"es", @"fr", @"pt", @"ru", @"zh", @"zh-Hans", nil];
+    });
+    return mapboxStreetsLanguages;
+}
+
++ (NSString *)preferredMapboxStreetsLanguage {
+    NSArray<NSString *> *supportedLanguages = [MGLVectorSource mapboxStreetsLanguages].allObjects;
+    NSArray<NSString *> *preferredLanguages = [NSBundle preferredLocalizationsFromArray:supportedLanguages
+                                                                         forPreferences:[NSLocale preferredLanguages]];
+    NSString *mostSpecificLanguage;
+    for (NSString *language in preferredLanguages) {
+        if (language.length > mostSpecificLanguage.length) {
+            mostSpecificLanguage = language;
+        }
+    }
+    return mostSpecificLanguage ?: @"en";
+}
+
+- (BOOL)isMapboxStreets {
+    NSURL *url = self.configurationURL;
+    if (![url.scheme isEqualToString:@"mapbox"]) {
+        return NO;
+    }
+    NSArray *identifiers = [url.host componentsSeparatedByString:@","];
+    return [identifiers containsObject:@"mapbox.mapbox-streets-v7"] || [identifiers containsObject:@"mapbox.mapbox-streets-v6"];
+}
+
+- (NS_DICTIONARY_OF(NSString *, NSString *) *)localizedKeysByKeyForPreferredLanguage:(nullable NSString *)preferredLanguage {
+    if (!self.mapboxStreets) {
+        return @{};
+    }
+
+    // Replace {name} and {name_*} with the matching localized name tag.
+    NSString *localizedKey = preferredLanguage ? [NSString stringWithFormat:@"name_%@", preferredLanguage] : @"name";
+    NSMutableDictionary *localizedKeysByKey = [NSMutableDictionary dictionaryWithObject:localizedKey forKey:@"name"];
+    for (NSString *languageCode in [MGLVectorSource mapboxStreetsLanguages]) {
+        NSString *key = [NSString stringWithFormat:@"name_%@", languageCode];
+        localizedKeysByKey[key] = localizedKey;
+    }
+    return localizedKeysByKey;
+}
+
+@end