Development Tools

@lingo.dev/compiler provides development tools to speed up your workflow and reduce API costs during development.

Pseudotranslator

The pseudotranslator generates instant fake translations without API calls.

Enable

{
  dev: {
    usePseudotranslator: true,
  }
}

What It Does

Transforms text with visual markers:

Original:

Welcome to our app

Pseudotranslated:

[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]

Benefits:

  1. Instant feedback — No API calls, no waiting
  2. Visualize translatable text — See exactly what gets translated
  3. Test varying lengths — Pseudotranslations are ~30% longer, revealing layout issues
  4. Zero cost — No API credits consumed

How It Works

The pseudotranslator:

  • Adds markers ([!!! and !!!])
  • Replaces characters with accented versions (a → ä, e → ë)
  • Extends text length by ~30%
  • Preserves interpolations ({name} stays {name})
  • Maintains HTML structure

Example with interpolations:

<p>Hello {name}, you have {count} items</p>
// Becomes: [!!! Ḧëļļö {name}, ÿöü ḧävë {count} ïẗëṁṡ !!!]

When to Use

During development:

  • Initial setup and integration
  • Layout testing with varying text lengths
  • Debugging translation issues
  • Rapid iteration on UI

When NOT to use:

  • Reviewing actual translation quality
  • Testing locale-specific formatting
  • Final QA before deployment

Disable for Real Translations

{
  dev: {
    usePseudotranslator: false,
  }
}

Restart dev server to generate real translations using your configured LLM provider.

Translation Server

The translation server handles on-demand translation generation during development.

How It Works

When you run npm run dev:

  1. Compiler starts a local HTTP server
  2. Server auto-finds an available port (60000-60099)
  3. Your app requests translations from the server
  4. Server generates translations (pseudo or real)
  5. Translations are cached in .lingo/metadata.json

Configuration

{
  dev: {
    translationServerStartPort: 60000, // Starting port
    translationServerUrl: "http://localhost:60000", // Custom URL (advanced)
  }
}

Port range: The server tries ports 60000-60099 sequentially until it finds an available one.

Manual Start (Advanced)

You can start the translation server manually:

npx @lingo.dev/compiler translate-server \
  --port 60000 \
  --config ./lingo.config.json

This is useful for:

  • Running translation server separately from build process
  • Debugging translation issues
  • Custom CI/CD workflows

WebSocket Support

The translation server supports WebSockets for real-time communication with the development widget.

When translations update, the server pushes changes to connected clients via WebSocket.

Development Widget

The development widget is an in-browser overlay for editing translations in real-time.

Features

  • Edit translations in-browser — No need to edit files
  • See context — View source text, component location
  • Real-time updates — Changes apply immediately via WebSocket
  • Locale switching — Test different locales quickly

Enable

{
  dev: {
    enableWidget: true, // Coming soon
  }
}

Status: Development widget is under active development and will be available in a future release.

How It Will Work

  1. Press keyboard shortcut (e.g., Cmd+Shift+L)
  2. Widget overlay appears
  3. Click any translated text to edit
  4. Change translations for specific locales
  5. Save—changes sync via WebSocket
  6. Translations update instantly in .lingo/metadata.json

Development Workflow

1. Initial Setup:

{
  dev: {
    usePseudotranslator: true, // Fast feedback
  }
}

Run npm run dev to see pseudotranslations instantly.

2. Layout Testing:

Pseudotranslations reveal layout issues:

  • Text overflow
  • Truncated labels
  • Misaligned elements
  • Incorrect responsive breakpoints

Fix layout issues before investing in real translations.

3. Real Translation Review:

{
  dev: {
    usePseudotranslator: false,
  }
}

Generate real translations to review quality. Test:

  • Translation accuracy
  • Tone and formality
  • Technical term handling
  • Brand name preservation

4. Fine-Tuning:

Use data-lingo-override for precision control:

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

5. Production Build:

{
  buildMode: "cache-only",
}

Use pre-generated translations for fast, deterministic builds.

Debugging

Check Translation Server

Translation server logs to console:

[lingo] Translation server started on port 60001
[lingo] Pseudotranslator: enabled
[lingo] Watching for changes...

Check Metadata File

Inspect .lingo/metadata.json to see cached translations:

{
  "translations": {
    "abc123": {
      "source": "Welcome to our app",
      "locales": {
        "es": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]",
        "de": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]"
      }
    }
  }
}

With pseudotranslator disabled, you'll see real translations instead.

Port Conflicts

If ports 60000-60099 are all in use:

{
  dev: {
    translationServerStartPort: 61000, // Use different range
  }
}

Or manually stop processes using those ports:

# Find process using port 60000
lsof -i :60000

# Kill process
kill -9 <PID>

Performance Tips

Pseudotranslator is fast—use it by default in development.

Real translations are slower—only use when you need to review quality:

  • Initial translation generation: API latency applies
  • Subsequent builds: Translations are cached, fast

Translation server is lightweight—minimal memory and CPU usage.

Common Questions

Do I need to start the translation server manually? No. It starts automatically when you run npm run dev.

Can I use pseudotranslator in production? No. Pseudotranslator is development-only. Production builds always use real translations from .lingo/metadata.json.

Why isn't the development widget available yet? It's under active development. Follow GitHub releases for updates.

Can I customize pseudotranslations? Not currently. Pseudotranslator uses a fixed algorithm optimized for visualizing translatable text.

Do pseudotranslations work with all character sets? Yes. The pseudotranslator handles Unicode correctly, including emoji, CJK characters, and RTL languages.

Next Steps