Install Linguana

Install Linguana, connect it to your build, and extract your first messages. Local setup works without an account or token.

Requirements

Use an existing Vite application and its framework plugin. The published 0.1.0 packages support:

The shared plugin supports Vite >=7 <9. Use a Node.js version supported by your Vite release. Keep the Linguana runtime and Vite plugin on matching release versions and commit your package manager's lockfile.

1. Install your framework's packages

Choose one framework. These commands assume its framework and official Vite plugin are already installed.

bun add @linguanahq/react @linguanahq/catalog
bun add --dev @linguanahq/vite

bun add @linguanahq/vue @linguanahq/catalog
bun add --dev @linguanahq/vite @vue/compiler-dom @vue/compiler-sfc

bun add @linguanahq/svelte @linguanahq/catalog
bun add --dev @linguanahq/vite

bun add @linguanahq/solid @linguanahq/catalog
bun add --dev @linguanahq/vite

@linguanahq/vite/react and the other adapter paths are imports from @linguanahq/vite, not separate packages to install. @linguanahq/catalog is needed directly when you import createCatalog. The core, compiler, and build-core packages are installed transitively for normal framework integrations.

2. Configure the config loader

The 0.1.0 packages publish TypeScript source. When running Vite with Node.js, use its module runner to load the config and SDK imports:

{
  "scripts": {
    "dev": "vite --configLoader runner",
    "build": "vite build --configLoader runner",
    "preview": "vite preview --configLoader runner"
  }
}

Preserve any existing type-check step in your build script and append --configLoader runner to its Vite command. This also works when invoking the scripts through bun run; installing with Bun alone does not force Vite to run under Bun.

If you see ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING, check this setting before changing application code.

3. Add the build plugin

The example below uses React. For Vue, Svelte, or Solid, use the framework-specific plugin and runtime, then return to step 5. For server-rendered React, follow TanStack Start.

Add the Linguana plugin before the React plugin:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { linguana } from "@linguanahq/vite";
import { react as linguanaReact } from "@linguanahq/vite/react";

export default defineConfig({
  plugins: [
    linguana({
      adapter: linguanaReact(),
      projectId: "my-app",
      environment: "development",
      sourceLocale: "en",
      upload: false,
    }),
    react(),
  ],
});

my-app is a local identifier for this extraction-only example. Replace it consistently in the plugin and runtime with your real project ID before connecting to the API. See framework setup for Vue, Svelte, and Solid, or TanStack Start for SSR.

4. Add the runtime

The transformed application needs its framework runtime. For React, wrap the app once:

import { createRoot } from "react-dom/client";
import { LocaleProvider } from "@linguanahq/react";
import { App } from "./app";

createRoot(document.getElementById("root")!).render(
  <LocaleProvider
    projectId="my-app"
    environment="development"
    initialLocale="en"
    fallbackLocale="en"
  >
    <App />
  </LocaleProvider>,
);

Use your application's existing App import and root element. The compiler keeps source text as fallback, so you can check extraction before any translations exist. For explicit catalogs and locale switching, continue with Show translated content.

5. Build your app

bun run build

Confirm .linguana/manifest.json contains messages from your application, run your app, and check that its source-language text still renders. No upload occurs with upload: false.

Next

Your app now extracts text and renders its original language. Continue with Connect hosted translations to upload text and publish your first language.

For text with variables or links, see Dynamic text and links. If the build fails, see Build diagnostics.