@langapi/mcp-server 1.0.5 → 1.0.7

package/dist/tools/sync-translations.js

@@ -7,6 +7,7 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import { dirname, resolve } from "path";
 import { detectLocales } from "../locale-detection/index.js";
 import { flattenJson, unflattenJson, parseJsonSafe, } from "../utils/json-parser.js";
+import { isArbFile, parseArbContent, mergeArbContent, getLocaleFileExtension, } from "../utils/arb-parser.js";
 import { parseJsonWithFormat, stringifyWithFormat, } from "../utils/format-preserve.js";
 import { LangAPIClient } from "../api/client.js";
 import { isApiKeyConfigured } from "../config/env.js";
@@ -15,7 +16,7 @@ import { readSyncCache, writeSyncCache, detectLocalDelta, } from "../utils/sync-
 // Input schema
 const SyncTranslationsSchema = z.object({
     source_lang: languageCodeSchema.describe("Source language code (e.g., 'en', 'pt-BR')"),
-    target_langs: languageCodesArraySchema.describe("Target language codes to sync"),
+    target_langs: languageCodesArraySchema.describe("Target language codes to translate to. Can include NEW languages not yet in the project (e.g., ['cs', 'de'] to add Czech and German)"),
     dry_run: z
         .boolean()
         .default(true)
@@ -110,22 +111,29 @@ function removeExtraKeys(targetObj, sourceKeys) {
 /**
  * Compute target file path by replacing source language with target language.
  * Handles both directory-based (locales/en/file.json) and flat (locales/en.json) structures.
+ * Also supports Flutter ARB files with underscore naming (app_en.arb → app_ko.arb).
  */
 function computeTargetFilePath(sourcePath, sourceLang, targetLang) {
+    const ext = getLocaleFileExtension(sourcePath);
     // Try directory-based replacement first: /en/ → /ko/
     const dirPattern = `/${sourceLang}/`;
     if (sourcePath.includes(dirPattern)) {
         return sourcePath.replace(dirPattern, `/${targetLang}/`);
     }
-    // Try flat file replacement: /en.json → /ko.json
-    const filePattern = `/${sourceLang}.json`;
+    // Try flat file replacement: /en.json → /ko.json or /en.arb → /ko.arb
+    const filePattern = `/${sourceLang}${ext}`;
     if (sourcePath.endsWith(filePattern)) {
-        return sourcePath.slice(0, -filePattern.length) + `/${targetLang}.json`;
+        return sourcePath.slice(0, -filePattern.length) + `/${targetLang}${ext}`;
     }
     // Try filename with prefix: messages.en.json → messages.ko.json
-    const prefixPattern = `.${sourceLang}.json`;
+    const prefixPattern = `.${sourceLang}${ext}`;
     if (sourcePath.endsWith(prefixPattern)) {
-        return sourcePath.slice(0, -prefixPattern.length) + `.${targetLang}.json`;
+        return sourcePath.slice(0, -prefixPattern.length) + `.${targetLang}${ext}`;
+    }
+    // Try Flutter-style underscore pattern: app_en.arb → app_ko.arb
+    const underscorePattern = `_${sourceLang}${ext}`;
+    if (sourcePath.endsWith(underscorePattern)) {
+        return sourcePath.slice(0, -underscorePattern.length) + `_${targetLang}${ext}`;
     }
     // Cannot determine target path
     return null;
@@ -134,7 +142,7 @@ function computeTargetFilePath(sourcePath, sourceLang, targetLang) {
  * Register the sync_translations tool with the MCP server
  */
 export function registerSyncTranslations(server) {
-    server.tool("sync_translations", "Sync translations by calling the LangAPI /v1/sync endpoint. Default is dry_run=true (preview mode) for safety. Set dry_run=false to actually perform the sync.", SyncTranslationsSchema.shape, async (args) => {
+    server.tool("sync_translations", "Add new languages or sync existing translations via LangAPI. Use this tool to: (1) ADD translations for new languages like Czech, Spanish, French - creates new locale files automatically, (2) SYNC existing translations when source content changes. Supports any valid language code (e.g., 'cs' for Czech, 'de' for German). Default is dry_run=true for preview.", SyncTranslationsSchema.shape, async (args) => {
         const input = SyncTranslationsSchema.parse(args);
         const projectPath = input.project_path || process.cwd();
         // Check if API key is configured
@@ -171,12 +179,24 @@ export function registerSyncTranslations(server) {
             const content = await readFile(file.path, "utf-8");
             const parsed = parseJsonWithFormat(content);
             if (parsed) {
-                const flatContent = flattenJson(parsed.data);
+                let flatContent;
+                let arbMetadata;
+                if (isArbFile(file.path)) {
+                    // ARB file: extract translatable keys only, preserve metadata
+                    const arbContent = parseArbContent(parsed.data);
+                    flatContent = arbContent.translatableKeys;
+                    arbMetadata = arbContent.metadata;
+                }
+                else {
+                    // Regular JSON: flatten all keys
+                    flatContent = flattenJson(parsed.data);
+                }
                 sourceFilesData.push({
                     file,
                     content: parsed.data,
                     flatContent,
                     format: parsed.format,
+                    arbMetadata,
                 });
             }
         }
@@ -366,122 +386,139 @@ export function registerSyncTranslations(server) {
         const client = LangAPIClient.create();
         // Track skipped keys per language for reporting
         const skippedKeysReport = {};
-        // Check if we need per-language filtering
-        const hasSkipKeys = input.skip_keys && Object.keys(input.skip_keys).length > 0;
-        const hasMissingLanguages = missingLanguages.length > 0;
-        // If we have missing languages, missing files, skip_keys, OR no cache, process per-language
-        // When cache is null, we need per-language processing to filter against existing target translations
-        const hasLanguagesWithMissingFiles = languagesWithMissingFiles.length > 0;
-        const needsTargetFiltering = !cachedContent && existingLanguages.length > 0;
-        if (hasMissingLanguages || hasSkipKeys || hasLanguagesWithMissingFiles || needsTargetFiltering) {
-            // Process each language one at a time: API call → write files → next language
-            // This ensures partial results are saved immediately and not lost on error
-            let totalCreditsUsed = 0;
-            let totalWordsToTranslate = 0;
-            let currentBalance = 0;
-            // Track completed languages and their results
-            const completedResults = [];
-            const completedLanguages = [];
-            const allFilesWritten = [];
+        // ========== PER-FILE PROCESSING APPROACH ==========
+        // Process each source file separately:
+        // 1. For each source file, determine which keys need syncing
+        // 2. Make one API call per file → all target languages
+        // 3. Write to corresponding target files
+        // This ensures correct file mapping without namespace matching bugs
+        let totalCreditsUsed = 0;
+        let totalWordsToTranslate = 0;
+        let currentBalance = 0;
+        // Track results per language (aggregated across files)
+        const langResults = new Map();
+        // Initialize results for all target languages
+        for (const lang of input.target_langs) {
+            langResults.set(lang, { translated_count: 0, files_written: [] });
+        }
+        // Track completed files for partial error reporting
+        const completedFiles = [];
+        const allFilesWritten = [];
+        // Process each source file
+        for (const sourceFileData of sourceFilesData) {
+            const sourceFileKeys = new Set(sourceFileData.flatContent.map((item) => item.key));
+            // Filter delta content to only keys in this source file
+            const fileKeysInDelta = localDelta.contentToSync.filter((item) => sourceFileKeys.has(item.key));
+            // Determine which languages need this file's translations
+            // and what content to sync per language
+            const langContentMap = new Map();
             for (const targetLang of input.target_langs) {
-                // Determine base content: ALL keys for missing languages or languages with missing files
+                // Compute target file path
+                const targetFilePath = computeTargetFilePath(sourceFileData.file.path, input.source_lang, targetLang);
+                if (!targetFilePath || targetFilePath === sourceFileData.file.path) {
+                    continue;
+                }
+                const resolvedPath = resolve(targetFilePath);
+                if (!isPathWithinProject(resolvedPath, projectPath)) {
+                    continue;
+                }
+                // Determine base content for this file+language combination
                 const isMissingLang = missingLanguages.includes(targetLang);
-                const hasMissingFiles = languagesWithMissingFiles.includes(targetLang);
-                const needsFullSync = isMissingLang || hasMissingFiles;
-                let baseContent = needsFullSync ? flatContent : localDelta.contentToSync;
-                // Filter against existing target translations (not just cache)
-                // This ensures we only sync keys that are actually missing from target files
-                // Only apply when cache is null - otherwise cache delta already handles new/changed correctly
-                if (!isMissingLang && !cachedContent) {
-                    const targetLocale = detection.locales.find((l) => l.lang === targetLang);
-                    if (targetLocale && targetLocale.files.length > 0) {
-                        // Read all target files and collect existing keys
-                        const existingTargetKeys = new Set();
-                        for (const targetFile of targetLocale.files) {
-                            try {
-                                const targetContent = await readFile(targetFile.path, "utf-8");
-                                const parsed = parseJsonWithFormat(targetContent);
-                                if (parsed) {
-                                    const flatTarget = flattenJson(parsed.data);
-                                    for (const item of flatTarget) {
-                                        // Only count as "existing" if it has a non-empty value
-                                        if (item.value && item.value.trim() !== "") {
-                                            existingTargetKeys.add(item.key);
-                                        }
-                                    }
-                                }
-                            }
-                            catch {
-                                // File read failed, treat as missing
+                // Check if this specific target file exists
+                let targetFileExists = false;
+                let existingTargetKeys = new Set();
+                try {
+                    const targetContent = await readFile(resolvedPath, "utf-8");
+                    targetFileExists = true;
+                    const parsed = parseJsonWithFormat(targetContent);
+                    if (parsed) {
+                        const flatTarget = flattenJson(parsed.data);
+                        for (const item of flatTarget) {
+                            if (item.value && item.value.trim() !== "") {
+                                existingTargetKeys.add(item.key);
                             }
                         }
-                        // Filter out keys that already exist in target
-                        baseContent = baseContent.filter((item) => !existingTargetKeys.has(item.key));
                     }
                 }
-                // Apply skip_keys filter on top of base content
+                catch {
+                    // File doesn't exist
+                }
+                // Determine what content to sync
+                let contentToSync;
+                if (isMissingLang || !targetFileExists) {
+                    // New language or missing file: sync all keys from this source file
+                    contentToSync = sourceFileData.flatContent;
+                }
+                else if (!cachedContent) {
+                    // No cache: sync only keys missing from target
+                    contentToSync = sourceFileData.flatContent.filter((item) => !existingTargetKeys.has(item.key));
+                }
+                else {
+                    // Has cache: use delta, but only keys from this file
+                    contentToSync = fileKeysInDelta;
+                }
+                // Apply skip_keys filter
                 const skipSet = getSkipKeysForLang(input.skip_keys, targetLang);
-                const filteredContent = baseContent.filter((item) => !skipSet.has(item.key));
-                // Track skipped keys for this language
+                const filteredContent = contentToSync.filter((item) => !skipSet.has(item.key));
+                // Track skipped keys
                 if (skipSet.size > 0) {
-                    const skippedInContent = baseContent
+                    const skippedInContent = contentToSync
                         .filter((item) => skipSet.has(item.key))
                         .map((item) => item.key);
                     if (skippedInContent.length > 0) {
-                        skippedKeysReport[targetLang] = skippedInContent;
+                        const existing = skippedKeysReport[targetLang] || [];
+                        skippedKeysReport[targetLang] = [...new Set([...existing, ...skippedInContent])];
                     }
                 }
-                // Skip API call if no content after filtering
-                if (filteredContent.length === 0) {
-                    completedResults.push({
-                        language: targetLang,
-                        translated_count: 0,
-                        skipped_keys: skippedKeysReport[targetLang],
-                        file_written: null,
-                    });
-                    completedLanguages.push(targetLang);
-                    continue;
+                if (filteredContent.length > 0) {
+                    langContentMap.set(targetLang, filteredContent);
                 }
-                // Make API call for this language
-                const response = await client.sync({
-                    source_lang: input.source_lang,
-                    target_langs: [targetLang],
-                    content: filteredContent,
-                    dry_run: input.dry_run,
-                });
-                // Handle API error - return immediately (previous languages already saved)
-                if (!response.success) {
-                    const currentIndex = input.target_langs.indexOf(targetLang);
-                    const remainingLangs = input.target_langs.slice(currentIndex + 1);
-                    // Return partial error with info about completed languages
-                    if (completedLanguages.length > 0) {
-                        const output = {
-                            success: false,
-                            partial_results: {
-                                languages_completed: completedLanguages,
-                                files_written: allFilesWritten,
-                                credits_used: totalCreditsUsed,
-                            },
-                            error: {
-                                code: response.error.code,
-                                message: response.error.message,
-                                failed_language: targetLang,
-                                remaining_languages: remainingLangs,
-                                current_balance: response.error.currentBalance,
-                                required_credits: response.error.requiredCredits,
-                                top_up_url: response.error.topUpUrl,
-                            },
-                        };
-                        return {
-                            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
-                        };
-                    }
-                    // No completed languages - return simple error
+            }
+            // Skip API call if no languages need this file
+            if (langContentMap.size === 0) {
+                completedFiles.push(sourceFileData.file.path);
+                continue;
+            }
+            // Collect all unique keys to sync for this file (union across all languages)
+            const allKeysToSync = new Set();
+            for (const content of langContentMap.values()) {
+                for (const item of content) {
+                    allKeysToSync.add(item.key);
+                }
+            }
+            // Get source content for these keys
+            const contentForApi = sourceFileData.flatContent.filter((item) => allKeysToSync.has(item.key));
+            if (contentForApi.length === 0) {
+                completedFiles.push(sourceFileData.file.path);
+                continue;
+            }
+            // Make API call for this file → all languages that need it
+            const langsNeedingSync = Array.from(langContentMap.keys());
+            const response = await client.sync({
+                source_lang: input.source_lang,
+                target_langs: langsNeedingSync,
+                content: contentForApi,
+                dry_run: input.dry_run,
+            });
+            // Handle API error
+            if (!response.success) {
+                // Return partial error with info about completed files
+                if (completedFiles.length > 0) {
+                    const completedLangs = Array.from(langResults.entries())
+                        .filter(([_, r]) => r.translated_count > 0 || r.files_written.length > 0)
+                        .map(([lang]) => lang);
                     const output = {
                         success: false,
+                        partial_results: {
+                            languages_completed: completedLangs,
+                            files_written: allFilesWritten,
+                            credits_used: totalCreditsUsed,
+                        },
                         error: {
                             code: response.error.code,
                             message: response.error.message,
+                            failed_language: langsNeedingSync[0],
+                            remaining_languages: langsNeedingSync,
                             current_balance: response.error.currentBalance,
                             required_credits: response.error.requiredCredits,
                             top_up_url: response.error.topUpUrl,
@@ -491,209 +528,46 @@ export function registerSyncTranslations(server) {
                         content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
                     };
                 }
-                // Handle dry run response - just accumulate costs
-                if ("delta" in response && response.cost) {
-                    totalWordsToTranslate += response.cost.wordsToTranslate || 0;
-                    totalCreditsUsed += response.cost.creditsRequired || 0;
-                    currentBalance = response.cost.currentBalance || 0;
-                    completedLanguages.push(targetLang);
-                    continue;
-                }
-                // Handle execute response - write files immediately for this language
-                if ("results" in response && response.cost) {
-                    totalCreditsUsed += response.cost.creditsUsed || 0;
-                    currentBalance = response.cost.balanceAfterSync || 0;
-                    const result = response.results[0];
-                    if (!result) {
-                        continue;
-                    }
-                    const filesWrittenForLang = [];
-                    // Write files for this language if requested
-                    if (input.write_to_files) {
-                        // Check if target locale exists (use detected files)
-                        const targetLocale = detection.locales.find((l) => l.lang === targetLang);
-                        for (const sourceFileData of sourceFilesData) {
-                            // Compute target file path
-                            let targetFilePath = null;
-                            if (targetLocale && targetLocale.files.length > 0) {
-                                // Use existing detected target file path
-                                // Match by namespace or use first file for single-file projects
-                                const matchingFile = targetLocale.files.find((f) => f.namespace === sourceFileData.file.namespace) || targetLocale.files[0];
-                                targetFilePath = matchingFile.path;
-                            }
-                            else {
-                                // New language - compute path from source
-                                targetFilePath = computeTargetFilePath(sourceFileData.file.path, input.source_lang, targetLang);
-                            }
-                            // Safety check: prevent overwriting source file
-                            if (!targetFilePath || targetFilePath === sourceFileData.file.path) {
-                                continue;
-                            }
-                            const resolvedPath = resolve(targetFilePath);
-                            if (!isPathWithinProject(resolvedPath, projectPath)) {
-                                continue;
-                            }
-                            // Get keys that belong to this source file
-                            const sourceFileKeys = new Set(sourceFileData.flatContent.map((item) => item.key));
-                            // Filter translations to only those from this source file
-                            const fileTranslations = result.translations.filter((t) => sourceFileKeys.has(t.key));
-                            if (fileTranslations.length === 0) {
-                                continue;
-                            }
-                            // Read existing target file content (if exists)
-                            let existingContent = {};
-                            try {
-                                const existingFileContent = await readFile(resolvedPath, "utf-8");
-                                const parsed = parseJsonSafe(existingFileContent);
-                                if (parsed) {
-                                    existingContent = parsed;
-                                }
-                            }
-                            catch {
-                                // File doesn't exist yet, start with empty object
-                            }
-                            // Unflatten and merge translations
-                            const newTranslations = unflattenJson(fileTranslations);
-                            let mergedContent = deepMerge(existingContent, newTranslations);
-                            mergedContent = removeExtraKeys(mergedContent, sourceFileKeys);
-                            // Write file
-                            await mkdir(dirname(resolvedPath), { recursive: true });
-                            const fileContent = stringifyWithFormat(mergedContent, sourceFileData.format);
-                            await writeFile(resolvedPath, fileContent, "utf-8");
-                            filesWrittenForLang.push(resolvedPath);
-                            allFilesWritten.push(resolvedPath);
-                        }
-                    }
-                    completedResults.push({
-                        language: targetLang,
-                        translated_count: result.translatedCount,
-                        skipped_keys: skippedKeysReport[targetLang],
-                        file_written: filesWrittenForLang.length > 0 ? filesWrittenForLang.join(", ") : null,
-                    });
-                    completedLanguages.push(targetLang);
-                    // Update cache after each successful language write
-                    if (input.write_to_files) {
-                        await writeSyncCache(projectPath, input.source_lang, flatContent);
-                    }
-                }
-            }
-            // All languages processed successfully
-            // Handle dry run response
-            if (input.dry_run) {
-                const skippedMsg = Object.keys(skippedKeysReport).length > 0
-                    ? ` Skipped keys: ${JSON.stringify(skippedKeysReport)}`
-                    : "";
                 const output = {
-                    success: true,
-                    dry_run: true,
-                    delta: {
-                        new_keys: localDelta.newKeys,
-                        changed_keys: localDelta.changedKeys,
-                        total_keys_to_sync: localDelta.contentToSync.length,
+                    success: false,
+                    error: {
+                        code: response.error.code,
+                        message: response.error.message,
+                        current_balance: response.error.currentBalance,
+                        required_credits: response.error.requiredCredits,
+                        top_up_url: response.error.topUpUrl,
                     },
-                    cost: {
-                        words_to_translate: totalWordsToTranslate,
-                        credits_required: totalCreditsUsed,
-                        current_balance: currentBalance,
-                        balance_after_sync: currentBalance - totalCreditsUsed,
-                    },
-                    message: `Preview: ${localDelta.contentToSync.length} keys to sync, ${totalCreditsUsed} credits required.${skippedMsg} Run with dry_run=false to execute.`,
                 };
                 return {
                     content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
                 };
             }
-            // Return success with all completed results
-            const skippedMsg = Object.keys(skippedKeysReport).length > 0
-                ? ` Skipped: ${JSON.stringify(skippedKeysReport)}`
-                : "";
-            const totalTranslated = completedResults.reduce((sum, r) => sum + r.translated_count, 0);
-            const output = {
-                success: true,
-                dry_run: false,
-                results: completedResults,
-                cost: {
-                    credits_used: totalCreditsUsed,
-                    balance_after_sync: currentBalance,
-                },
-                message: `Sync complete. ${totalTranslated} keys translated across ${completedLanguages.length} languages.${skippedMsg}`,
-            };
-            return {
-                content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
-            };
-        }
-        // No skip_keys - use batch approach
-        const response = await client.sync({
-            source_lang: input.source_lang,
-            target_langs: input.target_langs,
-            content: localDelta.contentToSync,
-            dry_run: input.dry_run,
-        });
-        // Handle error response
-        if (!response.success) {
-            const output = {
-                success: false,
-                error: {
-                    code: response.error.code,
-                    message: response.error.message,
-                    current_balance: response.error.currentBalance,
-                    required_credits: response.error.requiredCredits,
-                    top_up_url: response.error.topUpUrl,
-                },
-            };
-            return {
-                content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
-            };
-        }
-        // Handle dry run response - use local delta for accurate new/changed detection
-        if (input.dry_run && "delta" in response) {
-            const output = {
-                success: true,
-                dry_run: true,
-                delta: {
-                    new_keys: localDelta.newKeys,
-                    changed_keys: localDelta.changedKeys,
-                    total_keys_to_sync: localDelta.contentToSync.length,
-                },
-                cost: {
-                    words_to_translate: response.cost.wordsToTranslate,
-                    credits_required: response.cost.creditsRequired,
-                    current_balance: response.cost.currentBalance,
-                    balance_after_sync: response.cost.balanceAfterSync,
-                },
-                message: `Preview: ${localDelta.contentToSync.length} keys to sync (${localDelta.newKeys.length} new, ${localDelta.changedKeys.length} changed), ${response.cost.creditsRequired} credits required. Run with dry_run=false to execute.`,
-            };
-            return {
-                content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
-            };
-        }
-        // Handle execute response
-        if ("results" in response) {
-            const results = [];
-            // Write translated content to files if requested
-            if (input.write_to_files) {
+            // Handle dry run response - accumulate costs
+            if ("delta" in response && response.cost) {
+                totalWordsToTranslate += response.cost.wordsToTranslate || 0;
+                totalCreditsUsed += response.cost.creditsRequired || 0;
+                currentBalance = response.cost.currentBalance || 0;
+                completedFiles.push(sourceFileData.file.path);
+                continue;
+            }
+            // Handle execute response - write files
+            if ("results" in response && response.cost) {
+                totalCreditsUsed += response.cost.creditsUsed || 0;
+                currentBalance = response.cost.balanceAfterSync || 0;
+                // Write translations for each language
                 for (const result of response.results) {
-                    const lang = result.language;
-                    const filesWritten = [];
-                    // Write to each source file's corresponding target file
-                    for (const sourceFileData of sourceFilesData) {
-                        // Compute target file path
-                        const targetFilePath = computeTargetFilePath(sourceFileData.file.path, input.source_lang, lang);
-                        // Skip if path computation failed or would overwrite source
-                        if (!targetFilePath || targetFilePath === sourceFileData.file.path) {
-                            continue;
-                        }
-                        const resolvedPath = resolve(targetFilePath);
-                        if (!isPathWithinProject(resolvedPath, projectPath)) {
-                            continue;
-                        }
-                        // Get the keys that belong to this source file
-                        const sourceFileKeys = new Set(sourceFileData.flatContent.map((item) => item.key));
-                        // Filter translations to only those from this source file
-                        const fileTranslations = result.translations.filter((t) => sourceFileKeys.has(t.key));
-                        if (fileTranslations.length === 0) {
-                            continue;
-                        }
+                    const targetLang = result.language;
+                    // Always compute target path from source (no namespace matching!)
+                    const targetFilePath = computeTargetFilePath(sourceFileData.file.path, input.source_lang, targetLang);
+                    if (!targetFilePath || targetFilePath === sourceFileData.file.path) {
+                        continue;
+                    }
+                    const resolvedPath = resolve(targetFilePath);
+                    if (!isPathWithinProject(resolvedPath, projectPath)) {
+                        continue;
+                    }
+                    if (input.write_to_files) {
+                        let mergedContent;
                         // Read existing target file content (if exists)
                         let existingContent = {};
                         try {
@@ -706,58 +580,84 @@ export function registerSyncTranslations(server) {
                         catch {
                             // File doesn't exist yet, start with empty object
                         }
-                        // Unflatten the new translations
-                        const newTranslations = unflattenJson(fileTranslations);
-                        // Deep merge: new translations override existing ones
-                        let mergedContent = deepMerge(existingContent, newTranslations);
-                        // Remove any keys in target that don't exist in this source file
-                        mergedContent = removeExtraKeys(mergedContent, sourceFileKeys);
-                        // Ensure directory exists
+                        if (isArbFile(resolvedPath) && sourceFileData.arbMetadata) {
+                            // ARB file: merge with existing, preserve metadata, update locale
+                            mergedContent = mergeArbContent(existingContent, result.translations, sourceFileData.arbMetadata, sourceFileKeys, targetLang);
+                        }
+                        else {
+                            // Regular JSON: merge and remove extra keys
+                            const newTranslations = unflattenJson(result.translations);
+                            mergedContent = deepMerge(existingContent, newTranslations);
+                            mergedContent = removeExtraKeys(mergedContent, sourceFileKeys);
+                        }
+                        // Write file
                         await mkdir(dirname(resolvedPath), { recursive: true });
-                        // Write file with format preservation
                         const fileContent = stringifyWithFormat(mergedContent, sourceFileData.format);
                         await writeFile(resolvedPath, fileContent, "utf-8");
-                        filesWritten.push(resolvedPath);
+                        allFilesWritten.push(resolvedPath);
+                        // Update per-language results
+                        const langResult = langResults.get(targetLang);
+                        langResult.translated_count += result.translatedCount;
+                        langResult.files_written.push(resolvedPath);
+                    }
+                    else {
+                        // Just track count without writing
+                        const langResult = langResults.get(targetLang);
+                        langResult.translated_count += result.translatedCount;
                     }
-                    results.push({
-                        language: lang,
-                        translated_count: result.translatedCount,
-                        file_written: filesWritten.length > 0 ? filesWritten.join(", ") : null,
-                    });
-                }
-            }
-            else {
-                for (const result of response.results) {
-                    results.push({
-                        language: result.language,
-                        translated_count: result.translatedCount,
-                        file_written: null,
-                    });
                 }
+                completedFiles.push(sourceFileData.file.path);
             }
-            // Update cache with current source content after successful sync
+        }
+        // Update cache after all files processed
+        if (input.write_to_files && !input.dry_run) {
             await writeSyncCache(projectPath, input.source_lang, flatContent);
+        }
+        // Build final response
+        if (input.dry_run) {
             const output = {
                 success: true,
-                dry_run: false,
-                results,
+                dry_run: true,
+                delta: {
+                    new_keys: localDelta.newKeys,
+                    changed_keys: localDelta.changedKeys,
+                    total_keys_to_sync: localDelta.contentToSync.length,
+                },
                 cost: {
-                    credits_used: response.cost.creditsUsed,
-                    balance_after_sync: response.cost.balanceAfterSync,
+                    words_to_translate: totalWordsToTranslate,
+                    credits_required: totalCreditsUsed,
+                    current_balance: currentBalance,
+                    balance_after_sync: currentBalance - totalCreditsUsed,
                 },
-                message: `Sync complete. ${response.results.reduce((sum, r) => sum + r.translatedCount, 0)} keys translated across ${response.results.length} languages. ${response.cost.creditsUsed} credits used.`,
+                message: `Preview: ${localDelta.contentToSync.length} keys to sync across ${sourceFilesData.length} file(s), ${totalCreditsUsed} credits required. Run with dry_run=false to execute.`,
             };
             return {
                 content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
             };
         }
-        // Fallback error
+        // Build results array from aggregated per-language data
+        const results = [];
+        for (const [lang, data] of langResults) {
+            results.push({
+                language: lang,
+                translated_count: data.translated_count,
+                skipped_keys: skippedKeysReport[lang],
+                file_written: data.files_written.length > 0 ? data.files_written.join(", ") : null,
+            });
+        }
+        const totalTranslated = results.reduce((sum, r) => sum + r.translated_count, 0);
+        const skippedMsg = Object.keys(skippedKeysReport).length > 0
+            ? ` Skipped: ${JSON.stringify(skippedKeysReport)}`
+            : "";
         const output = {
-            success: false,
-            error: {
-                code: "UNEXPECTED_RESPONSE",
-                message: "Unexpected response from API",
+            success: true,
+            dry_run: false,
+            results,
+            cost: {
+                credits_used: totalCreditsUsed,
+                balance_after_sync: currentBalance,
             },
+            message: `Sync complete. ${totalTranslated} keys translated across ${input.target_langs.length} languages.${skippedMsg}`,
         };
         return {
             content: [{ type: "text", text: JSON.stringify(output, null, 2) }],