# Translation

> Real-time translation of speech from the glasses microphone.

Source: https://docs.dev.glassly.ai/app-devs/core-concepts/translation/

`session.translation` turns spoken speech into translated text. Register a handler
for the language pair you care about and results start arriving; the SDK handles
the subscription for you.

```typescript
session.translation.to("es", (data) => {
  if (data.isFinal) {
    session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: data.text}]);
  }
});
```

Translation needs the `MICROPHONE` permission in your
[manifest](https://docs.dev.glassly.ai/app-devs/core-concepts/miniapp-manifest.md). Without it the phone drops
the subscription, no events arrive, and [`onPermissionError`](https://docs.dev.glassly.ai/app-devs/core-concepts/permissions.md#permission-errors) fires with
`PERMISSION_NOT_DECLARED`.

## Results

Each event is a `TranslationData`:

| Field | Type | Notes |
|---|---|---|
| `text` | `string` | The translated text so far. |
| `isFinal` | `boolean` | `false` for interim results that keep updating, `true` once the utterance is settled. |
| `sourceLanguage` | `string` | Language the speech was recognized in. |
| `targetLanguage` | `string` | Language `text` was translated into. |
| `originalText` | `string?` | Source-language text of the same utterance, when the provider supplies it. |
| `utteranceId` | `string?` | Stable id correlating interim and final results of one utterance. |
| `speakerId` | `string?` | Speaker id when the provider reports diarization. |

Interim results stream as the user speaks and get replaced; wait for `isFinal` if
you only want settled text. Use `utteranceId` to match an interim result to the
final one that supersedes it.

## Choosing what to listen for

Three methods select which translations reach your handler. They differ only in how
they pin the source and target language.

| Method | Listens for |
|---|---|
| `on(handler)` | Every translation event, any source, any target. |
| `to(target, handler)` | Any source, translated to `target`. Pass an array of targets to fan one handler across several. |
| `fromTo(source, target, handler)` | A specific `source` to `target` pair. Pass an array for `target` to fan one source across several targets. |

Each returns an unsubscribe function. `source` and `target` are language tags
(for example `"en"`, `"es"`).

```typescript
// Any language the user hears, translated to Spanish.
session.translation.to("es", handler);

// Several targets at once, one handler.
session.translation.to(["es", "fr"], handler);

// A specific direction: English speech to Spanish text.
session.translation.fromTo("en", "es", handler);

// One source fanned across multiple targets.
session.translation.fromTo("en", ["es", "fr"], handler);
```

`on()` is the broad case. It registers cheaply on your side but asks the cloud to
fan every active pair out to you, so reach for `to` or `fromTo` once you know the
language(s) you want.

When the provider supplies `originalText`, you can show the source and the
translation together:

```typescript
session.translation.to("es", (data) => {
  if (data.originalText) {
    session.display.render([
      {type: "text", id: "src", box: {x: 0, y: 0, w: 576, h: 144}, text: data.originalText},
      {type: "text", id: "msg", box: {x: 0, y: 144, w: 576, h: 144}, text: data.text},
    ]);
  } else {
    session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: data.text}]);
  }
});
```

## On-device translation

`on`, `to`, and `fromTo` take an optional final `{forceLocal: true}` to
translate on the phone only, never through the cloud:

```typescript
session.translation.to("es", handler, {forceLocal: true});
```

The source language is whatever the on-device transcriber is set to, and the
language pair must be downloaded in the Glassly App under **Settings → Offline
models**. On-device translation needs iOS 26 or later; other hosts deliver
nothing to a `forceLocal` listener. Without `forceLocal`, a listener still
receives on-device translations while the cloud is unavailable, if the pair is
downloaded.

`forLanguagePair(fromLang, toLang, handler)` is a deprecated alias for
`fromTo(source, target, handler)`. Use `fromTo` in new code; the alias will be
removed in a future release.

## Cleaning up

Every subscription returns an unsubscribe function. `stop()` tears down every
subscription this module owns at once:

```typescript
const off = session.translation.to("es", handler);
off();                      // drop this one

session.translation.stop(); // drop all of them
```

`session.translation.hasPermission` tells you whether `MICROPHONE` is declared in
your manifest. It does not tell you whether the user granted the OS prompt: if they
denied it, your handler never fires. See
[Permissions](https://docs.dev.glassly.ai/app-devs/core-concepts/permissions.md).

Translation gives you translated text. For the untranslated transcript in the
spoken language, use
[`session.transcription`](https://docs.dev.glassly.ai/app-devs/core-concepts/microphone/speech-to-text.md).
Subscribing to one does not subscribe you to the other.
