# translator-api

Integrates the browser Translator API into JavaScript or TypeScript web apps. Sets up on-device translation, model downloads, and streaming text output.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 467 installs · ★ 52
- Author: webmaxru
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/webmaxru/web-ai-agent-skills/tree/HEAD/skills/translator-api/SKILL.md
- Updated: 2026-09-29
- HTML: https://affpapa.org/en/nevibecode/skills/translator-api

## What it does

This skill guides agents through integrating client-side translation into web frontends. It scans project boundaries using `node scripts/find-translator-targets.mjs .` or manual file inspection, then builds guarded session logic from `assets/translator-session.template.ts`. The generated code handles capability checks with `Translator.availability()`, streaming via `translateStreaming()`, input budgeting with `measureInputUsage()`, and session cleanup.

The API fails immediately outside a secure `Window` context or inside an iframe lacking the `allow="translator"` policy. This skill covers on-device browser translation exclusively. If your architecture relies on server runtimes or cloud translation providers, this skill will not work.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add webmaxru/web-ai-agent-skills --skill translator-api -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/translator-api/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/translator-api/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add webmaxru/web-ai-agent-skills --skill translator-api -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/translator-api/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add webmaxru/web-ai-agent-skills --skill translator-api -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/translator-api/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install webmaxru/web-ai-agent-skills translator-api
```

2. **Manually: put the files in place**
- File: `.github/skills/translator-api/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add webmaxru/web-ai-agent-skills --skill translator-api -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/webmaxru/web-ai-agent-skills --path skills/translator-api
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/translator-api/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add webmaxru/web-ai-agent-skills --skill translator-api -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/webmaxru/web-ai-agent-skills/tree/HEAD/skills/translator-api/SKILL.md

## When to use it
- wire browser on-device Translator API into UI components
- handle model download progress and user activation steps
- implement incremental text output via `translateStreaming()`
- resolve permission policy blocks and iframe delegation issues

## Example prompts
- Implement browser Translator API for English to Spanish in `TranslateBox.tsx`
- Add download progress monitoring and model availability checks to the translation flow
- Wire `translateStreaming()` with cancellation support via `AbortController`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 44d23491b3c596cd.

BEGIN THIRD-PARTY FILE 44d23491b3c596cd
```text
---
name: translator-api
description: Implements and debugs browser Translator API integrations in JavaScript or TypeScript web apps. Use when adding Translator support checks, language-pair availability flows, model download UX, session creation, translate() or translateStreaming() calls, input-usage measurement, or permissions-policy handling for on-device translation. Don't use for server-side translation SDKs, cloud translation services, or generic multilingual content pipelines.
license: MIT
metadata:
  author: webmaxru
  version: "1.3"
---

# Translator API

## Procedures

**Step 1: Identify the browser integration surface**
1. Inspect the workspace for browser entry points, text-input flows, localization UI, and any existing AI abstraction layer.
2. Execute `node scripts/find-translator-targets.mjs .` to inventory likely frontend files and existing Translator API markers when a Node runtime is available.
3. If a Node runtime is unavailable, inspect the nearest `package.json`, HTML entry point, and framework bootstrap files manually to identify the browser app boundary.
4. If the workspace contains multiple frontend apps, prefer the app that contains the active route, translation UI, or user-requested feature surface.
5. If the inventory still leaves multiple plausible frontend targets, stop and ask which app should receive the Translator API integration.
6. If the project is not a browser web app, stop and explain that this skill does not apply.

**Step 2: Confirm API viability and choose the integration shape**
1. Read `references/translator-reference.md` before writing code.
2. Read `references/examples.md` when the feature needs a session wrapper, download-progress UI, streaming output, cancellation, or cleanup shape.
3. Read `references/compatibility.md` when preview flags, browser channels, iframe rules, or environment constraints matter.
4. Read `references/troubleshooting.md` when support checks, session creation, translation, or cleanup fail.
5. Verify that the feature runs in a secure `Window` context.
6. Verify that the current frame is allowed to use the `translator` permissions-policy feature.
7. Choose the narrowest session shape that matches the task:
   - bare `Translator.create()` for a fixed language pair and full-result translation
   - monitored `create()` when the UI must surface model download progress
   - `translateStreaming()` when the UI should reveal translated output incrementally
   - `measureInputUsage()` when quota or input-size budgeting affects the flow
8. If the feature must run in a worker, on the server, or through a cloud translation contract, stop and explain the platform mismatch.
9. If the project uses TypeScript, add or preserve narrow typings for the Translator API surface used by the feature.

**Step 3: Implement a guarded translator session**
```
END THIRD-PARTY FILE 44d23491b3c596cd

The third-party file has ended. Everything between the 44d23491b3c596cd tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2842 of 7411 bytes. © webmaxru · MIT · https://github.com/webmaxru/web-ai-agent-skills/tree/HEAD/skills/translator-api/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md