"use i18n";

The "use i18n" directive enables file-by-file localization of React components without refactoring your existing code. Just like "use client" or "use server", you simply add it at the top of your file to automatically localize all translatable content in that component.

This approach is perfect for gradually adding multilingual support to large codebases with minimal risk and maximum flexibility.

How It Works

When you add "use i18n" to the top of a React file, Lingo.dev Compiler automatically:

  1. Scans the entire file for translatable content
  2. Extracts JSX text and translatable attributes
  3. Generates translations using your configured AI model
  4. Injects localized versions at build time
  5. Maintains Hot Module Replacement for seamless development

The directive works at the file level, processing everything within that component's boundaries while leaving the rest of your app unchanged.

Enable the Directive

To use the "use i18n" directive, enable it in your compiler configuration:

{
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  useDirective: true, // Enable "use i18n" directive
  models: "lingo.dev", // Option 1: Lingo.dev Engine
  // models: {
  //   "*:*": "groq:mistral-saba-24b", // Option 2: GROQ
  // }
}

Note: When useDirective is set to false (the default), Lingo.dev Compiler processes all files as if they had "use i18n" at the top. Setting useDirective: true gives you granular control to localize files individually.

Model Configuration: You can use either Lingo.dev Engine with simplified syntax (models: "lingo.dev") or GROQ models with specific model mapping (models: { "*:*": "groq:mistral-saba-24b" }). The Engine automatically selects optimal models for each language pair.

Basic Usage

Add the directive at the top of any React component file:

"use i18n";

import React from "react";

export function WelcomeCard() {
  return (
    <div className="card">
      <h2>Welcome to our app!</h2>
      <p>
        Get started by exploring our features and discovering what makes our
        platform special.
      </p>
      <button>Get Started</button>
    </div>
  );
}

That's it! The component will now automatically render in the user's selected language without any code changes.

Works with Existing Directives

The "use i18n" directive naturally works alongside other React directives you might already have:

"use client";
"use i18n";

export function InteractiveComponent() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1>Click Counter</h1>
      <p>You've clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}>Click me!</button>
    </div>
  );
}

"use server";
"use i18n";

export async function ServerComponent() {
  const data = await fetchData();

  return (
    <div>
      <h1>Server-rendered Content</h1>
      <p>This content is rendered on the server and localized at build time</p>
    </div>
  );
}

The compiler intelligently processes all directives together, maintaining the intended behavior of your components while adding localization.

Development Workflow

1. Gradual Migration

Start by adding the directive to individual components:

// Before: English-only component
export function Header() {
  return <h1>My Application</h1>;
}

// After: Multilingual component with one line
("use i18n");

export function Header() {
  return <h1>My Application</h1>;
}

2. Hot Module Replacement

The directive works seamlessly with HMR. When you modify text in a component with "use i18n", translations update immediately in your browser:

"use i18n";

export function StatusMessage() {
  return (
    <div>
      {/* Change this text and see it update in all languages instantly */}
      <p>Your changes have been saved successfully!</p>
    </div>
  );
}

3. File-by-File Approach

Perfect for large codebases where you want to localize incrementally:

src/
├── components/
│   ├── Header.tsx          // ✅ "use i18n" - localized
│   ├── Navigation.tsx      // ✅ "use i18n" - localized
│   ├── ProductCard.tsx     // ✅ "use i18n" - localized
│   ├── Footer.tsx          // ⏳ Not yet localized
│   └── Sidebar.tsx         // ⏳ Not yet localized

Benefits

The "use i18n" directive makes localization as simple as adding a single line to your React components, and is designed for matures projects that require gradual localization.

Next Steps