Quickstart for AdonisJS

Introduction

Lingo.dev Compiler is an AI-powered tool that enables you to localize React-based apps without making changes to existing components. You just configure a few things, wrap your app in a context provider, and that's it — your app is localized.

This guide explains how to set up Lingo.dev Compiler with AdonisJS, a full-featured Node.js web framework for building server-side applications.

Prerequisites

Your AdonisJS project is using Inertia.js.

What You'll Learn

How to initialize Lingo.dev Compiler in an AdonisJS project
How to configure the compiler for compatibility with AdonisJS
How to set up a locale switcher for switching between locales

Step 1. Set up 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 a supported provider.

To get up and running as quickly as possible, we recommend using Lingo.dev Engine — our own, hosted platform that offers 10,000 tokens of free, monthly usage.

To set up an API key:

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

Store the API key in an environment variable:

export LINGODOTDEV_API_KEY="<your_api_key>"

Alternative: Custom LLM Providers

You don't have to use Lingo.dev Engine. You can configure the compiler to integrate with a number of custom LLM providers, including:

Groq
Google
Mistral
Ollama
OpenRouter

Step 2. Install the Package

Lingo.dev Compiler is distributed as part of the lingo.dev npm package. To install it, use your preferred package manager:

npm install lingo.dev

Step 3. Initialize the Compiler

Lingo.dev Compiler integrates with Vite and runs at build time. To hook into Vite's build process, make the following changes to the vite.config.ts file:

Import the compiler:

import lingoCompiler from "lingo.dev/compiler";

Initialize the compiler with the vite method:

const withLingo = lingoCompiler.vite({
  sourceRoot: "inertia",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

For compatibility with AdonisJS, ensure that:

sourceRoot is set to "inertia"
rsc is set to false

To learn more about the available options, see Compiler Options.

Merge the compiler configuration with the existing configuration and export it:
```
export default withLingo(viteConfig);
```

With this configuration in place, Lingo.dev Compiler will:

Traverse the codebase's Abstract Syntax Tree (AST)
Find localizable content (i.e., text in JSX elements and certain attribute values)
Use the configured AI model(s) to generate translations
Store the original and translated content in a dictionary.js file
Replace localized content with placeholders

Step 4. Load the Localized Content

After the compiler processes your app and generates translations, you need to load and serve this localized content to your users. This involves:

Loading the appropriate dictionary based on the user's locale preference
Providing the loaded translations to your app through a context provider

Client-Side

In the inertia/app/app.tsx file:

Import the LingoProviderWrapper component and loadDictionary function from lingo.dev/react/client:
```
import {
  LingoProviderWrapper,
  loadDictionary,
} from "lingo.dev/react/client";
```
The LingoProviderWrapper component is a context provider that replaces the compiler-created placeholders with the localized content.

The loadDictionary function:
- Retrieves the current locale from the lingo-locale cookie
- Falls back to "en" when a locale isn't defined
- Loads the localized content from the dictionary.js file

Wrap the App component in the LingoProviderWrapper component and pass the loadDictionary function into it:

<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>

Server-Side

In the inertia/app/ssr.tsx file, repeat the same steps to avoid hydration mismatches:

import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>;

Step 5. Set up a Locale Switcher

To enable users to switch between locales, import the LocaleSwitcher from the lingo.dev package. This is an unstyled component that:

Renders a dropdown of available locales
Lets the user select their preferred locale
Remembers the user's locale for return visits

To use the component, embed it anywhere in your app and set the locales prop to an array that contains the configured source and target locales:

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

<LocaleSwitcher locales={["en", "es"]} />;

Alternative: Custom Locale Switcher

You don't have to use the LocaleSwitcher component. You can implement custom locale switching logic and UI. The only requirement is to read and write the active locale to the lingo-locale cookie.

Step 6. Run the App

To verify that Lingo.dev Compiler has been set up correctly:

Start the development server:
```
npm run dev
```
Navigate to localhost:3333.
Use the LocaleSwitcher component to switch between locales.

The page should reload and display the localized content.

Alternative: Set Cookies Manually

If you're not using the LocaleSwitcher component, an alternative way to verify that localization is working is by manually setting the lingo-locale cookie.

If you're using Google Chrome, follow these instructions:

Navigate to View > Developer > Developer Tools.
Go to the Application tab.
In the left sidebar, under Storage, expand Cookies and select the site’s URL.
In the cookies table, right-click anywhere and select Add.
In the Name column, enter lingo-locale.
In the Value column, enter the desired locale (e.g., es).
Press Enter to save the cookie.
Refresh the page to apply the cookie.