RFC: AI Integration in Lingui CLI

[andrii-bodnar]

Background

Two key pain points exist in current i18n workflows:

1. Missing Context: Developers rarely add context comments manually, forcing translators to work with isolated strings that frequently result in incorrect translations and ambiguity.
2. Manual Translation: The discussion at #2342 highlights that despite AI coding tools, developers still manually translate strings in .po files.

This RFC proposes native AI integration in Lingui CLI to address both issues.

Motivation

• Automatic Context Generation: Analyze code during extraction and add helpful context for translators
• Automatic Translation: Generate initial translations using AI, eliminating manual work
• Natural Workflow: extract → translate → compile becomes the standard flow
• Provider Flexibility: Support OpenAI, Anthropic, Google, and other providers via unified interface

Proposed Solution

Overview

Two AI-powered features:

1. Context Generation (during extract): Analyzes code surrounding each message and generates descriptive comments
2. Automatic Translation (new translate command): Fills missing translations using AI

Both features share a common AI service infrastructure.

Configuration

Add new root-level ai configuration in packages/conf/src/types.ts:

import type { LanguageModel } from "ai"

type AIConfig = {
  model: LanguageModel
}

export type LinguiConfig = {
  // ... existing config
  ai?: AIConfig
}

Users import and configure their preferred provider directly, giving full control over provider options and supporting any AI SDK provider (including community providers).

Environment Variables

Each provider uses its own standard environment variables per Vercel AI SDK conventions:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
# And any other provider...

Architecture

flowchart TD
    subgraph Extract[lingui extract]
        E1[Extract Messages] --> E2[Messages Collected]
        E2 --> E3{Context Enabled?}
        E3 -->|Yes| E4[AI Service: Generate Context]
        E3 -->|No| E5[Write Catalogs]
        E4 --> E5
    end
    
    subgraph Translate[lingui translate]
        T1[Read Catalogs] --> T2[Find Missing Translations]
        T2 --> T3[AI Service: Generate Translations]
        T3 --> T4[Write Translations]
    end
    
    AIService[AI Service<br/>Vercel AI SDK] -.->|Context| E4
    AIService -.->|Translation| T3

Loading

Implementation Details

1. AI Service Module (packages/cli/src/api/ai/)

2. Core Interface:

// Using Vercel AI SDK
import { generateText, type LanguageModel } from 'ai'

interface AIService {
  constructor(model: LanguageModel)

  // Generate context for extracted messages
  generateContext(params: {
    messages: ExtractedMessage[]
    sourceFiles: Map<string, string> // filename -> file content
  }): Promise<Map<string, string>> // messageId -> context

  // Generate translations for messages
  generateTranslations(params: {
    messages: Array<{ id: string; message: string; context?: string }>
    targetLocale: string
    sourceLocale: string
  }): Promise<Map<string, string>> // messageId -> translation
}

This is a very basic example. Probably, we should stick to the Structured Output Generation approach under the hood.

3. Integration Points:

Context Generation - packages/cli/src/api/catalog/extractFromFiles.ts:

• After all messages extracted, before writing catalogs
• Call AI service with batch of messages
• Enhance messages with generated context in comments field

Translation - New command packages/cli/src/lingui-translate.ts:

• Similar structure to existing extract/compile commands
• Read existing catalogs
• Find messages with empty translations
• Generate translations via AI service
• Write updated catalogs

4. Using the Configured Model:

// In CLI code
import { generateText, Output } from 'ai'
import { z } from 'zod'

const aiService = new AIService(config.ai.model)

// The model is already configured by user, just use it
const result = await generateText({
  model: config.ai.model,
  prompt: '...',
  output: Output.object({
    schema: z.object({...}),
  }),
})

Usage Examples

1. Context Generation:

// lingui.config.ts
import { defineConfig } from "@lingui/conf"
import { openai } from "@ai-sdk/openai"

