Bolt

Bolt is an AI-powered, browser-based development platform from StackBlitz. This guide explains how to localize a React-based app with Lingo.dev Compiler in Bolt.

Known limitations

Bolt uses web containers to run web apps within the browser. This is a powerful technology, but it does have some compatibility issues with Lingo.dev:

  • You can only use an API key to authenticate with Lingo.dev Engine, not the login command of the CLI.
  • In Bolt, Lingo.dev Compiler is only compatible with Vite-based apps. You can't use Next.js.
  • The <LocaleSwitcher /> component doesn't work within Bolt's embedded Preview window.
  • Ollama is not supported in Bolt as Ollama needs to be run locally.

Step 1. Get an API Key

Lingo.dev Compiler uses large language models (LLMs) to localize apps with AI. To use one of these models, you need an API key from one of the supported providers. You can use Lingo.dev Engine or a custom LLM provider.

Lingo.dev Engine

Lingo.dev Engine is our own, hosted platform that provides dynamic model selection, auto-routing, translation memory, and glossary support. Registration is free and all users get 10,000 tokens per month of free usage.

To get an API key:

  1. Log in to Lingo.dev Engine.
  2. Navigate to the Projects page.
  3. Click API key > Copy.

Custom LLM Provider

Lingo.dev Compiler also integrates with a range of third-party providers, including:

The exact instructions for setting up an API key depend on the provider.

Note: Make sure to activate your account with LLM provider and accept their Terms of service before using it in Compiler.

Step 2. Install lingo.dev

The lingo.dev package contains the compiler.

To install the package:

  1. Create or open a project in Bolt.

  2. Switch to the Code tab.

  3. Click Terminal.

  4. Run the following command:

    npm install lingo.dev

Step 3. Configure Vite

When using Vite, Lingo.dev Compiler must be initialized in the project's configuration file:

  • If you're using TypeScript, the configuration file is vite.config.ts.
  • If you're using JavaScript, the configuration file is vite.config.js.

You can configure the behavior of the compiler during initilization. It's this configuration that determines the locales to translate between and the model(s) to use for localization.

For the complete list of available options, see Compiler Options.

Lingo.dev Engine

If you're using Lingo.dev Engine, set models to "lingo.dev":

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import lingoCompiler from "lingo.dev/compiler";

const viteConfig = {
  plugins: [react()],
};

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    lingoDir: "lingo",
    sourceLocale: "en",
    targetLocales: ["es"],
    rsc: false,
    useDirective: false,
    debug: false,
    models: "lingo.dev",
  })(viteConfig),
);

Custom LLM Provider

If you're using a custom LLM provider, set models to an object that maps source and target locales with the models that should localize them. For example, this configuration localizes all strings with "groq:mistral-saba-24b":

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import lingoCompiler from "lingo.dev/compiler";

const viteConfig = {
  plugins: [react()],
};

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    lingoDir: "lingo",
    sourceLocale: "en",
    targetLocales: ["es"],
    rsc: false,
    useDirective: false,
    debug: false,
    models: {
      "*:*": "groq:mistral-saba-24b",
    },
  })(viteConfig),
);

Step 4. Set an Environment Variable

To ensure that Lingo.dev Compiler can access the API keys for the configured models, the API keys need to be available as environment variables.

To set up the environment variables in Bolt:

  1. Create a .env file.

    1. Right-click the file pane.
    2. Select New file.
    3. Enter .env.

  2. Add the relevant environment variables to the file:

    # Lingo.dev Engine
LINGODOTDEV_API_KEY="YOUR_API_KEY_GOES_HERE"

# Google AI
GOOGLE_API_KEY="YOUR_API_KEY_GOES_HERE"

# GROQ
GROQ_API_KEY="YOUR_API_KEY_GOES_HERE"

# Mistral
MISTRAL_API_KEY="YOUR_API_KEY_GOES_HERE"

# OpenRouter
OPENROUTER_API_KEY="YOUR_API_KEY_GOES_HERE"

Note: Bolt automatically encrypts environment variables. To learn more, see Environment Variables (developer.stackblitz.com).

Step 4. Add Provider

The lingo.dev package exports a <LingoProviderWrapper /> component. This component is responsible for loading translations and making them available throughout the app.

To use the component, import it into the src/main.tsx file and wrap it around the <App /> component:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
      <App />
    </LingoProviderWrapper>
  </React.StrictMode>,
);

(Optional) Step 5. Add Locale Switcher

The lingo.dev package exports an unstyled <LocaleSwitcher /> component. This component renders a dropdown that allows users to set their preferred language and remembers that selection on return visits.

To use the component, include it as a descendent of the <LingoProviderWrapper /> component and set the locales prop to an array that contains the source and target locales:

import { LocaleSwitcher } from "lingo.dev/react/client";

function App() {
  return (
    <div className="App">
      <header>
        <LocaleSwitcher locales={["en", "es"]} />
      </header>
      <main>
        <h1>Welcome to your app</h1>
        <p>This content is automatically translated</p>
      </main>
    </div>
  );
}

export default App;

Warning: The <LocaleSwitcher /> component does not work in Bolt's embedded Preview window. To see the component in action, click the Open preview in a separate tab icon.

Step 6. Build and Test

If the development server is not already running, start it with the following command:

npm run dev

The compiler will automatically:

  1. Scan your React components for translatable content
  2. Extract translation keys
  3. Generate AI-powered translations
  4. Create optimized translation files in the lingo/ directory

Next Steps