Manual Overrides

Override AI-generated translations for specific text using the data-lingo-override attribute.

Basic Usage

<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

The compiler uses your specified translations instead of generating them with AI.

Syntax

The data-lingo-override attribute accepts an object with locale codes as keys:

data-lingo-override={{
  [locale]: "translation",
  ...
}}

Locale codes must match your configured targetLocales. The attribute is removed from the final HTML output.

Use Cases

Brand Names

Preserve brand names across all locales:

<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev", fr: "Lingo.dev" }}>
  Lingo.dev
</h1>

Technical Terms

Ensure consistent technical terminology:

<p data-lingo-override={{ es: "API REST", de: "REST-API", ja: "REST API" }}>
  REST API
</p>

Legal Text

Use certified translations for legal content:

<p data-lingo-override={{
  es: "Todos los derechos reservados. Consulte nuestros términos legales.",
  de: "Alle Rechte vorbehalten. Siehe unsere rechtlichen Bedingungen."
}}>
  All rights reserved. See our legal terms.
</p>

Marketing Copy

Fine-tune marketing messages:

<h2 data-lingo-override={{
  es: "Traduce tu app en minutos",
  de: "Übersetze deine App in Minuten",
  fr: "Traduisez votre app en quelques minutes"
}}>
  Translate your app in minutes
</h2>

Partial Overrides

Override only specific locales—other locales use AI translations:

<p data-lingo-override={{ de: "Professionelle Übersetzung" }}>
  Professional translation
</p>

Spanish, French, and other locales use AI translations. Only German uses your override.

Rich Text and Interpolations

The compiler handles rich text with nested elements:

<p data-lingo-override={{
  es: "Bienvenido <strong0>{name}</strong0>",
  de: "Willkommen <strong0>{name}</strong0>"
}}>
  Welcome <strong>{name}</strong>
</p>

Placeholder syntax:

  • <tagname0>...</tagname0> for first instance of a tag
  • <tagname1>...</tagname1> for second instance
  • {variableName} for interpolations

The compiler automatically maps <strong0> back to <strong> in the output.

Multiple Nested Elements

<div data-lingo-override={{
  es: "Tu pedido: <span0>{count}</span0> artículos por <em0>${price}</em0>",
  de: "Deine Bestellung: <span0>{count}</span0> Artikel für <em0>${price}</em0>"
}}>
  Your order: <span>{count}</span> items for <em>${price}</em>
</div>

Complex Examples

Nested Components

<section>
  <h1 data-lingo-override={{ es: "Características", de: "Funktionen" }}>
    Features
  </h1>
  <p data-lingo-override={{
    es: "Traduce automáticamente tus componentes React sin cambios de código",
    de: "Übersetze deine React-Komponenten automatisch ohne Code-Änderungen"
  }}>
    Automatically translate your React components without code changes
  </p>
</section>

Attributes

Works with string attributes too:

<img
  src="/logo.png"
  alt="Company Logo"
  data-lingo-override={{
    es: "Logo de la Empresa",
    de: "Firmenlogo"
  }}
/>

The override applies to the alt attribute.

Locale Region Codes

Supports locale region codes (e.g., en-US, en-GB):

<p data-lingo-override={{
  "en-US": "color",
  "en-GB": "colour",
  "es-ES": "color",
  "es-MX": "color"
}}>
  color
</p>

Use quotes for locale codes with hyphens.

TypeScript Support

The attribute is fully typed when using TypeScript:

interface OverrideProps {
  "data-lingo-override"?: Record<string, string>;
}

TypeScript will validate locale codes match your configured targetLocales.

Best Practices

Use sparingly—Let AI handle most translations. Override only when necessary:

  • Brand names that shouldn't be translated
  • Technical terms requiring specific translations
  • Legal text requiring certification
  • Marketing copy needing human review

Maintain consistency—Use overrides for the same terms across your app:

// Good - consistent brand name
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>Lingo.dev</span></p>

// Bad - inconsistent
<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override

Version control—Override strings are in your source code, making them easy to review and version control.

Common Questions

Does this work with Client Components? Yes. Overrides work with both Server and Client Components.

Can I override attributes like aria-label? Yes. The override applies to the translatable text whether it's element content or an attribute.

What if I only override one locale? Other locales use AI translations. Overrides are per-locale—no need to specify all locales.

Can I use variables in overrides? Yes. Use {variableName} syntax for interpolations. The compiler preserves variable placeholders.

Do overrides increase bundle size? Slightly. Each override adds a few bytes to the bundle. The impact is negligible for reasonable use.

Can I override in development only? No. Overrides are source code—they apply in all environments. Use the development widget for temporary testing.

Next Steps