Lingo.dev I18n Copilot

Implements comprehensive internationalization in web applications using Lingo.dev with step-by-step checklist-driven workflows.

When to Use This Agent

Choose this agent when you need to:

• Add multi-language support to React, Next.js, or Vue apps using the Lingo.dev platform
• Follow a structured, validated i18n workflow that checks each phase before proceeding
• Configure locale detection, string extraction, pluralization, and translation management

Consider alternatives when:

• You need general i18n with react-intl or i18next without the Lingo.dev platform
• Your translation workflow is purely manual without automated translation management

Quick Start

Configuration

Copy
name: lingodotdev-i18n-copilot
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke lingodotdev-i18n-copilot "Set up i18n for my Next.js app with English, Spanish, and Japanese"

Example Output

i18n Implementation Checklist
==============================
Step 1/6: Project Analysis .............. COMPLETE
  - Framework: Next.js 16, 47 hardcoded strings in 12 files
Step 2/6: Configuration Setup ........... COMPLETE
  - Created: i18n/config.ts (locales: en, es, ja)
  - Created: lingo.config.json
Step 3/6: String Extraction ............. IN PROGRESS
  - Extracting from components: 8/12 processed

Core Concepts

I18n Implementation Layers

Aspect	Details
String Extraction	Replacing hardcoded text with t() function calls and translation keys
Locale Routing	URL-based (/en/about), subdomain, or cookie-based locale detection
Translation Files	JSON message catalogs organized by locale with nested namespaces
Pluralization	ICU MessageFormat rules handling zero/one/few/many/other per locale
Lingo.dev Sync	Bidirectional sync between local files and the Lingo.dev cloud platform

I18n Workflow Architecture

+-------------------+     +-------------------+     +------------------+
|  Source Code      |---->|  String           |---->|  Translation     |
|  Analysis         |     |  Extraction       |     |  Key Generation  |
+-------------------+     +-------------------+     +------------------+
                                                          |
         +-------------------+     +-------------------+  |
         |  Build            |<----|  Lingo.dev        |<-+
         |  Validation       |     |  Platform Sync    |
         +-------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
source_locale	string	"en"	Primary language used as translation source
target_locales	array	[]	Target locale codes for translation generation
framework_adapter	string	"auto"	Binding: "next-intl", "react-intl", "vue-i18n", or "auto"
key_style	string	"nested"	Key format: "nested" (auth.login.title) or "flat"
sync_mode	string	"pull"	Sync: "push", "pull", or "bidirectional"

Best Practices

1. Follow the Checklist Sequentially - The agent operates through a structured multi-step checklist where each step must be validated before proceeding. Skipping steps causes downstream configuration errors harder to diagnose than following the prescribed order.

2. Extract Strings per Component - Process one component at a time rather than bulk-extracting. This lets you verify each t() call renders correctly before moving on, preventing a cascade of broken views.

3. Use Namespaced Keys - Organize keys by domain (auth.login.submitButton) rather than flat identifiers. This enables per-feature translation loading and reduces merge conflicts.

4. Build After Each Phase - Run a full build after each checklist step to catch configuration errors immediately. Missing keys and malformed ICU syntax surface as build-time errors.

5. Handle Pluralization with ICU - Avoid conditional string concatenation. Use ICU MessageFormat ({count, plural, one {# item} other {# items}}) which handles complex plural rules for all locales.

Common Issues

1. Missing Translations Cause Blanks - When a key exists in source but not target locale, some libraries render empty strings. Configure fallbackLocale: "en" and enable missing-key warnings in development.

2. Date/Number Formatting Gaps - String translations do not cover locale-sensitive formatting. Use Intl.DateTimeFormat and Intl.NumberFormat alongside your translation library.

3. Locale Routing Conflicts - Adding locale prefixes can break API routes and static assets. Exclude non-content paths with matcher patterns like /((?!api|_next|static|.*\\..*).*).