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)`

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

Option	Type	Required	Default	Example	Exposure	Failure behavior
`adapter`	`react()	vue()	svelte()	solid()`	Yes	-
`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
`exclude`	`string	string[]`	No	Dependencies/tests/specs	`"*/.stories.tsx"`	Build config
`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

Translation options

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`

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