feat: expose window.__tolgee API for Playwright and console (#3499)

JanCizmar · web-flow · commit 0e4bf4622c9f · 2026-02-10T12:33:40.000+01:00
## Problem

When taking screenshots with Playwright, there is no way to
programmatically discover which translation keys are visible on screen
and where they are positioned. This makes it impossible to automatically
associate screenshots with translation keys in the Tolgee platform —
users have to manually tag each screenshot with the relevant keys.

## Solution

Exposes a `window.__tolgee` object (automatically set when
`InContextTools`/`DevTools` plugin is active) with methods to query
visible keys and their positions:

- `getVisibleKeys()` — returns all keys visible in the current viewport
with their bounding rects
- `highlight(keyName?, ns?)` — highlights matching DOM elements (returns
an unhighlight handle)
- `isRunning()` — checks if the tolgee observer is active

### Usage from Playwright

```js
const keys = await page.evaluate(() =&gt; window.__tolgee?.getVisibleKeys());
// → [{ keyName: "hello", keyNamespace: "", position: { x, y, width, height } }, ...]
```

## Test plan

- [x] Unit tests: 12 tests covering API setup, viewport filtering,
highlight handle, and cleanup on stop
- [x] Manual: verified on dev app via Playwright MCP —
`getVisibleKeys()` returns correct keys with positions, viewport
filtering works (9 keys full viewport → 6 keys with 400px viewport)


&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;

## Summary by CodeRabbit

* **Documentation**
* Added project conventions guide covering branch naming, pre-commit
checks, and commit/PR standards.

* **New Features**
* Introduced Window API exposing lightweight browser integration with
capabilities to retrieve visible translation keys, highlight specific
keys, and check running status.

* **Tests**
* Added comprehensive test coverage for Window API functionality across
multiple scenarios.

&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,18 @@
+# Project conventions
+
+## Branch naming
+
+Branches follow the pattern `jancizmar/<short-description>` (e.g., `jancizmar/window-tolgee-api`).
+
+## Before committing
+
+Always run these checks before creating a commit:
+
+1. **Prettier** — format changed files: `npx prettier --write <files>`
+2. **Unit tests** — run tests for the affected package, e.g.: `cd packages/web && npx jest --no-coverage`
+
+## Commits and PRs
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `chore:`, `refactor:`).
+- Do NOT add `Co-Authored-By` or any AI author attribution to commits.
+- PR descriptions must start with the user pain / problem being solved, then explain the solution.
diff --git a/packages/web/src/package/InContextTools.ts b/packages/web/src/package/InContextTools.ts
@@ -3,6 +3,7 @@ import { ContextUi } from './ContextUi';
 import { DevBackend } from './DevBackend';
 import { InContextOptions } from './types';
 import { ObserverPlugin } from './ObserverPlugin';
+import { setupWindowApi } from './WindowApi';
 
 export const InContextTools =
   (props?: InContextOptions): TolgeePlugin =>
@@ -18,5 +19,15 @@ export const InContextTools =
     if (credentials) {
       tolgee.overrideCredentials(credentials);
     }
+
+    let teardownWindowApi = setupWindowApi(tolgee);
+
+    tolgee.on('running', ({ value: isRunning }) => {
+      teardownWindowApi();
+      if (isRunning) {
+        teardownWindowApi = setupWindowApi(tolgee);
+      }
+    });
+
     return tolgee;
   };
