Vite integration API
Import linguana from @linguanahq/vite, then select exactly one framework adapter. The plugin extracts matching framework source and writes a version 3 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, andpre. - Allowed attributes:
title,placeholder,aria-label,alt,label, and buttonvalue. - Custom attributes require
data-translate. data-no-translate, hidden content, URLs, and machine attributes are excluded.- Default output is
.linguana/manifest.json.
Automatic translation context
Automatically extracted text and attributes include nearby static headings, associated labels, and supporting copy from the same section, form, or component usage. React, Solid, Vue, and Svelte use the same selection rules; Next.js uses the shared JSX compiler. Conditional branches, loop bodies, and nested sections remain isolated.
Each message carries up to six excerpts, at most 256 Unicode code points each and 2 KiB total. The complete translation prompt remains limited to 64 KiB. Hidden/excluded copy, dynamic values, handlers, comments, and arbitrary attribute values are excluded. There is no additional model call for context collection.
Generated IDs distinguish identical phrases used in different places. Editing a nearby heading keeps the message ID but invalidates its translation-memory match and refreshes live preview. Moving an element or renaming its module may change the ID. Explicit t() and <T> IDs and meaning notes keep their existing behavior.
Context in a different component implementation or runtime data still needs a meaning note or project context. When upgrading, rebuild and translate the new generated IDs before publishing the matching app and catalog together. Existing published catalogs remain readable.
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 · Migrate from the compiler package · Automate translations in CI
Reference the multi-framework Vite plugin, adapters, strict policy, defaults, and failure behavior.
Last updated November 17, 2026
Did this page get you to a working result?