---
title: "Vite integration API"
description: "Reference the multi-framework Vite plugin, adapters, strict policy, defaults, and failure behavior."
canonical_url: "https://docs.linguana.dev/docs/reference/compiler"
markdown_url: "https://docs.linguana.dev/docs/reference/compiler.md"
x_farming_labs_generated_preamble: true
---

# Vite integration API
URL: /docs/reference/compiler
LLM index: /llms.txt
Description: Reference the multi-framework Vite plugin, adapters, strict policy, defaults, and failure behavior.

# Vite integration API

Import `linguana` from `@linguanahq/vite`, then select exactly one framework adapter. The plugin extracts matching framework source and writes a version 2 manifest without changing source files.

## `linguana(options)`

```ts
import { linguana, type LinguanaViteOptions } from "@linguanahq/vite";
import { react } from "@linguanahq/vite/react";
```

<ConfigReference>

| Option | Type | Required | Default | Example | Exposure | Failure behavior |
| --- | --- | --- | --- | --- | --- | --- |
| `adapter` | `react() | vue() | svelte() | solid()` | Yes | - | `react()` | Build config | Missing or misplaced adapters fail with setup guidance |
| `projectId` | `string` | Yes | - | `"checkout"` | Public identity | Missing value is a TypeScript/config error |
| `environment` | `string` | No | `"development"` | `"development"` | Public identity | Translation rejects non-development values |
| `sourceLocale` | `string` | No | `"en"` | `"en"` | Public | Used for stable IDs and source fallback |
| `apiUrl` | `string` | Remote work | - | `process.env.LINGUANA_API_URL` | Server/build config | Upload or translation fails when absent |
| `token` | `string` | Remote work | - | `process.env.LINGUANA_PROJECT_TOKEN` | Secret | Upload or translation fails when absent/invalid |
| `include` | `string | string[]` | No | JSX and TSX | `"src/**/*.tsx"` | Build config | Nonmatching files are ignored |
| `exclude` | `string | string[]` | No | Dependencies/tests/specs | `"**/*.stories.tsx"` | Build config | Matching files are ignored |
| `output` | `string` | No | `.linguana/manifest.json` | `"artifacts/messages.json"` | Build config | Parent directory is created automatically |
| `upload` | `boolean` | No | `Boolean(token)` | `true` | Build config | Requires `token` |
| `strict` | `StrictPolicy` | No | `false` | `{ duplicate: true }` | Build policy | Selected diagnostics fail the build |
| `translation` | `object` | No | - | See below | Paid build policy | Waits, fails safely, publishes development only |

</ConfigReference>

## Translation options

```ts
translation: {
  enabled: true,
  maxChargeMicros: 100_000,
  waitTimeoutMs: 300_000,
  publish: "development",
}
```

Target languages come from the project’s enabled Languages list in the dashboard. `maxChargeMicros` and an optional `waitTimeoutMs` must be positive safe integers. `publish` accepts only `development`.

The compiler derives one idempotent build intent from manifest hash, sorted target locales, and publish target. It polls jobs until success, review/failure/cancellation, dispatch failure, or timeout. Every successful target must provide a catalog version before the development release is created.

## `StrictPolicy`

```ts
type StrictPolicy =
  | boolean
  | { ambiguous?: boolean; unsafe?: boolean; duplicate?: boolean };
```

`true` fails on every non-info diagnostic. Object policy defaults incompatible duplicate IDs to fatal while allowing you to promote ambiguous or unsafe categories independently.

## Framework adapters

React and Solid transform JSX before their official compiler plugins. Vue transforms the template block through the SFC compiler AST. Svelte transforms source before the official preprocess/compile plugins. Place `linguana()` before the official framework plugin.

## Defaults and extraction boundaries

- Excluded elements: `script`, `style`, `code`, and `pre`.
- Allowed attributes: `title`, `placeholder`, `aria-label`, `alt`, `label`, and button `value`.
- Custom attributes require `data-translate`.
- `data-no-translate`, hidden content, URLs, and machine attributes are excluded.
- Default output is `.linguana/manifest.json`.

## Common failures

| Message or code | Meaning | Recovery |
| --- | --- | --- |
| `Manifest upload requires apiUrl and token` | Remote work is enabled without both credentials | Supply both in the build or disable remote work |
| `duplicate-id` | One explicit ID maps to incompatible source | Give each semantic message a distinct ID |
| `TRANSLATION_BUILD_TIMEOUT` | Durable work exceeded the build wait | Inspect the listed jobs before retrying the same intent |
| `INNGEST_DISPATCH_FAILED` | The workflow worker was unreachable | Start/reconnect the worker and inspect the job ID |
| `REVIEW_REQUIRED` | A candidate needs human evidence | Resolve it in Review rather than publishing around it |

## See also

[Choose a framework](/docs/getting-started/frameworks) · [Migrate from the compiler package](/docs/advanced/migrate-compiler) · [Automate translations in CI](/docs/automate/ci-cd)

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).