From 5870603094b07322113a8d151f2c9f27c0a164df Mon Sep 17 00:00:00 2001 From: akxue <18199652+akxue@users.noreply.github.com> Date: Tue, 10 Nov 2026 19:50:57 +0000 Subject: [PATCH 1/5] Document the browser locale on managed auth connections --- auth/configuration.mdx | 91 ++++++++++++++++++++++++++++++++++++++++++ browsers/location.mdx | 2 +- 2 files changed, 92 insertions(+), 1 deletion(-) diff --git a/auth/configuration.mdx b/auth/configuration.mdx index dd5aaf8b..f33a847c 100644 --- a/auth/configuration.mdx +++ b/auth/configuration.mdx @@ -639,6 +639,96 @@ _ = login Browser placement and proxy location are independent. `browser.region` chooses where the browser runs; the connection's [proxy](/proxies/overview) controls the exit IP that websites see. Regional browsers don't provide a data residency guarantee. See [Regional Browsers](/browsers/regions) for storage and processing details. +## Browser locale + +Set `browser.location.locale` to choose the language the connection's browsers report to websites, through `navigator.language`, `Intl` formatting, and the `Accept-Language` header. The initial login, health checks, and automatic reauthentication all use it. Without it, browsers use the default for their [region](#browser-region), such as `en-US` for `us-east`. + +Use it when the site picks its language from the browser, so the field labels, MFA prompts, and site error messages your users see during login are in their language. It doesn't change sites that choose a language by domain or IP address, and it doesn't translate Kernel's hosted login page. + + +```typescript TypeScript +const auth = await kernel.auth.connections.create({ + domain: 'verkkokauppa.com', + profile_name: 'user-123', + browser: { location: { locale: 'sv-SE' } }, +}); +``` + +```python Python +auth = await kernel.auth.connections.create( + domain="verkkokauppa.com", + profile_name="user-123", + browser={"location": {"locale": "sv-SE"}}, +) +``` + +```go Go +auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ + ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ + Domain: "verkkokauppa.com", + ProfileName: "user-123", + Browser: kernel.ManagedAuthBrowserConfigParam{ + Location: kernel.ManagedAuthBrowserLocationParam{ + Locale: kernel.String("sv-SE"), + }, + }, + }, +}) +if err != nil { + panic(err) +} +_ = auth +``` + + +`locale` accepts the same BCP 47 tags as [browser location](/browsers/location). Kernel normalizes spelling, so `sv-se` is stored and returned as `sv-SE`. An unsupported value returns a `400` with code `invalid_browser_location`. Connections set the locale only; the timezone follows the browser's region. + +To change the locale, update the connection. Leave `location` out to keep the current value, or set `locale` to `null` to go back to the region default: + + +```typescript TypeScript +await kernel.auth.connections.update(auth.id, { + browser: { location: { locale: 'fi-FI' } }, +}); + +await kernel.auth.connections.update(auth.id, { + browser: { location: { locale: null } }, +}); +``` + +```python Python +await kernel.auth.connections.update( + auth.id, + browser={"location": {"locale": "fi-FI"}}, +) + +await kernel.auth.connections.update( + auth.id, + browser={"location": {"locale": None}}, +) +``` + +```go Go +// import "github.com/kernel/kernel-go-sdk/packages/param" +_, err := client.Auth.Connections.Update(ctx, auth.ID, kernel.AuthConnectionUpdateParams{ + ManagedAuthUpdateRequest: kernel.ManagedAuthUpdateRequestParam{ + Browser: kernel.ManagedAuthBrowserConfigParam{ + Location: kernel.ManagedAuthBrowserLocationParam{ + Locale: param.Null[string](), + }, + }, + }, +}) +if err != nil { + panic(err) +} +``` + + +The new value applies to the next browser the connection creates. It doesn't change a login, health check, or reauthentication that's already running. The locale belongs to the connection, so passing `browser.location` to `auth.connections.login` returns a `400`. + +If a later browser version stops supporting a stored locale, the connection's browsers use the region default instead and the stored value stays unchanged. + ## SSO/OAuth support Managed Auth supports common "Sign in with Google/GitHub/Microsoft" flows. The user completes the OAuth flow with the provider, and Kernel saves the authenticated session to the profile. Automatic reauthentication depends on the provider's login requirements. See [Can this connection auto-reauth?](/auth/connection-lifecycle#can-this-connection-auto-reauth) for how Kernel determines eligibility. @@ -919,6 +1009,7 @@ After creating a connection, you can update its configuration with `auth.connect | `save_credentials` | Whether to save credentials on successful login | | `record_session` | Record a [replay](/browsers/replays) of every auth browser session for this connection (logins, health checks, and reauths) | | `browser.region` | Region for login, health-check, and reauth browsers. Takes effect on the next browser created for the connection | +| `browser.location.locale` | Locale for login, health-check, and reauth browsers. Set to `null` to use the region default. Takes effect on the next browser created for the connection | | `proxy` | Pin login, health-check, and reauth sessions to a proxy. Takes effect on the next health check or reauth | Only the fields you include are updated—everything else stays the same. Changes to `health_check_interval`, `health_checks`, `auto_reauth`, and `proxy` take effect immediately on the running connection. diff --git a/browsers/location.mdx b/browsers/location.mdx index a12946db..9b8a9a5f 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -107,5 +107,5 @@ Browser responses include the timezone and locale the browser is using, and whet - Date and number formatters a page already created keep their original settings. Create a new one, such as `new Intl.DateTimeFormat()`, to use the new values. - Requests already in progress keep their original language. Later requests use the new one. - A timezone or locale you set yourself through Playwright or Puppeteer, such as Playwright's `timezoneId`, takes precedence on the pages it applies to. -- The location lasts for the browser session. Profiles don't save it. +- The location lasts for the browser session. Profiles don't save it. To set the locale for [Managed Auth](/auth/configuration#browser-locale) browsers, set it on the connection. - A pooled browser you release with `reuse: true` keeps its location for the next acquirer, just as it keeps cookies and open tabs. Release it with `reuse: false` to get a fresh browser instead. From 9cf7cdbf7dca3686c02dbc090cd8c426e2a7c0b8 Mon Sep 17 00:00:00 2001 From: akxue <18199652+akxue@users.noreply.github.com> Date: Tue, 10 Nov 2026 19:56:55 +0000 Subject: [PATCH 2/5] Align the managed auth locale docs with browser location --- auth/configuration.mdx | 8 +++++--- browsers/location.mdx | 2 +- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/auth/configuration.mdx b/auth/configuration.mdx index f33a847c..e2d9f4eb 100644 --- a/auth/configuration.mdx +++ b/auth/configuration.mdx @@ -641,9 +641,9 @@ Browser placement and proxy location are independent. `browser.region` chooses w ## Browser locale -Set `browser.location.locale` to choose the language the connection's browsers report to websites, through `navigator.language`, `Intl` formatting, and the `Accept-Language` header. The initial login, health checks, and automatic reauthentication all use it. Without it, browsers use the default for their [region](#browser-region), such as `en-US` for `us-east`. +Set `browser.location.locale` to choose the language the connection's browsers report to websites. It's the same locale setting as [browser location](/browsers/location): it applies to `Intl`, `navigator.language`, `navigator.languages`, and `Accept-Language` headers. The initial login, health checks, and automatic reauthentication all use it. Without it, browsers use the default for their [region](#browser-region), such as `en-US` for `us-east`. -Use it when the site picks its language from the browser, so the field labels, MFA prompts, and site error messages your users see during login are in their language. It doesn't change sites that choose a language by domain or IP address, and it doesn't translate Kernel's hosted login page. +Use it when the site picks its language from the browser, so the field labels, MFA prompts, and site error messages your users see during login are in their language. It doesn't change sites that choose a language by domain or IP address. Like browser location, it doesn't set geolocation or guarantee a bot-detection outcome, and it doesn't translate KERNEL's hosted login page. To translate the text of the embedded login component, use its [`localization`](/auth/react#localization) prop. ```typescript TypeScript @@ -681,7 +681,9 @@ _ = auth ``` -`locale` accepts the same BCP 47 tags as [browser location](/browsers/location). Kernel normalizes spelling, so `sv-se` is stored and returned as `sv-SE`. An unsupported value returns a `400` with code `invalid_browser_location`. Connections set the locale only; the timezone follows the browser's region. +`locale` accepts the same BCP 47 tags as browser location. KERNEL normalizes spelling and deprecated codes, so `sv-se` is stored and returned as `sv-SE`. An unsupported value such as `en-QQ` returns a `400` with code `invalid_browser_location`. Connections set the locale only; the timezone follows the browser's region. + +The locale is independent of `browser.region` and the connection's proxy. Choose the locale that matches your user, not the browser's region or exit IP. To change the locale, update the connection. Leave `location` out to keep the current value, or set `locale` to `null` to go back to the region default: diff --git a/browsers/location.mdx b/browsers/location.mdx index 9b8a9a5f..fe579398 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -107,5 +107,5 @@ Browser responses include the timezone and locale the browser is using, and whet - Date and number formatters a page already created keep their original settings. Create a new one, such as `new Intl.DateTimeFormat()`, to use the new values. - Requests already in progress keep their original language. Later requests use the new one. - A timezone or locale you set yourself through Playwright or Puppeteer, such as Playwright's `timezoneId`, takes precedence on the pages it applies to. -- The location lasts for the browser session. Profiles don't save it. To set the locale for [Managed Auth](/auth/configuration#browser-locale) browsers, set it on the connection. +- The location lasts for the browser session. Profiles don't save it. [Managed Auth](/auth/configuration#browser-locale) browsers take their locale from the connection instead. - A pooled browser you release with `reuse: true` keeps its location for the next acquirer, just as it keeps cookies and open tabs. Release it with `reuse: false` to get a fresh browser instead. From da281f3614adcaf6f291657aa038e6e209298460 Mon Sep 17 00:00:00 2001 From: akxue <18199652+akxue@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:00:19 +0000 Subject: [PATCH 3/5] Point the managed auth locale docs at browser location --- auth/configuration.mdx | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/auth/configuration.mdx b/auth/configuration.mdx index e2d9f4eb..f521a5cd 100644 --- a/auth/configuration.mdx +++ b/auth/configuration.mdx @@ -641,9 +641,9 @@ Browser placement and proxy location are independent. `browser.region` chooses w ## Browser locale -Set `browser.location.locale` to choose the language the connection's browsers report to websites. It's the same locale setting as [browser location](/browsers/location): it applies to `Intl`, `navigator.language`, `navigator.languages`, and `Accept-Language` headers. The initial login, health checks, and automatic reauthentication all use it. Without it, browsers use the default for their [region](#browser-region), such as `en-US` for `us-east`. +Managed Auth signs in to the site with browsers it creates for the connection. By default, those browsers use English, such as `en-US` for a browser in `us-east`. Set `browser.location.locale` on the connection to use another language, such as `sv-SE` for Swedish. Sites that choose their language from the browser then show their login page, field labels, MFA prompts, and error messages in that language. -Use it when the site picks its language from the browser, so the field labels, MFA prompts, and site error messages your users see during login are in their language. It doesn't change sites that choose a language by domain or IP address. Like browser location, it doesn't set geolocation or guarantee a bot-detection outcome, and it doesn't translate KERNEL's hosted login page. To translate the text of the embedded login component, use its [`localization`](/auth/react#localization) prop. +This is the [browser location](/browsers/location) locale, set on the connection instead of on each browser. KERNEL applies it to every browser the connection uses: the first login, health checks, and automatic reauthentication. That page covers the accepted values and what the locale changes in the browser. ```typescript TypeScript @@ -681,11 +681,7 @@ _ = auth ``` -`locale` accepts the same BCP 47 tags as browser location. KERNEL normalizes spelling and deprecated codes, so `sv-se` is stored and returned as `sv-SE`. An unsupported value such as `en-QQ` returns a `400` with code `invalid_browser_location`. Connections set the locale only; the timezone follows the browser's region. - -The locale is independent of `browser.region` and the connection's proxy. Choose the locale that matches your user, not the browser's region or exit IP. - -To change the locale, update the connection. Leave `location` out to keep the current value, or set `locale` to `null` to go back to the region default: +Update the connection to change the locale, or set it to `null` to go back to the region default: ```typescript TypeScript @@ -727,9 +723,11 @@ if err != nil { ``` -The new value applies to the next browser the connection creates. It doesn't change a login, health check, or reauthentication that's already running. The locale belongs to the connection, so passing `browser.location` to `auth.connections.login` returns a `400`. - -If a later browser version stops supporting a stored locale, the connection's browsers use the region default instead and the stored value stays unchanged. +- The new value applies to the next browser the connection creates, not to one that's already running. +- The locale belongs to the connection, so passing `browser.location` to `auth.connections.login` returns a `400`. +- Connections set the locale only; the timezone follows the browser's region. +- KERNEL's own text on the hosted login page stays in English. To translate the embedded login component, use its [`localization`](/auth/react#localization) prop. +- If a later browser version stops supporting a stored locale, the connection's browsers use the region default and the stored value stays unchanged. ## SSO/OAuth support @@ -1011,7 +1009,7 @@ After creating a connection, you can update its configuration with `auth.connect | `save_credentials` | Whether to save credentials on successful login | | `record_session` | Record a [replay](/browsers/replays) of every auth browser session for this connection (logins, health checks, and reauths) | | `browser.region` | Region for login, health-check, and reauth browsers. Takes effect on the next browser created for the connection | -| `browser.location.locale` | Locale for login, health-check, and reauth browsers. Set to `null` to use the region default. Takes effect on the next browser created for the connection | +| `browser.location.locale` | Language for login, health-check, and reauth browsers, such as `sv-SE`. Set to `null` to go back to the region default. Takes effect on the next browser created for the connection | | `proxy` | Pin login, health-check, and reauth sessions to a proxy. Takes effect on the next health check or reauth | Only the fields you include are updated—everything else stays the same. Changes to `health_check_interval`, `health_checks`, `auto_reauth`, and `proxy` take effect immediately on the running connection. From 32950264f2f03b470ba11d53a233c06dc4bf278c Mon Sep 17 00:00:00 2001 From: akxue <18199652+akxue@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:14:24 +0000 Subject: [PATCH 4/5] Use example.com in the managed auth locale examples --- auth/configuration.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/auth/configuration.mdx b/auth/configuration.mdx index f521a5cd..3ea37485 100644 --- a/auth/configuration.mdx +++ b/auth/configuration.mdx @@ -648,7 +648,7 @@ This is the [browser location](/browsers/location) locale, set on the connection ```typescript TypeScript const auth = await kernel.auth.connections.create({ - domain: 'verkkokauppa.com', + domain: 'example.com', profile_name: 'user-123', browser: { location: { locale: 'sv-SE' } }, }); @@ -656,7 +656,7 @@ const auth = await kernel.auth.connections.create({ ```python Python auth = await kernel.auth.connections.create( - domain="verkkokauppa.com", + domain="example.com", profile_name="user-123", browser={"location": {"locale": "sv-SE"}}, ) @@ -665,7 +665,7 @@ auth = await kernel.auth.connections.create( ```go Go auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ - Domain: "verkkokauppa.com", + Domain: "example.com", ProfileName: "user-123", Browser: kernel.ManagedAuthBrowserConfigParam{ Location: kernel.ManagedAuthBrowserLocationParam{ From c57b0f5d931d64dbe01e2535290b74a044967a71 Mon Sep 17 00:00:00 2001 From: akxue <18199652+akxue@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:15:10 +0000 Subject: [PATCH 5/5] Keep the managed auth locale section to an overview --- auth/configuration.mdx | 52 +++--------------------------------------- 1 file changed, 3 insertions(+), 49 deletions(-) diff --git a/auth/configuration.mdx b/auth/configuration.mdx index 3ea37485..cf64b5cd 100644 --- a/auth/configuration.mdx +++ b/auth/configuration.mdx @@ -641,9 +641,7 @@ Browser placement and proxy location are independent. `browser.region` chooses w ## Browser locale -Managed Auth signs in to the site with browsers it creates for the connection. By default, those browsers use English, such as `en-US` for a browser in `us-east`. Set `browser.location.locale` on the connection to use another language, such as `sv-SE` for Swedish. Sites that choose their language from the browser then show their login page, field labels, MFA prompts, and error messages in that language. - -This is the [browser location](/browsers/location) locale, set on the connection instead of on each browser. KERNEL applies it to every browser the connection uses: the first login, health checks, and automatic reauthentication. That page covers the accepted values and what the locale changes in the browser. +By default, the browsers Managed Auth uses for a connection report an English locale to websites, such as `en-US` in `us-east`. If your users sign in to sites in another language, set `browser.location.locale` on the connection, for example `sv-SE` for Swedish. Sites that choose their language from the browser then show their login page, field labels, and MFA prompts in your user's language. ```typescript TypeScript @@ -681,53 +679,9 @@ _ = auth ``` -Update the connection to change the locale, or set it to `null` to go back to the region default: - - -```typescript TypeScript -await kernel.auth.connections.update(auth.id, { - browser: { location: { locale: 'fi-FI' } }, -}); - -await kernel.auth.connections.update(auth.id, { - browser: { location: { locale: null } }, -}); -``` - -```python Python -await kernel.auth.connections.update( - auth.id, - browser={"location": {"locale": "fi-FI"}}, -) - -await kernel.auth.connections.update( - auth.id, - browser={"location": {"locale": None}}, -) -``` - -```go Go -// import "github.com/kernel/kernel-go-sdk/packages/param" -_, err := client.Auth.Connections.Update(ctx, auth.ID, kernel.AuthConnectionUpdateParams{ - ManagedAuthUpdateRequest: kernel.ManagedAuthUpdateRequestParam{ - Browser: kernel.ManagedAuthBrowserConfigParam{ - Location: kernel.ManagedAuthBrowserLocationParam{ - Locale: param.Null[string](), - }, - }, - }, -}) -if err != nil { - panic(err) -} -``` - +The locale applies to every browser the connection uses: the first login, health checks, and automatic reauthentication. Change it with `auth.connections.update`, or set it to `null` to go back to the default. -- The new value applies to the next browser the connection creates, not to one that's already running. -- The locale belongs to the connection, so passing `browser.location` to `auth.connections.login` returns a `400`. -- Connections set the locale only; the timezone follows the browser's region. -- KERNEL's own text on the hosted login page stays in English. To translate the embedded login component, use its [`localization`](/auth/react#localization) prop. -- If a later browser version stops supporting a stored locale, the connection's browsers use the region default and the stored value stays unchanged. +This is the same `locale` as [browser location](/browsers/location), applied to the connection's browsers. See that page for supported values and how the locale affects the browser. ## SSO/OAuth support