diff --git a/packages/web/src/package/WindowApi.ts b/packages/web/src/package/WindowApi.ts
@@ -0,0 +1,40 @@
+import type { TolgeeInstance, KeyPosition, Highlighter } from '@tolgee/core';
+import { isSSR } from './tools/isSSR';
+
+export interface TolgeeWindowApi {
+  getVisibleKeys(): KeyPosition[];
+  highlight(keyName?: string, ns?: string): Highlighter;
+  isRunning(): boolean;
+}
+
+declare global {
+  interface Window {
+    __tolgee?: TolgeeWindowApi;
+  }
+}
+
+export function setupWindowApi(tolgee: TolgeeInstance): () => void {
+  if (isSSR()) {
+    return () => {};
+  }
+
+  window.__tolgee = {
+    getVisibleKeys() {
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      return tolgee.findPositions().filter(({ position: p }) => {
+        return p.x + p.width > 0 && p.y + p.height > 0 && p.x < vw && p.y < vh;
+      });
+    },
+    highlight(keyName?: string, ns?: string) {
+      return tolgee.highlight(keyName, ns);
+    },
+    isRunning() {
+      return tolgee.isRunning();
+    },
+  };
+
+  return () => {
+    delete window.__tolgee;
+  };
+}
diff --git a/packages/web/src/package/__test__/windowApi.test.ts b/packages/web/src/package/__test__/windowApi.test.ts
@@ -0,0 +1,173 @@
+import { TolgeeCore, TolgeeInstance } from '@tolgee/core';
+import { waitFor } from '@testing-library/dom';
+import { InContextTools } from '../InContextTools';
+import { setupWindowApi } from '../WindowApi';
+import { TOLGEE_ATTRIBUTE_NAME } from '../constants';
+
+(['invisible', 'text'] as const).forEach((observerType) => {
+  describe(`window.__tolgee API (${observerType})`, () => {
+    let tolgee: TolgeeInstance;
+
+    afterEach(() => {
+      tolgee.stop();
+      document.body.innerHTML = '';
+    });
+
+    it('is set when InContextTools is used', async () => {
+      tolgee = TolgeeCore()
+        .use(InContextTools())
+        .init({
+          language: 'en',
+          staticData: { en: { hello: 'world' } },
+          observerType,
+        });
+      await tolgee.run();
+      expect(window.__tolgee).toBeDefined();
+      expect(typeof window.__tolgee!.getVisibleKeys).toBe('function');
+      expect(typeof window.__tolgee!.highlight).toBe('function');
+      expect(typeof window.__tolgee!.isRunning).toBe('function');
+    });
+
+    it('isRunning() returns true when running', async () => {
+      tolgee = TolgeeCore()
+        .use(InContextTools())
+        .init({
+          language: 'en',
+          staticData: { en: { hello: 'world' } },
+          observerType,
+        });
+      await tolgee.run();
+      expect(window.__tolgee!.isRunning()).toBe(true);
+    });
+
+    it('getVisibleKeys() returns key positions for rendered translations', async () => {
+      tolgee = TolgeeCore()
+        .use(InContextTools())
+        .init({
+          language: 'en',
+          staticData: { en: { hello: 'world' } },
+          observerType,
+        });
+      await tolgee.run();
+
+      document.body.innerHTML = `
+        <span data-testid="translation">${tolgee.t({ key: 'hello' })}</span>
+      `;
+
+      await waitFor(() => {
+        expect(
+          document
+            .querySelector('[data-testid="translation"]')
+            ?.getAttribute(TOLGEE_ATTRIBUTE_NAME)
+        ).not.toBeFalsy();
+      });
+
+      // findPositions finds the key in the DOM (jsdom returns zero-size rects)
+      const allPositions = tolgee.findPositions();
+      expect(allPositions.length).toBeGreaterThan(0);
+      expect(allPositions[0]).toMatchObject({
+        keyName: 'hello',
+        keyNamespace: '',
+      });
+      expect(allPositions[0].position).toBeDefined();
+    });
+
+    it('highlight() returns an unhighlight handle', async () => {
+      tolgee = TolgeeCore()
+        .use(InContextTools())
+        .init({
+          language: 'en',
+          staticData: { en: { hello: 'world' } },
+          observerType,
+        });
+      await tolgee.run();
+
+      const result = window.__tolgee!.highlight('hello');
+      expect(result).toBeDefined();
+      expect(typeof result.unhighlight).toBe('function');
+      result.unhighlight();
+    });
+
+    it('getVisibleKeys() filters out keys outside the viewport', () => {
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+
+      const mockTolgee = {
+        findPositions: () => [
+          // visible: fully inside viewport
+          {
+            keyName: 'visible-key',
+            keyNamespace: '',
+            position: { x: 10, y: 10, width: 100, height: 20 },
+          },
+          // off-screen: below viewport
+          {
+            keyName: 'below-viewport',
+            keyNamespace: '',
+            position: { x: 10, y: vh + 10, width: 100, height: 20 },
+          },
+          // off-screen: to the right of viewport
+          {
+            keyName: 'right-of-viewport',
+            keyNamespace: '',
+            position: { x: vw + 10, y: 10, width: 100, height: 20 },
+          },
+          // off-screen: above viewport
+          {
+            keyName: 'above-viewport',
+            keyNamespace: '',
+            position: { x: 10, y: -100, width: 100, height: 20 },
+          },
+          // off-screen: to the left of viewport
+          {
+            keyName: 'left-of-viewport',
+            keyNamespace: '',
+            position: { x: -200, y: 10, width: 100, height: 20 },
+          },
+          // partially visible: overlapping bottom edge
+          {
+            keyName: 'partial-bottom',
+            keyNamespace: '',
+            position: { x: 10, y: vh - 10, width: 100, height: 30 },
+          },
+        ],
+        highlight: () => ({ unhighlight() {} }),
+        isRunning: () => true,
+      };
+
+      // setupWindowApi works with any object matching the TolgeeInstance shape
+      const teardown = setupWindowApi(mockTolgee as any);
+
+      // need to use a separate tolgee instance for afterEach cleanup
+      tolgee = TolgeeCore().init({ language: 'en' });
+
+      const keys = window.__tolgee!.getVisibleKeys();
+      const keyNames = keys.map((k) => k.keyName);
+
+      expect(keyNames).toContain('visible-key');
+      expect(keyNames).toContain('partial-bottom');
+      expect(keyNames).not.toContain('below-viewport');
+      expect(keyNames).not.toContain('right-of-viewport');
+      expect(keyNames).not.toContain('above-viewport');
+      expect(keyNames).not.toContain('left-of-viewport');
+      expect(keys).toHaveLength(2);
+
+      teardown();
+    });
+
+    it('is removed on tolgee.stop()', async () => {
+      tolgee = TolgeeCore()
+        .use(InContextTools())
+        .init({
+          language: 'en',
+          staticData: { en: { hello: 'world' } },
+          observerType,
+        });
+      await tolgee.run();
+      expect(window.__tolgee).toBeDefined();
+
+      tolgee.stop();
+      expect(window.__tolgee).toBeUndefined();
+    });
+  });
+});
