translator-api

What this skill does

# 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**
1. Read `assets/translator-session.template.ts` and adapt it to the framework, state model, and file layout in the workspace.
2. Centralize support checks around `globalThis.isSecureContext`, `Translator`, and the same `sourceLanguage` and `targetLanguage` shape the feature will use at runtime.
3. Gate session creation behind `Translator.availability()` using the same language pair that will be passed to `Translator.create()`.
4. Treat `availability()` as a capability check, not a guarantee that creation will succeed without download time, policy approval, or user activation.
5. Create sessions only after user activation when creation may trigger a model download.
6. Use the `monitor` option during `create()` when the product needs download progress.
7. Use `AbortController` for cancelable `create()`, `translate()`, `translateStreaming()`, or `measureInputUsage()` calls, and call `destroy()` when the session is no longer needed.
8. Recreate the session instead of mutating `sourceLanguage` or `targetLanguage` after creation; session options are fixed per instance.
9. If the feature lives in a cross-origin iframe, require explicit delegation through `allow="translator"`.

**Step 4: Wire UX and fallback behavior**
1. Surface distinct states for missing APIs, insecure contexts, blocked frames, unsupported language pairs, downloadable or downloading models, ready sessions, in-flight translation, and aborted work.
2. Keep a non-AI fallback for unsupported browsers, blocked frames, or environments that do not meet current preview requirements.
3. Preserve the source and target language pair explicitly in product state instead of inferring them from translated output.
4. Use `translate()` when downstream logic needs the full result before continuing, and use `translateStreaming()` when the UI should reveal translated text incrementally.
5. Use `measureInputUsage()` when large inputs can exceed session quota.
6. Treat same-language or best-fit identity translations as valid outcomes instead of forcing a fallback when the translated result matches the input.
7. Chunk or queue long-running product workflows deliberately; translation requests are not a substitute for general summarization, writing, or chat tasks.
8. Do not route generic cloud translation, document localization pipelines, or server-side batch translation through this API; switch to the approved service or runtime when the task is not browser on-device translation.

**Step 5: Validate behavior**
1. Execute `node scripts/find-translator-targets.mjs .` to confirm that the intended app boundary and Translator API markers still resolve to the edited integration surface.
2. Verify secure-context checks, `Translator` feature detection, and `availability()` behavior before debugging deeper runtime failures.
3. Test at least one `create()` plus `translate()` flow with representative user text for the target language pair.
4. If the feature exposes streaming, test `translateStreaming()` separately and confirm partial output stops cleanly on abort.
5. If the feature depends on quota budgeting, verify `measureInputUsage()` behavior before sending large input.
6. Confirm that cancellation rejects with the expected abort reason and that destroyed sessions are not reused.
7. If the target environment depends on preview browser flags or channel-specific behavior, confirm the required browser state from `references/compatibility.md` before treating failures as application bugs.
8. Run the workspace build, typecheck, or tests after editing.

## Error Handling
* If `Translator` is missing, keep a non-AI fallback and confirm secure-context, browser, channel, and flag requirements before changing product logic.
* If `availability()` returns `downloadable` or `downloading`, require user-driven session creation before promising that translation is ready.
* If `create()` throws `NotAllowedError`, check permissions-policy constraints, missing user activation for downloads, browser policy restrictions, or user rejection.
* If `create()` throws `OperationError`, treat model initialization as failed and retry only after checking browser state, required flags, and download readiness.
* If a translation call throws `QuotaExceededError`, reduce the input size or measure usage before retrying.
* If a translation call throws `NotReadableError` or `UnknownError`, surface a visible fallback instead of retrying blindly with the same input.
* If the feature must run in a worker or server context, stop and explain that the Translator API is a window-only browser API.