Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-04
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
## Why

No spec says what `$locale` means. It is one of the oldest client auto-properties and the
`capture` spec names it nowhere — the only mention of a language anywhere in `openspec/specs/`
is the unrelated "the language's no-payload value" phrasing in the flag specs. So each client
SDK invented its own meaning, and the meanings disagreed:

- posthog-ios 3.x sent `Locale.current.languageCode` — a bare language subtag, `de` for a
`de-CH` device.
- posthog-android 3.x sent `Locale.getDefault()`, which is the *app's* locale: a per-app
language, a secondary device language, or whatever the app last passed to
`Locale.setDefault()`. It also dropped the script (`zh-TW` for `zh-Hant-TW`) and sent the
legacy codes `iw`, `in` and `ji`.
- posthog-react-native sends the platform's full `languageTag`.
- posthog_flutter's pure-Dart desktop client sends the language code only.
- posthog-kmp's JVM context sends `"${language}-${country}"` off `Locale.getDefault()`.

So `$locale = de` matched an iOS user and missed the Android one, and nothing reported the
language the app actually displays — the thing most people are reaching for when they break
down by `$locale`.

posthog-ios 4.0 ([posthog-ios#1009](https://github.com/PostHog/posthog-ios/pull/1009)) and
posthog-android 4.0 ([posthog-android#927](https://github.com/PostHog/posthog-android/pull/927),
closing [posthog-android#822](https://github.com/PostHog/posthog-android/issues/822)) settle it
together, as one cross-SDK change: `$locale` becomes the device's first preferred language as a
full language tag, a new `$app_language` carries the displayed language, and a new public
`setAppLanguage()` lets an app that translates some other way supply it. Both are breaking
changes to a property's meaning, which is exactly the kind of contract this repo exists to hold.

## What Changes

- `capture`: add one requirement defining `$locale` and `$app_language` for client SDKs that
report a language — what each one means, the language-tag form, when each is omitted, the
public override method, and the per-app-language divergence between iOS and Android that 4.0
leaves open.

## Capabilities

### New Capabilities

None.

### Modified Capabilities

- `capture`: `$locale` is the device language as a full language tag; `$app_language` is the
displayed language; a public setter overrides the latter in memory.

## Impact

- posthog-ios 4.0 and posthog-android 4.0 meet the requirement; it is written from them.
- posthog-react-native already sends a full `languageTag` for `$locale` and has no
`$app_language` or setter.
- posthog_flutter's desktop (Windows/Linux) client sends a bare language code for `$locale`.
- posthog-kmp's JVM context reads `Locale.getDefault()`, the app-influenced source the
requirement rules out, and composes a tag by hand.

Those three have to change to meet it. The requirement does not oblige an SDK that reports no
language today (posthog-js browser) to start.
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
## ADDED Requirements

### Requirement: Device language and app display language

A client SDK that reports the user's language SHALL report it as two distinct event properties, each carried on every event the SDK enriches with ambient context:

- **`$locale`** — the first language in the *device's own* language preferences, as a full IETF BCP 47 language tag carrying every subtag the platform reports: script and region included (`de-CH`, `zh-Hant-TW`), never reduced to the bare language subtag. Unicode extension subtags, such as the `-u-fw-mon` first-day-of-week preference, SHALL be stripped.
- **`$app_language`** — the language the app's user interface is actually displayed in, named the way the platform names that localization, which MAY itself carry a region or script (`de`, `pt-BR`, `zh-Hans`).

Neither property SHALL be read from a process-global locale default the app can set on itself — `Locale.getDefault()` on the JVM, `Locale.setDefault` anywhere — because such a default reports the app's own choice back as the device's preference. `$locale` SHALL be read from the platform's device-language API (iOS `Locale.preferredLanguages`, Android `LocaleManager.getSystemLocales()`), and `$app_language` from the app's own resolved localization.

Each property SHALL be omitted, not sent empty and not guessed, when the SDK has no value for it:

- `$locale` is omitted when the platform reports no language, or only a placeholder naming none (`und`, `C`, `POSIX`).
- `$app_language` is omitted when the SDK cannot determine the displayed language. Detection MAY be limited to the platform versions that expose it (posthog-android detects it on Android 13+ only), and an SDK that cannot determine it on a given platform version SHALL omit it rather than fall back to `$locale`.

Both properties SHALL be re-read, not captured once at setup, so a language changed while the app runs is reflected on later events. Reading them SHALL NOT block the setup or capture path on a system call that can be slow.

The SDK SHALL expose a public method that overrides `$app_language` — `setAppLanguage(_:)` on posthog-ios, `setAppLanguage()` on posthog-android — for an app that translates through its own mechanism rather than platform localizations. The method:

- SHALL accept the language as a string, and the platform's null or an empty/whitespace-only string to clear the override and return to detection;
- SHALL trim surrounding whitespace and normalize the value to language-tag form (`" pt_BR "` is sent as `pt-BR`);
- SHALL hold the override in memory only: it is not persisted, and `reset()` does not clear it, because it describes the app rather than the user.

A caller-supplied or registered `$app_language` property on an event SHALL win over both the override and detection, under the existing property-precedence requirement.

Neither property SHALL be sent on feature flag evaluation requests. An app that wants to target on language SHALL set it as a person property itself.

**Unresolved divergence — the per-app language.** Both platforms let a user pick a language for one app. iOS surfaces that choice as the first entry of `Locale.preferredLanguages`, so posthog-ios 4.0's `$locale` follows it; posthog-android 4.0's `$locale` stays the device-wide language and the per-app choice reaches `$app_language` only. For a user who has set a per-app language, `$locale` therefore means different things on the two platforms. This spec records the divergence and names no winner.

#### Scenario: The device language is sent as a full language tag (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "de-CH"

#### Scenario: A regional preference extension is left out of the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "en-US-u-fw-mon"
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "en-US"

#### Scenario: A locale default the app set on itself is not reported as the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **AND** the app has set its own process-global locale default to "es-ES"
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "de-CH"

#### Scenario: A platform naming no language sends no device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the platform reports the locale "und"
- **WHEN** an event is captured
- **THEN** the event properties should not include `$locale`

#### Scenario: The displayed language is sent separately from the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **AND** the app is displayed in its "de" localization
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "de-CH"
- **AND** the event properties should include `$app_language` with value "de"

#### Scenario: An undetectable displayed language is omitted rather than filled from the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "fr-FR"
- **AND** the SDK cannot determine the language the app displays
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "fr-FR"
- **AND** the event properties should not include `$app_language`

#### Scenario: A language changed while the app runs reaches later events (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **WHEN** an event is captured
- **AND** the device's first preferred language changes to "es-ES"
- **AND** a second event is captured
- **THEN** the first event properties should include `$locale` with value "de-CH"
- **AND** the second event properties should include `$locale` with value "es-ES"

#### Scenario: The app language override is trimmed and normalized (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app is displayed in its "en" localization
- **WHEN** the app language is set to " pt_BR "
- **AND** an event is captured
- **THEN** the event properties should include `$app_language` with value "pt-BR"

#### Scenario: Clearing the app language override returns to detection (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app is displayed in its "en" localization
- **AND** the app language is set to "de"
- **WHEN** the app language is set to the platform's null value
- **AND** an event is captured
- **THEN** the event properties should include `$app_language` with value "en"

#### Scenario: The app language override survives a reset (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app is displayed in its "en" localization
- **AND** the app language is set to "de"
- **WHEN** reset is called
- **AND** an event is captured
- **THEN** the event properties should include `$app_language` with value "de"

#### Scenario: A caller-supplied app language wins over the override (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app language is set to "de"
- **WHEN** capture is called with properties:
| property | value |
| $app_language | fr |
- **THEN** the event properties should include `$app_language` with value "fr"
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
## 1. Verification

- [x] 1.1 Read posthog-ios#1009 and posthog-android#927 — sources, API dumps, changesets and migration guides — for the `$locale` source, the `$app_language` source and its availability, and the `setAppLanguage` surface and lifetime
- [x] 1.2 Check what every other in-scope client SDK sends for `$locale` today (posthog-js browser and react-native, posthog_flutter desktop, posthog-kmp, posthog-unity)
- [x] 1.3 Confirm `openspec/specs/`, `acceptance/` and `compliance/` say nothing about `$locale` or an app language
- [x] 1.4 Check no open sdk-specs PR covers it (#170, #171 are flag/Flutter surface records; #151, #166 are before-send)

## 2. Spec delta

- [x] 2.1 Write the `capture` delta
- [x] 2.2 Review the delta: the requirement has scenarios, and scenarios use WHEN/THEN

## 3. Archive

- [x] 3.1 Sync the delta into `openspec/specs/capture/spec.md` and archive the change
108 changes: 108 additions & 0 deletions openspec/specs/capture/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -622,3 +622,111 @@ A backward clock change SHALL only pause refill until the clock catches up. It S
- **AND** no event named "Four" should be enqueued
- **AND** one event named "Five" should be enqueued

### Requirement: Device language and app display language

A client SDK that reports the user's language SHALL report it as two distinct event properties, each carried on every event the SDK enriches with ambient context:

- **`$locale`** — the first language in the *device's own* language preferences, as a full IETF BCP 47 language tag carrying every subtag the platform reports: script and region included (`de-CH`, `zh-Hant-TW`), never reduced to the bare language subtag. Unicode extension subtags, such as the `-u-fw-mon` first-day-of-week preference, SHALL be stripped.
- **`$app_language`** — the language the app's user interface is actually displayed in, named the way the platform names that localization, which MAY itself carry a region or script (`de`, `pt-BR`, `zh-Hans`).

Neither property SHALL be read from a process-global locale default the app can set on itself — `Locale.getDefault()` on the JVM, `Locale.setDefault` anywhere — because such a default reports the app's own choice back as the device's preference. `$locale` SHALL be read from the platform's device-language API (iOS `Locale.preferredLanguages`, Android `LocaleManager.getSystemLocales()`), and `$app_language` from the app's own resolved localization.

Each property SHALL be omitted, not sent empty and not guessed, when the SDK has no value for it:

- `$locale` is omitted when the platform reports no language, or only a placeholder naming none (`und`, `C`, `POSIX`).
- `$app_language` is omitted when the SDK cannot determine the displayed language. Detection MAY be limited to the platform versions that expose it (posthog-android detects it on Android 13+ only), and an SDK that cannot determine it on a given platform version SHALL omit it rather than fall back to `$locale`.

Both properties SHALL be re-read, not captured once at setup, so a language changed while the app runs is reflected on later events. Reading them SHALL NOT block the setup or capture path on a system call that can be slow.

The SDK SHALL expose a public method that overrides `$app_language` — `setAppLanguage(_:)` on posthog-ios, `setAppLanguage()` on posthog-android — for an app that translates through its own mechanism rather than platform localizations. The method:

- SHALL accept the language as a string, and the platform's null or an empty/whitespace-only string to clear the override and return to detection;
- SHALL trim surrounding whitespace and normalize the value to language-tag form (`" pt_BR "` is sent as `pt-BR`);
- SHALL hold the override in memory only: it is not persisted, and `reset()` does not clear it, because it describes the app rather than the user.

A caller-supplied or registered `$app_language` property on an event SHALL win over both the override and detection, under the existing property-precedence requirement.

Neither property SHALL be sent on feature flag evaluation requests. An app that wants to target on language SHALL set it as a person property itself.

**Unresolved divergence — the per-app language.** Both platforms let a user pick a language for one app. iOS surfaces that choice as the first entry of `Locale.preferredLanguages`, so posthog-ios 4.0's `$locale` follows it; posthog-android 4.0's `$locale` stays the device-wide language and the per-app choice reaches `$app_language` only. For a user who has set a per-app language, `$locale` therefore means different things on the two platforms. This spec records the divergence and names no winner.

#### Scenario: The device language is sent as a full language tag (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "de-CH"

#### Scenario: A regional preference extension is left out of the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "en-US-u-fw-mon"
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "en-US"

#### Scenario: A locale default the app set on itself is not reported as the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **AND** the app has set its own process-global locale default to "es-ES"
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "de-CH"

#### Scenario: A platform naming no language sends no device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the platform reports the locale "und"
- **WHEN** an event is captured
- **THEN** the event properties should not include `$locale`

#### Scenario: The displayed language is sent separately from the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **AND** the app is displayed in its "de" localization
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "de-CH"
- **AND** the event properties should include `$app_language` with value "de"

#### Scenario: An undetectable displayed language is omitted rather than filled from the device language (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "fr-FR"
- **AND** the SDK cannot determine the language the app displays
- **WHEN** an event is captured
- **THEN** the event properties should include `$locale` with value "fr-FR"
- **AND** the event properties should not include `$app_language`

#### Scenario: A language changed while the app runs reaches later events (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the device's first preferred language is "de-CH"
- **WHEN** an event is captured
- **AND** the device's first preferred language changes to "es-ES"
- **AND** a second event is captured
- **THEN** the first event properties should include `$locale` with value "de-CH"
- **AND** the second event properties should include `$locale` with value "es-ES"

#### Scenario: The app language override is trimmed and normalized (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app is displayed in its "en" localization
- **WHEN** the app language is set to " pt_BR "
- **AND** an event is captured
- **THEN** the event properties should include `$app_language` with value "pt-BR"

#### Scenario: Clearing the app language override returns to detection (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app is displayed in its "en" localization
- **AND** the app language is set to "de"
- **WHEN** the app language is set to the platform's null value
- **AND** an event is captured
- **THEN** the event properties should include `$app_language` with value "en"

#### Scenario: The app language override survives a reset (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app is displayed in its "en" localization
- **AND** the app language is set to "de"
- **WHEN** reset is called
- **AND** an event is captured
- **THEN** the event properties should include `$app_language` with value "de"

#### Scenario: A caller-supplied app language wins over the override (@client)
- **GIVEN** a client SDK that reports the user's language
- **AND** the app language is set to "de"
- **WHEN** capture is called with properties:
| property | value |
| $app_language | fr |
- **THEN** the event properties should include `$app_language` with value "fr"
Loading