docs

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 or Next.js.

Starting from scratch instead? Create a working multilingual app from a template, with no account required:

terminal
npx @linguanahq/cli create app

See CLI and templates.

1. Install the packages

terminal
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:

package.json — merge with existing scripts
{
  "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.

vite.config.ts
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:

src/main.tsx
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

terminal
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.

To skip copying the project ID, API URL, and keys from the dashboard, run npx @linguanahq/cli link in the app. It signs you in through your browser, selects or creates the project, and writes the values into an ignored .env.local. See Connect an existing app.

Did this page get you to a working result?

On this page

No Headings