export default defineConfig({
  sourceLocale: "en",
  locales: ["en", "cs", "de"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
  ai: {
    model: openai("gpt-5")
  }
})

export OPENAI_API_KEY=sk-...  # Set API key via env var (standard AI SDK convention)

lingui extract --context  # Extract with AI-generated context

Output:

#. Button label in header navigation. Logs user out and redirects to homepage.
#: src/components/Header.tsx:24
msgid "Log Out"
msgstr ""

2. Automatic Translation:

// lingui.config.ts
import { defineConfig } from "@lingui/conf"
import { anthropic } from "@ai-sdk/anthropic"

export default defineConfig({
  sourceLocale: "en",
  locales: ["en", "cs", "de"],
  catalogs: [
    {
      path: "<rootDir>/src/locales/{locale}/messages",
      include: ["src"],
    },
  ],
  ai: {
    model: anthropic("claude-opus-4-5")
  }
})

export ANTHROPIC_API_KEY=sk-ant-...  # Set API key

lingui translate  # Translate missing strings
lingui translate --locale cs --locale de  # Or translate specific locales

Benefits

1. Full Flexibility: Users control provider initialization and configuration
2. Zero Vendor Lock-in: Works with any AI SDK provider (official or community)
3. Provider-Agnostic: No need for Lingui to support each provider individually
4. Standard Conventions: Uses AI SDK environment variables and patterns
5. Simple Integration: Just import, configure, and pass the model
6. Opt-in Features: Controlled via CLI flags (--context for extract, command itself for translate)

Dependencies

Core dependency:

• ai - Vercel AI SDK (peer dependency - users install what they need)

User installs their chosen provider(s):

• @ai-sdk/openai - For OpenAI models
• @ai-sdk/anthropic - For Anthropic models
• @ai-sdk/google - For Google models
• Or any other AI SDK provider

Prompt Examples

Context Generation:

Analyze this i18n message and generate a brief context comment (1-2 sentences) for translators.

File: {fileName}
Message: "{message}"
Code context:
{codeSnippet}

Describe: UI location, user action, dynamic values, or important constraints.

Translation:

Translate the following i18n messages from {sourceLocale} to {targetLocale}.
Maintain placeholders like {name}, {count}, etc.
Context is provided to help with accurate translation.

Messages:
{batch of messages with context}

Open Questions

1. Incremental Updates: Should context/translation only run for new/changed messages?
2. Caching: Cache AI responses to avoid redundant API calls?
3. Architecture: Should all the new AI-related logic be extracted to a separate package, e.g. @lingui/ai?
4. Cost Controls: Add warnings when batch size exceeds cost threshold?
5. System Prompts: Should we allow system prompts to be extended or overwritten by the developer?

[christian-egger-augedo]

Super cool initiative!!

• I have a script that I run locally that went through 2-3 iterations of improvements.
  The biggest improvement came from also pulling context from other existing translations that are "physically" close to the string that is to be translated.
  In simple terms: When translating a string, look up the existing translation on the same page / components and add these as context to the translation prompt ("On this page we already have these 20 translations below. Make sure to stick to the tone and style. [...]")
  And the .po format makes sourcing "close" translations super easy, due to the nature of how it points to the strings via paths, e.g.

#: src/pages/oscar/ad-campaigns/ads.tsx:1182
msgid "Add description..."
msgstr "Beschreibung hinzufügen..."

6. System Prompts: I believe that users should be able to either a) update the System prompt or b) at least inject additoinal context to the translation. What comes to mind for me is that often times there are guidelines on how a brand communicates. Being able to add such communication guidelines to the context makes the translations more precise, especially when starting from scratch.

[andrii-bodnar]

Thank you very much for your input!

Your observation about incorporating the nearest existing translation into the prompt is very interesting. There is something similar in the native Crowdin AI - "Previous and next strings" option. It helps the AI suggest a more accurate translation of the string, depending on the strings that come before and after it.

I also agree that it should be possible to include additional context or instructions in the system prompt. It looks like we can hardcode the system prompt at the library level and allow additional instructions to be included in the prompt option of the generateText method.