lokalise_bulk_update_translations
Batch update translations by supplying translation IDs and new data. Change text, mark as reviewed or unverified, and assign custom statuses for up to 100 translations per request.
Instructions
Efficiently processes batch translation corrections or approvals. Required: projectId, updates array (up to 100). Each update needs translation_id plus changes. Use for mass approvals, systematic corrections, or importing reviewed content. Returns: Success/error per translation. Performance: ~5 updates/second with automatic rate limiting and retries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | Project ID containing the translations | |
| updates | Yes | Array of translation updates (min 1, max 100). Each update includes translationId and translationData |
Implementation Reference
- The main MCP tool handler function for lokalise_bulk_update_translations. It receives args with projectId and updates array, delegates to translationsController.bulkUpdateTranslations, and formats the response.
async function handleBulkUpdateTranslations( args: BulkUpdateTranslationsToolArgsType, ) { const methodLogger = Logger.forContext( "translations.tool.ts", "handleBulkUpdateTranslations", ); methodLogger.debug("Bulk updating translations...", { projectId: args.projectId, updateCount: args.updates.length, }); try { const result = await translationsController.bulkUpdateTranslations(args); methodLogger.debug("Got the response from the controller", result); return { content: [ { type: "text" as const, text: result.content, }, ], }; } catch (error) { methodLogger.error("Tool failed", { error: (error as Error).message, args, }); return formatErrorForMcpTool(error); } } - src/domains/translations/translations.tool.ts:210-215 (registration)Registration of the lokalise_bulk_update_translations tool with the MCP server, binding the name, description, Zod schema (BulkUpdateTranslationsToolArgs.shape), and the handler function handleBulkUpdateTranslations.
server.tool( "lokalise_bulk_update_translations", "Efficiently processes batch translation corrections or approvals. Required: projectId, updates array (up to 100). Each update needs translation_id plus changes. Use for mass approvals, systematic corrections, or importing reviewed content. Returns: Success/error per translation. Performance: ~5 updates/second with automatic rate limiting and retries.", BulkUpdateTranslationsToolArgs.shape, handleBulkUpdateTranslations, ); - BulkUpdateTranslationsToolArgs Zod schema defining input validation: projectId (string), updates (array of {translationId, translationData} min 1 max 100). Also exports BulkUpdateTranslationsToolArgsType, BulkUpdateTranslationResult, and BulkUpdateTranslationsSummary interfaces.
/** * Zod schema for bulk update translations tool arguments. * Allows updating multiple translations in a single operation. */ export const BulkUpdateTranslationsToolArgs = z .object({ projectId: z.string().describe("Project ID containing the translations"), updates: z .array( z.object({ translationId: z.number().describe("Translation ID to update"), translationData: z .object({ translation: z.string().describe("The updated translation text"), isReviewed: z .boolean() .optional() .describe("Mark translation as reviewed"), isUnverified: z .boolean() .optional() .describe("Mark translation as unverified (fuzzy)"), customTranslationStatusIds: z .array(z.number()) .optional() .describe("Array of custom translation status IDs (numeric)"), }) .describe("Translation data to update"), }), ) .min(1) .max(100) .describe( "Array of translation updates (min 1, max 100). Each update includes translationId and translationData", ), }) .strict(); export type BulkUpdateTranslationsToolArgsType = z.infer< typeof BulkUpdateTranslationsToolArgs >; - The bulkUpdate service method that processes each translation update sequentially with rate limiting (200ms delay, ~5/sec) and retry logic (max 3 attempts). Returns a BulkUpdateTranslationsSummary with per-translation results.
async bulkUpdate( args: BulkUpdateTranslationsToolArgsType, ): Promise<BulkUpdateTranslationsSummary> { const methodLogger = logger.forMethod("bulkUpdate"); methodLogger.info("Starting bulk translation update", { projectId: args.projectId, updateCount: args.updates.length, }); const startTime = Date.now(); const results: BulkUpdateTranslationResult[] = []; const RATE_LIMIT_DELAY = 200; // 200ms delay = max 5 requests/second const MAX_RETRY_ATTEMPTS = 3; const RETRY_DELAY = 1000; // 1 second delay between retries // Helper function to update a single translation with retry logic const updateWithRetry = async ( update: (typeof args.updates)[0], attemptNumber = 1, ): Promise<BulkUpdateTranslationResult> => { try { const updateArgs: UpdateTranslationToolArgsType = { projectId: args.projectId, translationId: update.translationId, translationData: update.translationData, }; const translation = await this.update(updateArgs); return { translationId: update.translationId, success: true, translation, attempts: attemptNumber, }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); if (attemptNumber < MAX_RETRY_ATTEMPTS) { methodLogger.warn( `Translation update failed, retrying (attempt ${attemptNumber}/${MAX_RETRY_ATTEMPTS})`, { translationId: update.translationId, error: errorMessage, attemptNumber, }, ); // Wait before retry await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY)); // Retry return updateWithRetry(update, attemptNumber + 1); } // Max retries reached, record as failure methodLogger.error("Translation update failed after max retries", { translationId: update.translationId, error: errorMessage, attempts: attemptNumber, }); return { translationId: update.translationId, success: false, error: errorMessage, attempts: attemptNumber, }; } }; // Process updates sequentially with rate limiting for (let i = 0; i < args.updates.length; i++) { const update = args.updates[i]; methodLogger.info( `Processing translation ${i + 1}/${args.updates.length}`, { translationId: update.translationId, }, ); // Perform the update const result = await updateWithRetry(update); results.push(result); // Rate limiting: delay before next request (except for the last one) if (i < args.updates.length - 1) { await new Promise((resolve) => setTimeout(resolve, RATE_LIMIT_DELAY)); } } // Calculate summary const duration = Date.now() - startTime; const successCount = results.filter((r) => r.success).length; const failureCount = results.filter((r) => !r.success).length; const summary: BulkUpdateTranslationsSummary = { totalRequested: args.updates.length, successCount, failureCount, results, duration, }; methodLogger.info("Bulk translation update completed", { projectId: args.projectId, totalRequested: summary.totalRequested, successCount: summary.successCount, failureCount: summary.failureCount, durationMs: summary.duration, }); return summary; }, }; - The formatBulkUpdateTranslationsResult function that formats the bulk update summary into a Markdown response showing success/failure counts, tables of successful and failed updates, and performance notes.
export function formatBulkUpdateTranslationsResult( summary: BulkUpdateTranslationsSummary, ): string { const lines: string[] = []; // Add main heading lines.push(formatHeading("Bulk Translation Update Results", 1)); lines.push(""); // Add overall summary lines.push(formatHeading("Summary", 2)); const overallSummary: Record<string, unknown> = { "Total Translations": summary.totalRequested, "Successful Updates": `${summary.successCount} (${Math.round((summary.successCount / summary.totalRequested) * 100)}%)`, "Failed Updates": `${summary.failureCount} (${Math.round((summary.failureCount / summary.totalRequested) * 100)}%)`, "Total Duration": `${(summary.duration / 1000).toFixed(2)} seconds`, "Average Time per Translation": `${(summary.duration / summary.totalRequested / 1000).toFixed(2)} seconds`, }; lines.push(formatBulletList(overallSummary)); lines.push(""); // Add successful updates section if any if (summary.successCount > 0) { lines.push(formatHeading("✅ Successful Updates", 2)); const successfulResults = summary.results.filter((r) => r.success); const successTable = successfulResults.slice(0, 10).map((result) => ({ id: result.translationId.toString(), language: result.translation?.language_iso || "N/A", reviewed: result.translation?.is_reviewed ? "✓" : "✗", attempts: result.attempts.toString(), })); const table = formatTable(successTable, [ { key: "id", header: "Translation ID" }, { key: "language", header: "Language" }, { key: "reviewed", header: "Reviewed" }, { key: "attempts", header: "Attempts" }, ]); lines.push(table); if (successfulResults.length > 10) { lines.push( `*... and ${successfulResults.length - 10} more successful updates*`, ); } lines.push(""); } // Add failed updates section if any if (summary.failureCount > 0) { lines.push(formatHeading("❌ Failed Updates", 2)); const failedResults = summary.results.filter((r) => !r.success); const failureTable = failedResults.map((result) => ({ id: result.translationId.toString(), error: result.error || "Unknown error", attempts: result.attempts.toString(), })); const table = formatTable(failureTable, [ { key: "id", header: "Translation ID" }, { key: "error", header: "Error", formatter: (v) => { const error = String(v); return error.length > 50 ? `${error.substring(0, 50)}...` : error; }, }, { key: "attempts", header: "Attempts" }, ]); lines.push(table); lines.push(""); } // Add performance notes if (summary.totalRequested > 20) { lines.push(formatHeading("Performance Notes", 2)); const performanceNotes = { "Rate Limiting": "~5 requests per second", "Retry Logic": "Up to 3 attempts per translation on failure", Recommendation: "Consider smaller batches for better performance", }; lines.push(formatBulletList(performanceNotes)); lines.push(""); } // Add footer lines.push(formatFooter("Bulk update completed")); return lines.join("\n"); }