diff --git a/specs/LocaleRegion.md b/specs/LocaleRegion.md index 34cc37742..1dface8a7 100644 --- a/specs/LocaleRegion.md +++ b/specs/LocaleRegion.md @@ -14,9 +14,6 @@ language. * The intended value for `LocaleRegion` is in the format of `language[-country]` where `language` is the 2-letter code from [ISO 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). -* By default, the `LocaleRegion` will be set as the value for the Limited option in the browser. -That means that if the OS region and the display language share the same language code, -like 'en-GB' and 'en-US', the value will be set to the OS region. # Examples ```cpp @@ -51,22 +48,36 @@ public CreateWebView2Controller(IntPtr parentWindow) ```cpp [uuid(0c9a374f-20c3-4e3c-a640-67b78a7e0a48), object, pointer_default(unique)] interface ICoreWebView2StagingControllerOptions : IUnknown { - /// Interface for locale region that is updated through the ControllerOptions - /// API. - /// The default region for WebView. It applies to browser UI such as + /// The default region for the WebView2. It applies to JavaScript API + /// Intl.DateTimeFormat() which affects string formatting like /// in the time/date formats. The intended locale value is in the format of /// `language[-country]` where `language` is the 2-letter code from [ISO /// 639](https://www.iso.org/iso-639-language-codes.html) and `country` is the /// 2-letter code from [ISO 3166](https://www.iso.org/standard/72482.html). /// + /// This property will update the environment creation. This is global and immutable, + /// so changes will not be reflected in the existing webviews. They will need to closed + /// and reopened in order to see the changes reflected from using the new creation environment. + /// /// Validation is done on the V8 engine to match on the closest locale /// from the passed in locale region value. For example, passing in "en_gb" /// will reflect the "en-GB" locale in V8. /// If V8 cannot find any matching locale on the input value, it will default /// to the display language as the locale. /// - /// The Windows API `GetLocaleInfoEx` can be used if the LocaleRegion value - /// is always set to match the OS region + /// The default value for LocaleRegion will be 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 LocaleRegion** | + /// |-----------|-------------------|-------------------------------| + /// | en-GB | en-US | en-GB | + /// | es-MX | en-US | en-US | + /// | en-US | en-GB | en-US | + /// The default value can be reset using the empty string. + /// + /// Use OS specific APIs to determine the OS region to use with this property + /// if you want to match the OS. For example: /// /// ```cpp /// int LanguageCodeBufferSize = @@ -78,15 +89,19 @@ interface ICoreWebView2StagingControllerOptions : IUnknown { /// wcstombs(buffer.get(), w_language_code, LanguageCodeBufferSize); /// delete[] w_language_code; /// return buffer; - /// ``` + /// ``` /// + /// ```c# + /// var geographicRegion = new Windows.Globalization.GeographicRegion(); + /// var regionCode = geographicRegion.CodeTwoLetter; + /// ``` /// The caller must free the returned string with `CoTaskMemFree`. See /// [API Conventions](/microsoft-edge/webview2/concepts/win32-api-conventions#strings). /// \snippet AppWindow.cpp RegionLocaleSetting // MSOWNERS: stevenwei@microsoft.com [propget] HRESULT LocaleRegion([out, retval] LPWSTR* locale); - /// Sets the `Region` property. + /// Sets the `LocaleRegion` property. // MSOWNERS: stevenwei@microsoft.com [propput] HRESULT LocaleRegion([in] LPCWSTR locale); }