LocaleRegion API

specs/ScriptLocale.md

@@ -0,0 +1,111 @@
+ScriptLocale
+===
+
+# Background
+Developers have requested access to programmatically choose the specific locale/region to use in WebView2. 
+The locale/region updates the JavaScript region (objects in the ECMA standard) which gets reflected as
+variations in time and date formats. Currently, the locale is by default set to the same value as the 
+display language. 
+
+You can use the `ScriptLocale` property to update the locale value individually from the display
+language.
+
+# Description
+* The intended value for `SciptLocale` is in the format of BCP 47 Language Tags. 
+* More information can be found at [IETF BCP47](https://www.ietf.org/rfc/bcp/bcp47.html).
+# Examples
+```cpp
+ControllerOptions CreateAndInitializeCoreWebView2ControllerAndOptions(std::string locale) 
+{
+    auto webViewEnvironment10 = m_webViewEnvironment.try_query<ICoreWebView2Environment10>();
+    CHECK_FEATURE_RETURN(webViewEnvironment10);
+    wil::com_ptr<ICoreWebView2ControllerOptions> options;
+    CHECK_FAILURE(webViewEnvironment10->CreateCoreWebView2ControllerOptions(&options));
+    options->put_ScriptLocale(locale);
+    return options;
+}
+```
+
+```c#
+CoreWebView2Environment environment;
+CoreWebView2ControllerOptions CreateAndInitializeCoreWebView2ControllerOptions(CoreWebView2Environment environment, string locale)
+{
+    CoreWebView2ControllerOptions controllerOptions = null;
+    controllerOptions = environment.CreateCoreWebView2ControllerOptions();
+    controllerOptions.ScriptLocale = locale;
+    return controllerOptions;    
+}
+```
+
+# API Details
+```cpp
+[uuid(06c991d8-9e7e-11ed-a8fc-0242ac120002), object, pointer_default(unique)]
+interface ICoreWebView2ControllerOptions2 : ICoreWebView2ControllerOptions {
+  /// The default locale for the WebView2.  It sets the default locale for all
+  /// Intl JavaScript APIs and other JavaScript APIs that depend on it, namely
+  /// `Intl.DateTimeFormat()` which affects string formatting like
+  /// in the time/date formats. Example: `Intl.DateTimeFormat().format(new Date())`
+  /// The intended locale value is in the format of
+  /// BCP 47 Language Tags. More information can be found from
+  /// [IETF BCP47](https://www.ietf.org/rfc/bcp/bcp47.html).
+  ///
+  /// This property sets the locale for a CoreWebView2Environment used to create the
+  /// WebView2ControllerOptions object, which is passed as a parameter in
+  /// `CreateCoreWebView2ControllerWithOptions`.
+  ///
+  /// Changes to the ScriptLocale property apply to renderer processes created after
+  /// the change. Any existing renderer processes will continue to use the previous
+  /// ScriptLocale value. To ensure changes are applied to all renderer process,
+  /// close and restart the CoreWebView2Environment and all associated WebView2 objects.
+  ///
+  /// The default value for ScriptLocale will depend on the WebView2 language
+  /// and OS region. If the language portions of the WebView2 language and OS region
+  /// match, then it will use the OS region. Otherwise, it will use the WebView2
+  /// language.
+  ///
+  /// | **OS Region** | **WebView2 Language** | **Default WebView2 ScriptLocale** |
+  /// |-----------|-------------------|-------------------------------|
+  /// | en-GB     | en-US             | en-GB                         |
+  /// | es-MX     | en-US             | en-US                         |
+  /// | en-US     | en-GB             | en-US                         |
+  /// You can set the ScriptLocale to the empty string to get the default ScriptLocale value.
+  ///
+  /// Use OS specific APIs to determine the OS region to use with this property
+  /// if you want to match the OS. For example:
+  ///
+  /// Win32 C++:
+  /// ```cpp
+  ///   wchar_t osLocale[LOCALE_NAME_MAX_LENGTH] = {0};
+  ///   GetUserDefaultLocaleName(osLocale, LOCALE_NAME_MAX_LENGTH);
+  /// ```
+  ///
+  /// .NET and WinRT C#:
+  /// ```cs
+  ///   CultureInfo cultureInfo = Thread.CurrentThread.CurrentCulture;
+  ///   return cultureInfo.Name
+  /// ```
+  ///
+  /// The caller must free the returned string with `CoTaskMemFree`.  See
+  /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings).
+  /// \snippet AppWindow.cpp ScriptLocaleSetting
+  // MSOWNERS: [email protected]
+  [propget] HRESULT ScriptLocale([out, retval] LPWSTR* locale);
+  /// Sets the `ScriptLocale` property.
+  // MSOWNERS: [email protected]
+  [propput] HRESULT ScriptLocale([in] LPCWSTR locale);
+}
+```
+
+```c#
+namespace Microsoft.Web.WebView2.Core
+{
+    runtimeclass CoreWebView2ControllerOptions
+    {        
+       // ...
+       [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2ControllerOptions")]
+       {
+
+           String ScriptLocale { get; set; };
+       }
+    }
+}