Connect hosted translations

Start here after installation. You should already have a working build and a .linguana/manifest.json containing your app's text.

1. Create a project

Open Projects in the Linguana dashboard and choose New project. Create an organization first if you do not have one. The dashboard currently creates projects with English (en) as the source language.

Copy the project ID and replace the local my-app identifier in both your build plugin and runtime. This guide uses production in both places so the dashboard’s production publish action serves a catalog built for the same environment. Uploading a production build does not publish it. See Create a project for permissions and project settings.

In Tokens, create a production project token and copy it when shown. Obtain your API URL and browser publishable key from Integrations. The project token authenticates builds; the publishable key loads catalogs in the browser. The Integrations templates use VITE_LINGUANA_API and VITE_LINGUANA_KEY; this guide names those values VITE_LINGUANA_API_URL and VITE_LINGUANA_PUBLISHABLE_KEY. Match the names you store to the names your runtime reads.

2. Upload your text

LINGUANA_API_URL=https://your-linguana-api.example.com
LINGUANA_PROJECT_TOKEN=your-project-token
LINGUANA_UPLOAD=false
VITE_LINGUANA_API_URL=https://your-linguana-api.example.com
VITE_LINGUANA_PUBLISHABLE_KEY=your-publishable-key

Vite does not automatically populate process.env from .env.local while evaluating its config. Load those values explicitly when configuring authenticated builds:

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

export default defineConfig(({ mode }) => {
  const env = { ...loadEnv(mode, process.cwd(), ""), ...process.env };
  return {
    plugins: [
      linguana({
        adapter: linguanaReact(),
        projectId: "your-project-id",
        environment: "production",
        sourceLocale: "en",
        apiUrl: env.LINGUANA_API_URL,
        token: env.LINGUANA_PROJECT_TOKEN,
        upload: env.LINGUANA_UPLOAD === "true",
      }),
      react(),
    ],
  };
});

Reading unprefixed values here keeps them in the build process. Do not forward the entire environment through Vite's define or envPrefix options.

Set LINGUANA_UPLOAD=true in .env.local, then run your build:

npm run build

Confirm the new build appears in the dashboard. For Vue, Svelte, or Solid, keep the adapter and framework plugin from your installation and add the same environment options.

3. Translate and publish

1. In Languages, enable a target language such as French.
2. In Jobs, choose Translate latest build, review the estimate, and start the run for the uploaded production build.
3. Inspect the wording in Strings and resolve pending decisions in Review.
4. In Releases, inspect the ready catalog, choose Publish ready catalog, and confirm production.

Uploading text does not translate or publish it. For a separate development workflow with optional build-triggered publishing, use a development token and matching build/runtime environment; see CI/CD. Production publishing remains an explicit release action.

4. Load the published language

For React, update your existing provider and add a language selector:

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

createRoot(document.getElementById("root")!).render(
  <LocaleProvider
    projectId="your-project-id"
    environment="production"
    initialLocale="en"
    fallbackLocale="en"
    catalogEndpoint={import.meta.env.VITE_LINGUANA_API_URL}
    publishableKey={import.meta.env.VITE_LINGUANA_PUBLISHABLE_KEY}
    availableLocales={[
      { code: "en", displayName: "English", nativeName: "English" },
      { code: "fr", displayName: "French", nativeName: "Français" },
    ]}
  >
    <LanguageSelector />
    <App />
  </LocaleProvider>,
);

Use your existing App import and root element. For other frameworks, pass catalogEndpoint and publishableKey to the matching runtime. Server-rendered apps should use the TanStack Start guide to keep the initial language consistent.

Restart the app after changing environment values and select French. Text included in your published catalog should now appear in French; missing translations fall back to the original text.

If the language does not load, check that the project and environment match the published catalog, then follow Catalog runtime troubleshooting.

Next

Use Dynamic text and links for variables and rich text, or Show translated content for embedded catalogs and custom language switching.