Quickstart with code

Add Linguana to an existing React app on Vite and confirm that its text is extracted. For other frameworks, use the matching adapter and runtime; for server rendering, use TanStack Start.

1. Install the packages

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

The public 0.1.0 packages ship TypeScript source. Add --configLoader runner to your Vite commands, preserving existing type checks:

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

2. Add the plugin before React

Merge this into your existing Vite configuration. Keep the other plugins your app uses.

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. Replace it with your dashboard project ID before uploading.

3. Wrap the application once

Use your existing App import and root element:

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>,
);

Text in components beneath the provider stays readable without a remote catalog. You do not need translation keys for static JSX.

4. Build and inspect the strings

bun run build

Open .linguana/manifest.json and find a visible string from your app. Run your app and confirm it still renders the source language. This build has not uploaded, translated, or published anything.

5. Connect your first language

Follow Connect hosted translations to create a project, replace the local identifier, upload a build, enable a language, translate it under a spending limit, and publish a catalog. Your runtime's project and environment must match the published release.