feat(i18n): report the interface language to PostHog

apps/web/AGENTS.md

@@ -344,6 +344,8 @@ the user's newest account for that app from the last fifteen minutes.
   with `t()` from `@app/lib/i18n`, adding only the English to
   `src/lib/i18n/locales/en/`. The periodic `update-translations` skill fills
   in the other languages. See the [i18n rule](../../.agents/rules/web/i18n.md).
+  The resolved interface language is reported to PostHog as the person
+  property `interface_language` when the account language loads.
 - When adding or changing a feature flag, follow the `feature-flags` skill.
 - When adding or changing a view's feature tour, follow the `add-tour` skill.
 

apps/web/src/lib/analytics/analytics.test.ts

@@ -11,6 +11,7 @@ const mocks = vi.hoisted(() => ({
   groups: {} as Record<string, string>,
   unregister: vi.fn(),
   reset: vi.fn(),
+  setPersonProperties: vi.fn(),
   gtag: vi.fn(),
   fbq: vi.fn(),
 }));
@@ -36,6 +37,7 @@ vi.mock('posthog-js', () => ({
     getGroups = () => mocks.groups;
     unregister = mocks.unregister;
     reset = mocks.reset;
+    setPersonProperties = mocks.setPersonProperties;
   },
 }));
 
@@ -253,6 +255,32 @@ describe('PostHog exception frames', () => {
   });
 });
 
