@lingo.dev/cli 1.0.1 → 1.0.3

package/dist/server-DGIsMSAq.js

@@ -0,0 +1,847 @@
+import { C as discoverLocales, S as writeLocaleFile, T as tryReadFile, _ as runExtractionPipeline, a as detectInstallMethod, b as mergeEntries, d as computeSourceStatus, g as generateTypes, h as toApiPayload, i as compareVersions, l as runChecks, m as planLocalization, o as generateUpdateCommand, p as applyTranslations, s as VERSION, u as computeLocaleStatus, v as toLocaleEntries, w as findSourceFiles } from "./update-RHUBOb93.js";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { computeKey, getActiveEntries, readLocaleFile } from "@lingo.dev/spec";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+//#region src/mcp/hints.ts
+/**
+* Contextual agent hints appended to tool responses.
+* Fired once per session, never repeated, disabled via LINGO_NO_HINTS env var.
+*/
+const firedHints = /* @__PURE__ */ new Set();
+const HINTS = {
+	engine: {
+		condition: (ctx) => ctx.trigger === "first_translate",
+		message: "For glossary + brand voice, connect an engine: `lingo login && lingo link`"
+	},
+	manyLocales: {
+		condition: (ctx) => ctx.trigger === "translate" && (ctx.targetLocaleCount ?? 0) >= 5,
+		message: "Per-locale brand voice and model selection available with a connected engine."
+	},
+	manyStrings: {
+		condition: (ctx) => ctx.trigger === "extract" && (ctx.stringCount ?? 0) >= 100,
+		message: "At scale, a connected engine provides caching + glossary consistency."
+	}
+};
+function getHint(ctx) {
+	if (process.env.LINGO_NO_HINTS === "1") return void 0;
+	for (const [id, hint] of Object.entries(HINTS)) {
+		if (firedHints.has(id)) continue;
+		if (hint.condition(ctx)) {
+			firedHints.add(id);
+			return hint.message;
+		}
+	}
+}
+//#endregion
+//#region src/mcp/prompts.ts
+/**
+* MCP prompts for guided AI agent workflows.
+* These are the single source of truth for how AI agents use @lingo.dev/react.
+* Skills reference these prompts - never duplicate the instructions.
+*/
+const PROMPTS = {
+	lingo_setup: {
+		name: "lingo_setup",
+		description: "Comprehensive guide for first-time @lingo.dev/react setup in a project",
+		arguments: [{
+			name: "framework",
+			description: "Detected framework (next-pages, next-app, vite, react-router)",
+			required: false
+		}, {
+			name: "targetLocales",
+			description: "Target locales to translate to (e.g., 'es fr ja')",
+			required: false
+		}],
+		text: `# Setting up @lingo.dev/react
+
+You are setting up internationalization in a React project. Follow every step precisely.
+
+## Philosophy
+
+Context is REQUIRED on every translation call. Always. No exceptions.
+Route is REQUIRED on every withLingoProps call. Always. No exceptions.
+The human doesn't write i18n code - YOU do. Write clean, explicit, reviewable code.
+
+## Step 1: Detect Framework
+
+Read package.json and the project structure. Determine:
+- **Next.js Pages Router**: has \`next\` dependency + \`pages/\` or \`src/pages/\` directory
+- **Next.js App Router**: has \`next\` dependency + \`app/\` or \`src/app/\` directory
+- **Vite + React**: has \`vite\` dependency
+- **React Router / Remix**: has \`react-router\` or \`@remix-run\` dependency
+
+## Step 2: Install Packages
+
+Detect package manager from lockfile (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb).
+
+For Next.js:
+\`\`\`bash
+pnpm add @lingo.dev/react @lingo.dev/react-next
+\`\`\`
+
+For other frameworks:
+\`\`\`bash
+pnpm add @lingo.dev/react
+\`\`\`
+
+The CLI should already be installed (\`@lingo.dev/cli\`). If not:
+\`\`\`bash
+pnpm add -D @lingo.dev/cli
+\`\`\`
+
+## Step 3: Configure Framework (Next.js Pages Router)
+
+Edit \`next.config.ts\`:
+\`\`\`ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  i18n: {
+    locales: ["en", "es"],  // adjust to requested locales
+    defaultLocale: "en",
+  },
+};
+
+export default nextConfig;
+\`\`\`
+
+This gives automatic sub-path routing: \`/\` (English), \`/es/\` (Spanish).
+
+## Step 4: Wrap App Root
+
+### Next.js Pages Router
+
+\`\`\`tsx
+// pages/_app.tsx
+import type { AppProps } from "next/app";
+import { withLingoApp, LingoHead } from "@lingo.dev/react-next/pages/client";
+
+export default withLingoApp(function App({ Component, pageProps }: AppProps) {
+  return (
+    <>
+      <LingoHead />
+      <Component {...pageProps} />
+    </>
+  );
+});
+\`\`\`
+
+\`withLingoApp\` does three things:
+1. Wraps with \`LingoProvider\` (locale from router, messages from pageProps)
+2. Sets \`dir="rtl"\` for RTL locales (blocking script for SSR + useEffect for CSR)
+3. Warns in dev mode when a page is missing \`withLingoProps\`
+
+\`LingoHead\` generates \`<link rel="alternate" hreflang="...">\` tags for SEO.
+
+## Step 5: Add withLingoProps to Every Page
+
+EVERY page that uses translations must have \`withLingoProps\`. Route is required.
+
+\`\`\`tsx
+import { withLingoProps } from "@lingo.dev/react-next/pages/server";
+
+export const getStaticProps = withLingoProps({ route: "src/pages/index" });
+\`\`\`
+
+The \`route\` value is the file path relative to project root, without extension.
+- \`src/pages/index.tsx\` -> route: \`"src/pages/index"\`
+- \`src/pages/about.tsx\` -> route: \`"src/pages/about"\`
+- \`src/pages/blog/[slug].tsx\` -> route: \`"src/pages/blog/[slug]"\`
+- \`pages/index.tsx\` (no src/) -> route: \`"pages/index"\`
+
+With custom data:
+\`\`\`tsx
+export const getStaticProps = withLingoProps({
+  route: "src/pages/blog/[slug]",
+  handler: async (ctx) => {
+    const post = await getPost(ctx.params!.slug as string);
+    if (!post) return { notFound: true };
+    return { props: { post }, revalidate: 60 };
+  },
+});
+\`\`\`
+
+For dynamic routes, also add \`withLingoPaths\`:
+\`\`\`tsx
+import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
+
+export const getStaticPaths = withLingoPaths(async () => {
+  const posts = await getPosts();
+  return posts.map((post) => ({ params: { slug: post.slug } }));
+});
+\`\`\`
+
+This auto-expands paths across all locales with \`fallback: "blocking"\`.
+
+## Step 6: Replace Strings with l.text()
+
+Import \`useLingo\` and wrap every user-facing string.
+
+\`\`\`tsx
+import { useLingo } from "@lingo.dev/react";
+
+export default function Page() {
+  const l = useLingo();
+  return (
+    <div>
+      <h1>{l.text("Welcome to Acme", { context: "Homepage hero heading" })}</h1>
+      <p>{l.text("The best tool for teams.", { context: "Homepage hero subheading" })}</p>
+      <button>{l.text("Get started", { context: "Homepage CTA button" })}</button>
+    </div>
+  );
+}
+\`\`\`
+
+### API Reference
+
+**\`l.text(source, { context, values? })\`** - Plain text translation
+\`\`\`tsx
+l.text("Hello", { context: "Hero greeting" })
+l.text("Hello, {name}!", { context: "Dashboard welcome", values: { name: "Max" } })
+l.text("Save", { context: "Form submit button" })
+l.text("Save", { context: "Toolbar save action" })  // same text, different context = different translation
+\`\`\`
+
+**\`l.rich(source, { context, tags?, values? })\`** - Rich text with tags
+\`\`\`tsx
+l.rich("Read our <link>terms of service</link>", {
+  context: "Footer legal link",
+  tags: { link: (children) => <a href="/terms">{children}</a> },
+})
+l.rich("Welcome, <bold>{name}</bold>!", {
+  context: "Dashboard header",
+  tags: { bold: (children) => <strong>{children}</strong> },
+  values: { name: user.name },
+})
+\`\`\`
+
+**\`l.plural(count, forms, { context })\`** - Pluralization
+\`\`\`tsx
+l.plural(itemCount, { one: "# item", other: "# items" }, { context: "Cart item count" })
+l.plural(days, { one: "# day remaining", other: "# days remaining" }, { context: "Trial countdown" })
+\`\`\`
+
+**\`l.select(value, forms, { context })\`** - Select by value
+\`\`\`tsx
+l.select(role, { admin: "Admin Panel", user: "Dashboard", other: "Home" }, { context: "Navigation label" })
+\`\`\`
+
+**Formatting (no context needed - these use Intl APIs):**
+\`\`\`tsx
+l.num(1234567)                        // "1,234,567"
+l.currency(29.99, "USD")              // "$29.99"
+l.percent(0.156)                      // "16%"
+l.date(new Date())                    // "Mar 17, 2026"
+l.time(new Date())                    // "10:30 AM"
+l.relative(-1, "day")                 // "yesterday"
+l.list(["Alice", "Bob", "Charlie"])   // "Alice, Bob, and Charlie"
+\`\`\`
+
+### Context Rules
+
+1. Context is REQUIRED on every \`l.text()\`, \`l.rich()\`, \`l.plural()\`, \`l.select()\` call
+2. Context describes WHERE and HOW the text is used (not WHAT it says)
+3. Good context: "Checkout form submit button", "Hero section heading", "Error toast message"
+4. Bad context: "button", "heading", "text" (too generic)
+5. Same source text with different context = different translation (e.g., "Save" in a form vs toolbar)
+6. Context is included in the hash key - changing context changes the key
+
+### Locale Switcher
+
+Add a locale switcher component:
+\`\`\`tsx
+import { useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
+import { useRouter } from "next/router";
+
+export function LocaleSwitcher() {
+  const { locale, locales } = useRouter();
+  const switchLocale = useLocaleSwitch();
+
+  return (
+    <select value={locale} onChange={(e) => switchLocale(e.target.value)}>
+      {locales?.map((l) => (
+        <option key={l} value={l}>{l.toUpperCase()}</option>
+      ))}
+    </select>
+  );
+}
+\`\`\`
+
+## Step 7: Extract
+
+Run the \`lingo_extract\` tool (or \`pnpm lingo extract\`). This:
+- Scans source files for all \`l.text()\`, \`l.rich()\`, \`l.plural()\`, \`l.select()\` calls
+- Generates \`locales/en.jsonc\` with source messages, @context metadata, @src file locations
+- Generates \`lingo.d.ts\` with TypeScript types (exact context unions, value types)
+
+After extraction, TypeScript enforces:
+- Only extracted source strings are valid in \`l.text()\`
+- Context must match the exact extracted value (union type)
+- Required values must be provided for messages with placeholders
+
+## Step 8: Translate
+
+Run the \`lingo_translate\` tool (or \`pnpm lingo localize --target-locale es\`).
+This sends source messages with context to the Lingo.dev API and writes translated JSONC files.
+
+## Step 9: Verify
+
+Run the \`lingo_check\` tool (or \`pnpm lingo check\`). This verifies:
+- All \`l.text()\` calls have context
+- JSONC files are up to date with source code
+- \`lingo.d.ts\` is up to date
+- All target locales have complete translations
+
+Only report success when \`lingo_check\` returns 0 issues.`
+	},
+	lingo_localize: {
+		name: "lingo_localize",
+		description: "Guide for ongoing localization: find untranslated strings, wrap them, extract, translate, verify",
+		arguments: [{
+			name: "filePath",
+			description: "Specific file to localize (optional - checks whole project if omitted)",
+			required: false
+		}],
+		text: `# Localizing strings
+
+You are helping maintain translations in an existing @lingo.dev/react project.
+
+## Step 1: Check Current State
+
+Run the \`lingo_check\` tool first. It reports:
+- Missing context on any \`l.text()\` calls
+- Stale JSONC files (source code changed, JSONC not updated)
+- Stale TypeScript types
+- Missing translations in target locales
+- Orphaned entries (removed from source code)
+
+## Step 2: Fix Issues
+
+Based on what \`lingo_check\` reports:
+
+**Missing context:** Find the calls without context and add it.
+\`\`\`tsx
+// Before (will fail lingo_check):
+l.text("Save")
+
+// After:
+l.text("Save", { context: "Settings form submit button" })
+\`\`\`
+
+**Untranslated strings:** Find hardcoded user-facing strings and wrap them:
+\`\`\`tsx
+// Before:
+<h1>Welcome back</h1>
+<p>You have {count} notifications</p>
+
+// After:
+<h1>{l.text("Welcome back", { context: "Dashboard greeting heading" })}</h1>
+<p>{l.plural(count, { one: "You have # notification", other: "You have # notifications" }, { context: "Dashboard notification count" })}</p>
+\`\`\`
+
+**Missing withLingoProps:** Every page using \`useLingo()\` needs it:
+\`\`\`tsx
+export const getStaticProps = withLingoProps({ route: "src/pages/dashboard" });
+\`\`\`
+
+## Step 3: Extract + Translate + Verify
+
+1. Run \`lingo_extract\` to update JSONC + types
+2. Run \`lingo_translate\` to translate new strings
+3. Run \`lingo_check\` to verify 0 issues
+
+## What to Wrap
+
+Wrap ALL user-facing text:
+- Headings, paragraphs, labels
+- Button text, link text
+- Placeholder text, aria-labels
+- Error messages, success messages, toast notifications
+- Table headers, form labels
+- Alt text for images
+
+Do NOT wrap:
+- Code identifiers, CSS class names
+- URLs, email addresses
+- Numbers that are already formatted via \`l.num()\`
+- Technical identifiers (API keys, IDs)`
+	},
+	lingo_migrate: {
+		name: "lingo_migrate",
+		description: "Guide for migrating from another i18n library (next-intl, i18next, react-intl, lingui) to @lingo.dev/react",
+		arguments: [{
+			name: "fromLibrary",
+			description: "Library to migrate from (next-intl, i18next, react-intl, lingui)",
+			required: false
+		}],
+		text: `# Migrating to @lingo.dev/react
+
+You are migrating a project from another i18n library to @lingo.dev/react.
+
+## Key Difference
+
+Old libraries use manual key strings: \`t("pages.home.title")\`
+@lingo.dev/react uses source text + context: \`l.text("Welcome", { context: "Home page title" })\`
+
+No key management. No key naming conventions. The key is a deterministic hash computed from source + context.
+
+## API Mapping
+
+| Pattern | next-intl | react-intl | i18next | @lingo.dev/react |
+|---------|-----------|------------|---------|------------------|
+| Plain text | \`t("key")\` | \`formatMessage({ id: "key" })\` | \`t("key")\` | \`l.text("source", { context: "..." })\` |
+| With values | \`t("key", { name })\` | \`formatMessage({ id }, { name })\` | \`t("key", { name })\` | \`l.text("Hello, {name}", { context: "...", values: { name } })\` |
+| Rich text | \`t.rich("key", { link })\` | \`<FormattedMessage components />\` | \`<Trans components />\` | \`l.rich("Click <link>here</link>", { context: "...", tags: { link } })\` |
+| Plurals | ICU in JSON | \`<FormattedPlural />\` | ICU in JSON | \`l.plural(count, { one: "...", other: "..." }, { context: "..." })\` |
+| Provider | \`NextIntlClientProvider\` | \`IntlProvider\` | \`I18nextProvider\` | \`LingoProvider\` (via \`withLingoApp\`) |
+| Hook | \`useTranslations()\` | \`useIntl()\` | \`useTranslation()\` | \`useLingo()\` |
+
+## Migration Steps
+
+1. **Install @lingo.dev/react** alongside the existing library (both can coexist).
+
+2. **Set up @lingo.dev/react** following the \`lingo_setup\` prompt (add withLingoApp wrapping the existing provider, configure next.config.ts if not already done).
+
+3. **Migrate one component at a time:**
+   - Replace the old hook with \`const l = useLingo()\`
+   - Replace each translation call using the mapping above
+   - The source text should be the DEFAULT LANGUAGE text (usually English)
+   - Derive context from the old key name: \`home.hero.title\` -> context: \`"Home page hero title"\`
+   - Add \`withLingoProps({ route: "..." })\` if the page doesn't have it
+
+4. **Run extraction** after each component: \`lingo_extract\`
+
+5. **Run translation** to carry over existing translations: \`lingo_translate\`
+   The API produces new translations from the source text + context.
+
+6. **Remove the old library** once all components are migrated.
+   - Remove old provider wrapping
+   - Remove old JSON/YAML message files
+   - Remove old dependencies from package.json
+
+7. **Verify** with \`lingo_check\` - 0 issues means migration is complete.
+
+## Gotchas
+
+- Old libraries use nested key namespaces (\`home.hero.title\`). @lingo.dev/react uses flat hash keys. Don't try to replicate the namespace structure - let the hash system handle it.
+- If the old library has ICU MessageFormat in JSON files, the same patterns work in @lingo.dev/react since it uses intl-messageformat under the hood.
+- Existing translations in old JSON files cannot be directly imported - the keys are different (hash vs manual). Run \`lingo_translate\` to generate fresh translations with context.`
+	}
+};
+//#endregion
+//#region src/mcp/server.ts
+/**
+* Local MCP server for AI coding assistants.
+* Exposes i18n tools (extract, translate, search, etc.) over stdio transport.
+* Started via `lingo mcp`.
+*/
+let translateCallCount = 0;
+let updateNudge = null;
+async function checkUpdateOnce() {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 3e3);
+		const res = await fetch("https://registry.npmjs.org/@lingo.dev/cli/latest", {
+			headers: { Accept: "application/json" },
+			signal: controller.signal
+		});
+		clearTimeout(timeout);
+		if (!res.ok) return;
+		const info = compareVersions(VERSION, (await res.json()).version);
+		if (!info) return;
+		const cmd = generateUpdateCommand(detectInstallMethod(), info.latest);
+		updateNudge = {
+			current: info.current,
+			latest: info.latest,
+			command: cmd ? cmd.join(" ") : `npm install -D @lingo.dev/cli@${info.latest}`
+		};
+	} catch {}
+}
+function withUpdateNudge(response) {
+	if (!updateNudge) return response;
+	return {
+		...response,
+		content: [...response.content, {
+			type: "text",
+			text: [
+				"",
+				`IMPORTANT: You are using @lingo.dev/cli v${updateNudge.current}.`,
+				`v${updateNudge.latest} contains critical improvements to extraction accuracy, context handling, and translation quality.`,
+				`Results from the current version may be incomplete or incorrect.`,
+				`Update before proceeding: ${updateNudge.command}`
+			].join("\n")
+		}]
+	};
+}
+function cwd() {
+	return process.cwd();
+}
+function localesDir(out) {
+	return path.resolve(cwd(), out);
+}
+async function startMcpServer() {
+	checkUpdateOnce();
+	const server = new McpServer({
+		name: "@lingo.dev/react",
+		version: "0.1.0"
+	}, { capabilities: {
+		prompts: {},
+		tools: {}
+	} });
+	server.tool("lingo_search", "Search existing translations by source text, hash key, or context", {
+		query: z.string().describe("Search term (matches source text, key, or context)"),
+		out: z.string().default("locales").describe("Locale files directory")
+	}, async ({ query, out }) => {
+		const dir = localesDir(out);
+		const files = await fs.readdir(dir).catch(() => []);
+		const results = [];
+		const q = query.toLowerCase();
+		for (const file of files.filter((f) => f.endsWith(".jsonc"))) {
+			const locale = file.replace(/\.jsonc$/, "");
+			const content = await tryReadFile(path.join(dir, file));
+			if (!content) continue;
+			const parsed = readLocaleFile(content);
+			for (const entry of parsed.entries) if (entry.key.includes(query) || entry.value.toLowerCase().includes(q) || entry.metadata.context?.toLowerCase().includes(q)) results.push({
+				locale,
+				key: entry.key,
+				value: entry.value,
+				context: entry.metadata.context,
+				src: entry.metadata.src
+			});
+		}
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				matches: results,
+				total: results.length
+			}, null, 2)
+		}] };
+	});
+	server.tool("lingo_add", "Add a single translatable string to the source locale JSONC file", {
+		source: z.string().describe("Source text (e.g., 'Save changes')"),
+		context: z.string().optional().describe("Disambiguation context"),
+		filePath: z.string().optional().describe("Source file location (e.g., 'src/form.tsx:42')"),
+		sourceLocale: z.string().default("en").describe("Source locale code"),
+		out: z.string().default("locales").describe("Locale files directory")
+	}, async ({ source, context, filePath, sourceLocale, out }) => {
+		const key = computeKey(source, context);
+		const localePath = path.join(localesDir(out), `${sourceLocale}.jsonc`);
+		const content = await tryReadFile(localePath);
+		const existing = content ? readLocaleFile(content) : { entries: [] };
+		if (existing.entries.some((e) => e.key === key)) return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				key,
+				added: false,
+				reason: "Key already exists"
+			})
+		}] };
+		const entry = {
+			key,
+			value: source,
+			metadata: {
+				...context ? { context } : {},
+				...filePath ? { src: filePath } : {}
+			}
+		};
+		const merged = { entries: [...existing.entries, entry] };
+		await fs.mkdir(path.dirname(localePath), { recursive: true });
+		await fs.writeFile(localePath, writeLocaleFile(merged));
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				key,
+				added: true,
+				source,
+				context
+			})
+		}] };
+	});
+	server.tool("lingo_extract", "Extract translatable strings from source files into JSONC locale file + generate TypeScript declarations", {
+		src: z.string().default("src").describe("Source directory to scan"),
+		sourceLocale: z.string().default("en").describe("Source locale code"),
+		out: z.string().default("locales").describe("Output directory for locale files")
+	}, async ({ src, sourceLocale, out }) => {
+		const srcDir = path.resolve(cwd(), src);
+		const outDir = localesDir(out);
+		const localePath = path.join(outDir, `${sourceLocale}.jsonc`);
+		const typesPath = path.resolve(cwd(), "lingo.d.ts");
+		const filePaths = await findSourceFiles(srcDir);
+		if (filePaths.length === 0) return { content: [{
+			type: "text",
+			text: JSON.stringify({ error: `No .ts/.tsx files found in ${src}/` })
+		}] };
+		const { messages, warnings, collisions } = runExtractionPipeline(await Promise.all(filePaths.map(async (f) => ({
+			code: await fs.readFile(f, "utf-8"),
+			filePath: path.relative(cwd(), f)
+		}))));
+		if (collisions.length > 0) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({
+					error: "Hash collisions detected",
+					collisions
+				})
+			}],
+			isError: true
+		};
+		const entries = toLocaleEntries(messages);
+		const existingContent = await tryReadFile(localePath);
+		const existing = existingContent ? readLocaleFile(existingContent) : { entries: [] };
+		const merged = mergeEntries(existing, entries);
+		await fs.mkdir(outDir, { recursive: true });
+		await fs.writeFile(localePath, writeLocaleFile(merged));
+		await fs.writeFile(typesPath, generateTypes(merged));
+		const newCount = entries.filter((e) => !existing.entries.some((ex) => ex.key === e.key)).length;
+		const orphanCount = merged.entries.filter((e) => e.metadata.orphan).length;
+		const hint = getHint({
+			trigger: "extract",
+			stringCount: messages.length
+		});
+		return withUpdateNudge({ content: [{
+			type: "text",
+			text: JSON.stringify({
+				extracted: messages.length,
+				new: newCount,
+				orphaned: orphanCount,
+				warnings: warnings.map((w) => `${w.src}: ${w.message}`),
+				...hint ? { hint } : {},
+				nextAction: newCount > 0 ? "New strings found. Run lingo_translate to localize them." : void 0
+			}, null, 2)
+		}] });
+	});
+	server.tool("lingo_translate", "Localize missing strings to target locales via the Lingo.dev API", {
+		targetLocales: z.array(z.string()).describe("Target locale codes (e.g., ['es', 'fr'])"),
+		sourceLocale: z.string().default("en").describe("Source locale code"),
+		out: z.string().default("locales").describe("Locale files directory"),
+		apiKey: z.string().optional().describe("Lingo.dev API key (defaults to LINGO_API_KEY env var)")
+	}, async ({ targetLocales, sourceLocale, out, apiKey: apiKeyArg }) => {
+		const apiKey = apiKeyArg || process.env.LINGO_API_KEY;
+		if (!apiKey) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({ error: "No API key. Set LINGO_API_KEY env var or pass apiKey argument." })
+			}],
+			isError: true
+		};
+		const outDir = localesDir(out);
+		const sourceContent = await tryReadFile(path.join(outDir, `${sourceLocale}.jsonc`));
+		if (!sourceContent) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({ error: `No source file at ${out}/${sourceLocale}.jsonc. Run lingo_extract first.` })
+			}],
+			isError: true
+		};
+		const sourceFile = readLocaleFile(sourceContent);
+		const results = {};
+		for (const locale of targetLocales) {
+			const targetPath = path.join(outDir, `${locale}.jsonc`);
+			const targetContent = await tryReadFile(targetPath);
+			const targetFile = targetContent ? readLocaleFile(targetContent) : { entries: [] };
+			const plan = planLocalization(sourceFile, targetFile, locale);
+			if (plan.missing.length === 0) {
+				results[locale] = 0;
+				continue;
+			}
+			const { data, hints } = toApiPayload(plan.missing);
+			const apiUrl = process.env.LINGO_API_URL ?? "https://api.lingo.dev";
+			const res = await fetch(`${apiUrl}/process/localize`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-API-Key": apiKey
+				},
+				body: JSON.stringify({
+					sourceLocale,
+					targetLocale: locale,
+					data,
+					hints,
+					triggerType: "cli"
+				})
+			});
+			if (!res.ok) {
+				results[locale] = -1;
+				continue;
+			}
+			const response = await res.json();
+			const translated = applyTranslations(plan.missing, response.data);
+			const merged = mergeEntries(targetFile, [...getActiveEntries(targetFile.entries), ...translated]);
+			await fs.mkdir(outDir, { recursive: true });
+			await fs.writeFile(targetPath, writeLocaleFile(merged));
+			results[locale] = plan.missing.length;
+		}
+		translateCallCount++;
+		const hint = getHint({
+			trigger: translateCallCount === 1 ? "first_translate" : "translate",
+			targetLocaleCount: targetLocales.length
+		});
+		return withUpdateNudge({ content: [{
+			type: "text",
+			text: JSON.stringify({
+				localized: results,
+				...hint ? { hint } : {},
+				nextAction: "Run lingo_status to verify completeness."
+			}, null, 2)
+		}] });
+	});
+	server.tool("lingo_status", "Show per-locale translation completeness", {
+		sourceLocale: z.string().default("en").describe("Source locale code"),
+		out: z.string().default("locales").describe("Locale files directory")
+	}, async ({ sourceLocale, out }) => {
+		const outDir = localesDir(out);
+		const sourceContent = await tryReadFile(path.join(outDir, `${sourceLocale}.jsonc`));
+		if (!sourceContent) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({ error: `No source file at ${out}/${sourceLocale}.jsonc` })
+			}],
+			isError: true
+		};
+		const sourceFile = readLocaleFile(sourceContent);
+		const targets = await discoverLocales(outDir, sourceLocale);
+		const statuses = [computeSourceStatus(sourceFile, sourceLocale)];
+		for (const locale of targets) {
+			const content = await tryReadFile(path.join(outDir, `${locale}.jsonc`));
+			const targetFile = content ? readLocaleFile(content) : { entries: [] };
+			statuses.push(computeLocaleStatus(sourceFile, targetFile, locale));
+		}
+		const totalMissing = statuses.reduce((sum, s) => sum + s.missing, 0);
+		return withUpdateNudge({ content: [{
+			type: "text",
+			text: JSON.stringify({
+				statuses,
+				complete: totalMissing === 0,
+				nextAction: totalMissing > 0 ? `${totalMissing} strings missing. Run lingo_translate to fill gaps.` : void 0
+			}, null, 2)
+		}] });
+	});
+	server.tool("lingo_cleanup", "Remove orphaned (deleted from source) entries from locale files. Defaults to dry run for safety.", {
+		locale: z.string().optional().describe("Specific locale to clean (default: all)"),
+		out: z.string().default("locales").describe("Locale files directory"),
+		dryRun: z.boolean().default(true).describe("Preview changes without writing (default: true). Set to false to actually delete.")
+	}, async ({ locale, out, dryRun }) => {
+		const outDir = localesDir(out);
+		const files = locale ? [`${locale}.jsonc`] : await fs.readdir(outDir).catch(() => []);
+		const results = {};
+		for (const file of files.filter((f) => f.endsWith(".jsonc"))) {
+			const filePath = path.join(outDir, file);
+			const content = await tryReadFile(filePath);
+			if (!content) continue;
+			const parsed = readLocaleFile(content);
+			const active = getActiveEntries(parsed.entries);
+			const removed = parsed.entries.length - active.length;
+			if (removed > 0 && !dryRun) await fs.writeFile(filePath, writeLocaleFile({ entries: active }));
+			results[file.replace(/\.jsonc$/, "")] = removed;
+		}
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				...dryRun ? {
+					dryRun: true,
+					message: "Set dryRun: false to actually delete orphans."
+				} : {},
+				cleaned: results
+			}, null, 2)
+		}] };
+	});
+	server.tool("lingo_inspect", "Get full details for a translation key across all locales", {
+		source: z.string().optional().describe("Source text to look up"),
+		key: z.string().optional().describe("Hash key to look up"),
+		context: z.string().optional().describe("Context for hash computation"),
+		out: z.string().default("locales").describe("Locale files directory")
+	}, async ({ source, key: keyArg, context, out }) => {
+		const key = keyArg ?? (source ? computeKey(source, context) : void 0);
+		if (!key) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({ error: "Provide either source or key" })
+			}],
+			isError: true
+		};
+		const outDir = localesDir(out);
+		const files = await fs.readdir(outDir).catch(() => []);
+		const translations = {};
+		let sourceEntry = null;
+		for (const file of files.filter((f) => f.endsWith(".jsonc"))) {
+			const locale = file.replace(/\.jsonc$/, "");
+			const content = await tryReadFile(path.join(outDir, file));
+			if (!content) continue;
+			const entry = readLocaleFile(content).entries.find((e) => e.key === key);
+			translations[locale] = entry?.value ?? null;
+			if (!sourceEntry && entry) sourceEntry = {
+				source: entry.value,
+				context: entry.metadata.context,
+				src: entry.metadata.src
+			};
+		}
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				key,
+				...sourceEntry ?? {},
+				translations
+			}, null, 2)
+		}] };
+	});
+	server.tool("lingo_check", "Verify i18n consistency: context on all calls, translations complete, types up to date", {
+		src: z.string().default("src").describe("Source directory to scan"),
+		sourceLocale: z.string().default("en").describe("Source locale code"),
+		out: z.string().default("locales").describe("Locale files directory")
+	}, async ({ src, sourceLocale, out }) => {
+		const srcDir = path.resolve(cwd(), src);
+		const outDir = localesDir(out);
+		const localePath = path.join(outDir, `${sourceLocale}.jsonc`);
+		const typesPath = path.resolve(cwd(), "lingo.d.ts");
+		const filePaths = await findSourceFiles(srcDir);
+		const { messages, warnings } = runExtractionPipeline(await Promise.all(filePaths.map(async (f) => ({
+			code: await fs.readFile(f, "utf-8"),
+			filePath: path.relative(cwd(), f)
+		}))));
+		const entries = toLocaleEntries(messages);
+		const existingJsoncContent = await tryReadFile(localePath) ?? "";
+		const merged = mergeEntries(existingJsoncContent ? readLocaleFile(existingJsoncContent) : { entries: [] }, entries);
+		const generatedJsonc = writeLocaleFile(merged);
+		const generatedTypes = generateTypes(merged);
+		const existingTypes = await tryReadFile(typesPath) ?? "";
+		const targetLocales = await discoverLocales(outDir, sourceLocale).catch(() => []);
+		const targetFiles = await Promise.all(targetLocales.map(async (locale) => {
+			const content = await tryReadFile(path.join(outDir, `${locale}.jsonc`));
+			return {
+				locale,
+				file: content ? readLocaleFile(content) : { entries: [] }
+			};
+		}));
+		const result = runChecks({
+			warnings,
+			messageCount: messages.length,
+			generatedJsonc,
+			existingJsonc: existingJsoncContent,
+			generatedTypes,
+			existingTypes,
+			sourceFile: merged,
+			targetFiles
+		});
+		return withUpdateNudge({
+			content: [{
+				type: "text",
+				text: JSON.stringify(result, null, 2)
+			}],
+			...result.issues.length > 0 ? { isError: true } : {}
+		});
+	});
+	for (const prompt of Object.values(PROMPTS)) server.prompt(prompt.name, prompt.description, prompt.arguments, async () => ({ messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: prompt.text
+		}
+	}] }));
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+//#endregion
+export { startMcpServer };