fix(locale): document locale parameter (#990)

docs/api.md

@@ -196,6 +196,7 @@ Indicates that the browser is connected.
     - `latitude` <[number]> Latitude between -90 and 90.
     - `longitude` <[number]> Longitude between -180 and 180.
     - `accuracy` <[number]> Optional non-negative accuracy value.
+  - `locale` <?[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.
   - `permissions` <[Object]> A map from origin keys to permissions values. See [browserContext.setPermissions](#browsercontextsetpermissionsorigin-permissions) for more details.
 - returns: <[Promise]<[BrowserContext]>>
 
@@ -228,6 +229,7 @@ Creates a new browser context. It won't share cookies/cache with other browser c
     - `latitude` <[number]> Latitude between -90 and 90.
     - `longitude` <[number]> Longitude between -180 and 180.
     - `accuracy` <[number]> Optional non-negative accuracy value.
+  - `locale` <?[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules.
   - `permissions` <[Object]> A map from origin keys to permissions values. See [browserContext.setPermissions](#browsercontextsetpermissionsorigin-permissions) for more details.
 - returns: <[Promise]<[Page]>>
 

src/browserContext.ts

@@ -44,7 +44,7 @@ export type BrowserContextOptions = {
   javaScriptEnabled?: boolean,
   bypassCSP?: boolean,
   userAgent?: string,
-  language?: string,
+  locale?: string,
   timezoneId?: string,
   geolocation?: types.Geolocation,
   permissions?: { [key: string]: string[] };

src/chromium/crPage.ts

@@ -110,8 +110,8 @@ export class CRPage implements PageDelegate {
       promises.push(this._updateViewport(true /* updateTouch */));
     if (options.javaScriptEnabled === false)
       promises.push(this._client.send('Emulation.setScriptExecutionDisabled', { value: true }));
-    if (options.userAgent || options.language)
-      promises.push(this._client.send('Emulation.setUserAgentOverride', { userAgent: options.userAgent || '', acceptLanguage: options.language }));
+    if (options.userAgent || options.locale)
+      promises.push(this._client.send('Emulation.setUserAgentOverride', { userAgent: options.userAgent || '', acceptLanguage: options.locale }));
     if (options.timezoneId)
       promises.push(emulateTimezone(this._client, options.timezoneId));
     if (options.geolocation)

src/webkit/wkBrowser.ts

@@ -78,8 +78,8 @@ export class WKBrowser extends platform.EventEmitter implements Browser {
     const context = this._createBrowserContext(browserContextId, options);
     if (options.ignoreHTTPSErrors)
       await this._browserSession.send('Browser.setIgnoreCertificateErrors', { browserContextId, ignore: true });
-    if (options.language)
-      await this._browserSession.send('Browser.setLanguages', { browserContextId, languages: [options.language] });
+    if (options.locale)
+      await this._browserSession.send('Browser.setLanguages', { browserContextId, languages: [options.locale] });
     await context._initialize();
     this._contexts.set(browserContextId, context);
     return context;

src/webkit/wkPage.ts

@@ -142,10 +142,10 @@ export class WKPage implements PageDelegate {
     }
     if (contextOptions.bypassCSP)
       promises.push(session.send('Page.setBypassCSP', { enabled: true }));
-    if (this._page._state.extraHTTPHeaders || contextOptions.language) {
+    if (this._page._state.extraHTTPHeaders || contextOptions.locale) {
       const headers = this._page._state.extraHTTPHeaders || {};
-      if (contextOptions.language)
-        headers['Accept-Language'] = contextOptions.language;
+      if (contextOptions.locale)
+        headers['Accept-Language'] = contextOptions.locale;
       promises.push(session.send('Network.setExtraHTTPHeaders', { headers }));
     }
     if (this._page._state.hasTouch)
@@ -380,9 +380,9 @@ export class WKPage implements PageDelegate {
 
   async setExtraHTTPHeaders(headers: network.Headers): Promise<void> {
     const copy = { ...headers };
-    const language = this._page.context()._options.language;
-    if (language)
-      copy['Accept-Language'] = language;
+    const locale = this._page.context()._options.locale;
+    if (locale)
+      copy['Accept-Language'] = locale;
     await this._updateState('Network.setExtraHTTPHeaders', { headers: copy });
   }
 

test/emulation.spec.js

@@ -225,7 +225,7 @@ module.exports.describe = function({testRunner, expect, playwright, headless, FF
 
   describe.skip(CHROMIUM || FFOX)('BrowserContext({language})', function() {
     it('should affect accept-language header', async({newPage, server}) => {
-      const page = await newPage({ language: 'fr-CH' });
+      const page = await newPage({ locale: 'fr-CH' });
       const [request] = await Promise.all([
         server.waitForRequest('/empty.html'),
         page.goto(server.EMPTY_PAGE),
@@ -240,7 +240,7 @@ module.exports.describe = function({testRunner, expect, playwright, headless, FF
         expect(await page.evaluate(() => (1000000.50).toLocaleString())).toBe('1,000,000.5');
       }
       {
-        const page = await newPage({ language: 'fr-CH' });
+        const page = await newPage({ locale: 'fr-CH' });
         await page.goto(server.EMPTY_PAGE);
         expect(await page.evaluate(() => (1000000.50).toLocaleString())).toBe('1 000 000,5');
       }
@@ -253,7 +253,7 @@ module.exports.describe = function({testRunner, expect, playwright, headless, FF
             'Sat Nov 19 2016 10:12:34 GMT-0800 (PST)');
       }
       {
-        const page = await newPage({ language: 'de-de', timezoneId: 'Europe/Berlin' });
+        const page = await newPage({ locale: 'de-de', timezoneId: 'Europe/Berlin' });
         await page.goto(server.EMPTY_PAGE);
         expect(await page.evaluate(() => new Date(1479579154987).toString())).toBe(
             'Sat Nov 19 2016 19:12:34 GMT+0100 (Mitteleuropäische Normalzeit)');