+describe('interface language', () => {
+  it('records the language once, and again when it changes', async () => {
+    const { analytics } = await import('./analytics');
+
+    analytics.setInterfaceLanguage('de');
+    analytics.setInterfaceLanguage('de');
+    analytics.setInterfaceLanguage('ja');
+
+    expect(mocks.setPersonProperties.mock.calls).toEqual([
+      [{ interface_language: 'de' }],
+      [{ interface_language: 'ja' }],
+    ]);
+  });
+
+  it('records the same language again after logout resets PostHog', async () => {
+    const { analytics } = await import('./analytics');
+
+    analytics.setInterfaceLanguage('de');
+    analytics.reset();
+    analytics.setInterfaceLanguage('de');
+
+    expect(mocks.reset).toHaveBeenCalledTimes(1);
+    expect(mocks.setPersonProperties).toHaveBeenCalledTimes(2);
+  });
+});
+
 describe('PostHog team group', () => {
   const team = {
     id: '00000000-0000-0000-0000-000000000001',

apps/web/src/lib/analytics/analytics.ts

@@ -16,6 +16,7 @@ import {
   redactLinkTokens,
 } from '@core/util/telemetryUrl';
 import { getWebOrigin } from '@core/util/webOrigin';
+import type { Language } from '@service-auth/generated/schemas/language';
 import type { Team } from '@service-auth/generated/schemas/team';
 import { type CaptureOptions, PostHog } from 'posthog-js';
 import { match } from 'ts-pattern';
@@ -37,6 +38,12 @@ const DEVICE_PROPERTY = 'macro_device' as const;
 const ENVIRONMENT_PROPERTY = 'macro_environment' as const;
 const PLAN_TIER_AT_EVENT_PROPERTY = 'plan_tier_at_event' as const;
 const HAS_PAID_ACCESS_AT_EVENT_PROPERTY = 'has_paid_access_at_event' as const;
+/**
+ * The interface language being shown, as a BCP 47 tag (`en`, `zh-Hans`):
+ * the person's choice, else the team's, else the browser's, else English.
+ * A person property, so a breakdown uses the current language.
+ */
+const INTERFACE_LANGUAGE_PROPERTY = 'interface_language' as const;
 /** PostHog group type for team analytics; server events send the same key. */
 const TEAM_GROUP_TYPE = 'team' as const;
 
@@ -355,6 +362,21 @@ const createAnalytics = () => {
     }
   };
 
+  // Person properties are per PostHog identity. Forget the last value on
+  // reset so the next account is recorded even when the tag matches.
+  let reportedInterfaceLanguage: Language | undefined;
+
+  const setInterfaceLanguage = (language: Language) => {
+    if (disabled || reportedInterfaceLanguage === language) return;
+
+    try {
+      posthog.setPersonProperties({ [INTERFACE_LANGUAGE_PROPERTY]: language });
+      reportedInterfaceLanguage = language;
+    } catch (e) {
+      console.error('[Analytics] Failed to set interface language:', e);
+    }
+  };
+
   // `group` with properties captures a `$groupidentify` event, so only send
   // it when the team or its properties change, not on every team refetch.
   let syncedTeamGroupKey: string | undefined;
@@ -401,6 +423,7 @@ const createAnalytics = () => {
 
       posthog.unregister(PLAN_TIER_AT_EVENT_PROPERTY);
       posthog.unregister(HAS_PAID_ACCESS_AT_EVENT_PROPERTY);
+      reportedInterfaceLanguage = undefined;
       posthog.reset();
     } catch (e) {
       console.error('[Analytics] Failed to reset:', e);
@@ -455,6 +478,7 @@ const createAnalytics = () => {
     trackGoogleConversion,
     identify,
     setPlanProperties,
+    setInterfaceLanguage,
     setTeamGroup,
     clearTeamGroup,
     reset,
@@ -476,6 +500,8 @@ export type AnalyticsInterface = {
   ) => void;
   identify: (userID: string, info: Partial<UserIdentifyInfo>) => void;
   setPlanProperties: (licenseStatus: string | undefined) => void;
+  /** Records the interface language currently shown, for usage breakdowns. */
+  setInterfaceLanguage: (language: Language) => void;
   /** Associates this user's events with their team (PostHog group analytics). */
   setTeamGroup: (team: TeamGroupInfo) => void;
   /** Detaches events from any team, e.g. after leaving it. */

apps/web/src/lib/i18n/use-interface-language-sync.ts

@@ -1,3 +1,4 @@
+import { useAnalytics } from '@app/lib/analytics/analytics-context';
 import { useUserLanguageQuery } from '@queries/auth/user-language';
 import { queryReadyGate } from '@queries/gate';
 import { useCurrentTeamQuery } from '@queries/team/teams';
@@ -11,6 +12,7 @@ import { resolveInterfaceLanguage } from './languages';
  * settings have loaded the language remembered on this device stays in place.
  */
 export function useInterfaceLanguageSync() {
+  const analytics = useAnalytics();
   const userLanguage = useUserLanguageQuery();
   const team = useCurrentTeamQuery();
 
@@ -23,12 +25,12 @@ export function useInterfaceLanguageSync() {
       (!team.isError || userLanguage.data.language === null)
     )
       return;
-    setInterfaceLanguage(
-      resolveInterfaceLanguage(
-        userLanguage.data.language,
-        queryReadyGate(team) ? team.data?.team.language : undefined,
-        browserInterfaceLanguage
-      )
+    const language = resolveInterfaceLanguage(
+      userLanguage.data.language,
+      queryReadyGate(team) ? team.data?.team.language : undefined,
+      browserInterfaceLanguage
     );
+    setInterfaceLanguage(language);
+    analytics.setInterfaceLanguage(language);
   });
 }

crates/user_language/AGENTS.md

@@ -18,7 +18,8 @@ else the team's, else the browser's when offered, else English.
 
 - Owns: the `"User".language` column.
 - Not here: the team default → `crates/teams` (`PatchTeamRequest.language`);
-  translations and language resolution → `apps/web/src/lib/i18n`.
+  translations and language resolution → `apps/web/src/lib/i18n`. The web app
+  reports the resolved language to PostHog as `interface_language`.
 
 ## Recipes
 

docs/agent-guide/settings.md

@@ -360,7 +360,11 @@ only; without a team it is the only dropdown. A browser language the app isn't
 offered in falls back to English. Menus, navigation, the command and
 create menus, and settings navigation switch language as soon as the setting
 saves; page contents and user data stay as written. The choice is remembered on
-the device, so the next launch starts in the same language.
+the device, so the next launch starts in the same language. Once that resolved
+language has loaded, PostHog stores it on the person as `interface_language`
+(a tag such as `en` or `zh-Hans`). A usage pie is a Trends insight on
+`$pageview`, unique users, broken down by the person property
+`interface_language`.
 
 Existing settings URLs remain valid; `connections` still opens Integrations,
 `agent-connections` aliases Integrations, and `harness` aliases Runtimes.