@langapi/mcp-server 1.0.0

package/dist/api/client.js

@@ -0,0 +1,145 @@
+/**
+ * LangAPI client for making API requests
+ */
+import { API_BASE_URL, getApiKey } from "../config/env.js";
+/** Default request timeout in milliseconds (30 seconds) */
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Type guard for SyncDryRunResponse
+ */
+function isSyncDryRunResponse(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const obj = data;
+    return (obj.success === true &&
+        typeof obj.delta === "object" &&
+        obj.delta !== null &&
+        typeof obj.cost === "object" &&
+        obj.cost !== null &&
+        "wordsToTranslate" in obj.cost);
+}
+/**
+ * Type guard for SyncExecuteResponse
+ */
+function isSyncExecuteResponse(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const obj = data;
+    return (obj.success === true &&
+        Array.isArray(obj.results) &&
+        typeof obj.cost === "object" &&
+        obj.cost !== null &&
+        "creditsUsed" in obj.cost);
+}
+export class LangAPIClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(apiKey, baseUrl = API_BASE_URL, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * Create a client instance using the configured API key
+     * @throws Error if no API key is configured
+     */
+    static create() {
+        const apiKey = getApiKey();
+        if (!apiKey) {
+            throw new Error("No API key configured. Set the LANGAPI_API_KEY environment variable.");
+        }
+        return new LangAPIClient(apiKey);
+    }
+    /**
+     * Check if client can be created (API key is configured)
+     */
+    static canCreate() {
+        return !!getApiKey();
+    }
+    /**
+     * Sync translations with the LangAPI service
+     */
+    async sync(request) {
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(`${this.baseUrl}/api/v1/sync`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(request),
+                signal: controller.signal,
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                // Parse error response safely
+                const errorObj = typeof data === "object" && data !== null
+                    ? data
+                    : {};
+                const errorData = typeof errorObj.error === "object" && errorObj.error !== null
+                    ? errorObj.error
+                    : {};
+                return {
+                    success: false,
+                    error: {
+                        code: typeof errorData.code === "string" ? errorData.code : "API_ERROR",
+                        message: typeof errorData.message === "string"
+                            ? errorData.message
+                            : `HTTP ${response.status}`,
+                        currentBalance: typeof errorData.currentBalance === "number"
+                            ? errorData.currentBalance
+                            : undefined,
+                        requiredCredits: typeof errorData.requiredCredits === "number"
+                            ? errorData.requiredCredits
+                            : undefined,
+                        topUpUrl: typeof errorData.topUpUrl === "string"
+                            ? errorData.topUpUrl
+                            : undefined,
+                    },
+                };
+            }
+            // Validate successful response using type guards
+            if (isSyncDryRunResponse(data)) {
+                return data;
+            }
+            if (isSyncExecuteResponse(data)) {
+                return data;
+            }
+            // Unknown response format
+            return {
+                success: false,
+                error: {
+                    code: "INVALID_RESPONSE",
+                    message: "API returned an unexpected response format",
+                },
+            };
+        }
+        catch (error) {
+            // Handle timeout and network errors
+            if (error instanceof Error && error.name === "AbortError") {
+                return {
+                    success: false,
+                    error: {
+                        code: "TIMEOUT",
+                        message: `Request timed out after ${this.timeoutMs}ms`,
+                    },
+                };
+            }
+            return {
+                success: false,
+                error: {
+                    code: "NETWORK_ERROR",
+                    message: error instanceof Error ? error.message : "Unknown network error",
+                },
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/api/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * API request/response types for LangAPI
+ * These types match the langapi-api sync endpoint
+ */
+export interface KeyValue {
+    key: string;
+    value: string;
+}
+export interface SyncRequest {
+    source_lang: string;
+    target_langs: string[];
+    content: KeyValue[];
+    dry_run: boolean;
+}
+export interface SyncDelta {
+    newKeys: string[];
+    changedKeys: string[];
+    unchangedKeys: string[];
+    totalKeysToSync: number;
+}
+export interface SyncCostEstimate {
+    wordsToTranslate: number;
+    creditsRequired: number;
+    currentBalance: number;
+    balanceAfterSync: number;
+}
+export interface SyncDryRunResponse {
+    success: true;
+    delta: SyncDelta;
+    cost: SyncCostEstimate;
+}
+export interface SyncLanguageResult {
+    language: string;
+    translatedCount: number;
+    translations: KeyValue[];
+}
+export interface SyncExecuteResponse {
+    success: true;
+    results: SyncLanguageResult[];
+    cost: {
+        creditsUsed: number;
+        balanceAfterSync: number;
+    };
+}
+export interface SyncErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        currentBalance?: number;
+        requiredCredits?: number;
+        topUpUrl?: string;
+    };
+}
+export type SyncResponse = SyncDryRunResponse | SyncExecuteResponse | SyncErrorResponse;
+//# sourceMappingURL=types.d.ts.map

package/dist/api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAGD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAGD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAGD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,QAAQ,EAAE,CAAC;CAC1B;AAGD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,IAAI,EAAE;QACJ,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAGD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAGD,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,mBAAmB,GACnB,iBAAiB,CAAC"}

package/dist/api/types.js

@@ -0,0 +1,6 @@
+/**
+ * API request/response types for LangAPI
+ * These types match the langapi-api sync endpoint
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/config/env.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Environment variable configuration for LangAPI MCP Server
+ */
+export declare const API_BASE_URL: string;
+/**
+ * Get the API key from environment variable
+ * @returns The API key or null if not configured
+ */
+export declare function getApiKey(): string | null;
+/**
+ * Check if the API key is configured
+ */
+export declare function isApiKeyConfigured(): boolean;
+/**
+ * Get masked API key for display (shows first 10 and last 4 chars)
+ */
+export declare function getMaskedApiKey(): string | null;
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,YAAY,QACgC,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAK/C"}

package/dist/config/env.js

@@ -0,0 +1,29 @@
+/**
+ * Environment variable configuration for LangAPI MCP Server
+ */
+export const API_BASE_URL = process.env.LANGAPI_API_URL || "https://api.langapi.io";
+/**
+ * Get the API key from environment variable
+ * @returns The API key or null if not configured
+ */
+export function getApiKey() {
+    return process.env.LANGAPI_API_KEY || null;
+}
+/**
+ * Check if the API key is configured
+ */
+export function isApiKeyConfigured() {
+    return !!getApiKey();
+}
+/**
+ * Get masked API key for display (shows first 10 and last 4 chars)
+ */
+export function getMaskedApiKey() {
+    const key = getApiKey();
+    if (!key)
+        return null;
+    if (key.length <= 14)
+        return "***";
+    return `${key.slice(0, 10)}...${key.slice(-4)}`;
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,YAAY,GACvB,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,wBAAwB,CAAC;AAE1D;;;GAGG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IACxB,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAClD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * LangAPI MCP Server Entry Point
+ *
+ * This MCP server enables AI assistants to manage i18n translations
+ * in developer projects via the LangAPI service.
+ *
+ * Tools available:
+ * - list_local_locales: Scan project for locale files
+ * - get_translation_status: Compare source vs target locales
+ * - sync_translations: Sync translations via LangAPI API
+ * - get_diff: Compare source against sync cache for delta detection
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG"}

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * LangAPI MCP Server Entry Point
+ *
+ * This MCP server enables AI assistants to manage i18n translations
+ * in developer projects via the LangAPI service.
+ *
+ * Tools available:
+ * - list_local_locales: Scan project for locale files
+ * - get_translation_status: Compare source vs target locales
+ * - sync_translations: Sync translations via LangAPI API
+ * - get_diff: Compare source against sync cache for delta detection
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Failed to start LangAPI MCP server:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,KAAK,CAAC,CAAC;IAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/locale-detection/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Locale detection orchestrator
+ * Detects i18n framework and locale files in a project
+ */
+export interface LocaleFile {
+    /** Absolute path to the file */
+    path: string;
+    /** Relative path from project root */
+    relativePath: string;
+    /** Namespace if applicable (from directory name) */
+    namespace: string | null;
+    /** Number of translation keys */
+    keyCount: number;
+}
+export interface DetectedLocale {
+    /** Language code */
+    lang: string;
+    /** Files for this language */
+    files: LocaleFile[];
+    /** Total key count across all files */
+    totalKeys: number;
+}
+export interface LocaleDetectionResult {
+    /** Detected framework */
+    framework: string;
+    /** Confidence level */
+    confidence: "high" | "medium" | "low";
+    /** Path to locales directory (relative) */
+    localesPath: string | null;
+    /** Detected source language */
+    sourceLang: string | null;
+    /** All detected locales */
+    locales: DetectedLocale[];
+    /** Path to i18n config file if found */
+    configFile: string | null;
+}
+/**
+ * Detect i18n framework and locale files in a project
+ */
+export declare function detectLocales(projectPath: string, includeKeyCount?: boolean): Promise<LocaleDetectionResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/locale-detection/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/locale-detection/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+BAA+B;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2BAA2B;IAC3B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,wCAAwC;IACxC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,eAAe,UAAO,GACrB,OAAO,CAAC,qBAAqB,CAAC,CAgChC"}

package/dist/locale-detection/index.js

@@ -0,0 +1,188 @@
+/**
+ * Locale detection orchestrator
+ * Detects i18n framework and locale files in a project
+ */
+import { glob } from "glob";
+import { readFile } from "fs/promises";
+import { join, basename, dirname, relative } from "path";
+import { existsSync } from "fs";
+import { FRAMEWORK_PATTERNS, isLikelyLanguageCode, } from "./patterns.js";
+import { countKeys, parseJsonSafe } from "../utils/json-parser.js";
+/**
+ * Detect i18n framework and locale files in a project
+ */
+export async function detectLocales(projectPath, includeKeyCount = true) {
+    // Try to detect framework from config files
+    const { framework, configFile, confidence } = await detectFramework(projectPath);
+    // Get the pattern for this framework
+    const pattern = FRAMEWORK_PATTERNS[framework] || FRAMEWORK_PATTERNS.generic;
+    // Find locale files
+    const localeFiles = await findLocaleFiles(projectPath, pattern);
+    // Group by language
+    const locales = await groupByLanguage(projectPath, localeFiles, includeKeyCount);
+    // Determine locales path
+    const localesPath = determineLocalesPath(localeFiles, projectPath);
+    // Try to detect source language (usually 'en' if present, or first one)
+    const sourceLang = locales.find((l) => l.lang === "en")?.lang || locales[0]?.lang || null;
+    return {
+        framework,
+        confidence,
+        localesPath,
+        sourceLang,
+        locales,
+        configFile,
+    };
+}
+/**
+ * Detect the i18n framework from config files
+ */
+async function detectFramework(projectPath) {
+    // Check frameworks in order of specificity
+    for (const [frameworkName, pattern] of Object.entries(FRAMEWORK_PATTERNS)) {
+        if (frameworkName === "generic")
+            continue;
+        for (const configFile of pattern.configFiles) {
+            const fullPath = join(projectPath, configFile);
+            if (existsSync(fullPath)) {
+                // Read file and check content pattern
+                if (pattern.configPattern) {
+                    try {
+                        const content = await readFile(fullPath, "utf-8");
+                        if (pattern.configPattern.test(content)) {
+                            return {
+                                framework: frameworkName,
+                                configFile: configFile,
+                                confidence: "high",
+                            };
+                        }
+                    }
+                    catch {
+                        // Ignore read errors
+                    }
+                }
+                else {
+                    return {
+                        framework: frameworkName,
+                        configFile: configFile,
+                        confidence: "medium",
+                    };
+                }
+            }
+        }
+    }
+    // Fall back to generic
+    return { framework: "generic", configFile: null, confidence: "low" };
+}
+/**
+ * Find locale files matching the framework patterns
+ */
+async function findLocaleFiles(projectPath, pattern) {
+    const allFiles = [];
+    for (const globPattern of pattern.localeGlobs) {
+        try {
+            const files = await glob(globPattern, {
+                cwd: projectPath,
+                absolute: true,
+                nodir: true,
+            });
+            allFiles.push(...files);
+        }
+        catch {
+            // Ignore glob errors
+        }
+    }
+    // Deduplicate
+    return [...new Set(allFiles)];
+}
+/**
+ * Group locale files by language
+ */
+async function groupByLanguage(projectPath, files, includeKeyCount) {
+    const languageMap = new Map();
+    for (const filePath of files) {
+        const lang = extractLanguageFromPath(filePath);
+        if (!lang)
+            continue;
+        let keyCount = 0;
+        if (includeKeyCount) {
+            try {
+                const content = await readFile(filePath, "utf-8");
+                const parsed = parseJsonSafe(content);
+                if (parsed) {
+                    keyCount = countKeys(parsed);
+                }
+            }
+            catch {
+                // Ignore read errors
+            }
+        }
+        const relativePath = relative(projectPath, filePath);
+        const dirName = basename(dirname(filePath));
+        const namespace = dirName !== lang && !isLikelyLanguageCode(dirName) ? dirName : null;
+        const localeFile = {
+            path: filePath,
+            relativePath,
+            namespace,
+            keyCount,
+        };
+        if (!languageMap.has(lang)) {
+            languageMap.set(lang, []);
+        }
+        languageMap.get(lang).push(localeFile);
+    }
+    // Convert to array and calculate totals
+    return Array.from(languageMap.entries()).map(([lang, files]) => ({
+        lang,
+        files,
+        totalKeys: files.reduce((sum, f) => sum + f.keyCount, 0),
+    }));
+}
+/**
+ * Extract language code from file path
+ * Supports patterns like: /locales/en.json, /messages/en/common.json, /public/locales/en/translation.json
+ */
+function extractLanguageFromPath(filePath) {
+    const parts = filePath.split("/");
+    const fileName = basename(filePath, ".json");
+    // Check if filename is a language code (e.g., en.json)
+    if (isLikelyLanguageCode(fileName)) {
+        return fileName;
+    }
+    // Check parent directories for language code
+    for (let i = parts.length - 2; i >= 0; i--) {
+        if (isLikelyLanguageCode(parts[i])) {
+            return parts[i];
+        }
+    }
+    return null;
+}
+/**
+ * Determine the common locales directory path
+ */
+function determineLocalesPath(files, projectPath) {
+    if (files.length === 0)
+        return null;
+    // Find common parent directory
+    const relativePaths = files.map((f) => relative(projectPath, f));
+    if (relativePaths.length === 0)
+        return null;
+    // Get the first path's directory parts
+    const firstDir = dirname(relativePaths[0]).split("/");
+    // Find common prefix
+    let commonParts = [...firstDir];
+    for (const relPath of relativePaths) {
+        const parts = dirname(relPath).split("/");
+        const newCommon = [];
+        for (let i = 0; i < Math.min(commonParts.length, parts.length); i++) {
+            if (commonParts[i] === parts[i]) {
+                newCommon.push(commonParts[i]);
+            }
+            else {
+                break;
+            }
+        }
+        commonParts = newCommon;
+    }
+    return commonParts.length > 0 ? commonParts.join("/") : null;
+}
+//# sourceMappingURL=index.js.map

package/dist/locale-detection/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/locale-detection/index.ts"],"names":[],"mappings":"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"}

package/dist/locale-detection/patterns.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Framework-specific patterns for detecting i18n locale files
+ */
+export interface FrameworkPattern {
+    /** Config files that identify this framework */
+    configFiles: string[];
+    /** Glob patterns for locale files */
+    localeGlobs: string[];
+    /** Regex pattern to identify framework in config content */
+    configPattern?: RegExp;
+}
+export declare const FRAMEWORK_PATTERNS: Record<string, FrameworkPattern>;
+/**
+ * Common language codes
+ */
+export declare const COMMON_LANGUAGE_CODES: string[];
+/**
+ * Check if a string looks like a language code
+ */
+export declare function isLikelyLanguageCode(str: string): boolean;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/locale-detection/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/locale-detection/patterns.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,qCAAqC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CA+D/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,UAoDjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOzD"}