fix: use clean temporary metadata for the build

Author: AleksandrSl

cmp/compiler/src/metadata/manager.ts

@@ -27,8 +27,11 @@ export function createEmptyMetadata(): MetadataSchema {
 /**
  * Get the path to the metadata file
  */
-export function getMetadataPath(config: MetadataConfig): string {
-  return getMetadataPathUtil(config);
+export function getMetadataPath(
+  config: MetadataConfig,
+  filename?: string,
+): string {
+  return getMetadataPathUtil(config, filename);
 }
 
 /**
@@ -38,8 +41,9 @@ export function getMetadataPath(config: MetadataConfig): string {
  */
 export async function loadMetadata(
   config: MetadataConfig,
+  filename?: string,
 ): Promise<MetadataSchema> {
-  const metadataPath = getMetadataPath(config);
+  const metadataPath = getMetadataPath(config, filename);
 
   try {
     const content = await withTimeout(
@@ -64,8 +68,9 @@ export async function loadMetadata(
 export async function saveMetadata(
   config: MetadataConfig,
   metadata: MetadataSchema,
+  filename?: string,
 ): Promise<void> {
-  const metadataPath = getMetadataPath(config);
+  const metadataPath = getMetadataPath(config, filename);
   await withTimeout(
     fs.mkdir(path.dirname(metadataPath), { recursive: true }),
     DEFAULT_TIMEOUTS.FILE_IO,
@@ -90,13 +95,15 @@ export async function saveMetadata(
  *
  * @param config - Metadata configuration
  * @param entries - Translation entries to add/update
+ * @param filename - Optional custom metadata filename
  * @returns The updated metadata schema
  */
 export async function saveMetadataWithEntries(
   config: MetadataConfig,
   entries: TranslationEntry[],
+  filename?: string,
 ): Promise<MetadataSchema> {
-  const metadataPath = getMetadataPath(config);
+  const metadataPath = getMetadataPath(config, filename);
   const lockDir = path.dirname(metadataPath);
 
   // Ensure directory exists before locking
@@ -125,13 +132,13 @@ export async function saveMetadataWithEntries(
 
   try {
     // Re-load metadata inside lock to get latest state
-    const currentMetadata = await loadMetadata(config);
+    const currentMetadata = await loadMetadata(config, filename);
 
     // Apply updates
     const updatedMetadata = upsertEntries(currentMetadata, entries);
 
     // Save
-    await saveMetadata(config, updatedMetadata);
+    await saveMetadata(config, updatedMetadata, filename);
 
     return updatedMetadata;
   } finally {

cmp/compiler/src/plugin/build-translator.ts

@@ -26,6 +26,12 @@ export interface BuildTranslationOptions {
    * If not provided, files won't be generated
    */
   publicOutputPath?: string;
+
+  /**
+   * Custom metadata filename for build mode
+   * If not provided, uses default metadata.json
+   */
+  metadataFilename?: string;
 }
 
 export interface BuildTranslationResult {
@@ -60,7 +66,7 @@ export interface BuildTranslationResult {
 export async function processBuildTranslations(
   options: BuildTranslationOptions,
 ): Promise<BuildTranslationResult> {
-  const { config, publicOutputPath } = options;
+  const { config, publicOutputPath, metadataFilename } = options;
 
   // Determine build mode (env var > options > config)
   const buildMode =
@@ -69,7 +75,7 @@ export async function processBuildTranslations(
 
   logger.info(`🌍 Build mode: ${buildMode}`);
 
-  const metadata = await loadMetadata(config);
+  const metadata = await loadMetadata(config, metadataFilename);
 
   if (!metadata || Object.keys(metadata.entries).length === 0) {
     logger.info("No translations to process (metadata is empty)");

cmp/compiler/src/plugin/next.ts

@@ -11,9 +11,17 @@ import { logger } from "../utils/logger";
 import type { PartialLingoConfig } from "../types";
 import { lingoUnplugin } from "./unplugin";
 import { useI18nRegex } from "./transform/use-i18n";
+import {
+  generateBuildMetadataFilename,
+  getMetadataPath,
+} from "../utils/path-helpers";
+import * as fs from "fs/promises";
 
 export type LingoNextPluginOptions = PartialLingoConfig;
 
+// Track build metadata filename per config (use WeakMap for memory safety)
+const buildMetadataFilenames = new WeakMap<PartialLingoConfig, string>();
+
 /**
  * Check if Next.js supports stable turbopack config (Next.js 16+)
  */
@@ -70,6 +78,10 @@ function buildLingoConfig(
 ): NextConfig {
   const lingoConfig = createLingoConfig(lingoOptions);
 
+  // Generate timestamped metadata filename for build mode
+  const buildMetadataFilename = generateBuildMetadataFilename();
+  buildMetadataFilenames.set(lingoOptions, buildMetadataFilename);
+
   // Prepare Turbopack loader configuration
   const loaderConfig = {
     loader: "@lingo.dev/compiler/turbopack-loader",
@@ -78,6 +90,7 @@ function buildLingoConfig(
       lingoDir: lingoConfig.lingoDir,
       sourceLocale: lingoConfig.sourceLocale,
       useDirective: lingoConfig.useDirective,
+      buildMetadataFilename,
     },
   };
 
@@ -201,14 +214,32 @@ function buildLingoConfig(
     }
 
     logger.info("Running post-build translation generation...");
+    logger.info(
+      `Build mode: Using temporary metadata file: ${buildMetadataFilename}`,
+    );
 
     try {
       const { processBuildTranslations } = await import("./build-translator");
 
       await processBuildTranslations({
         config: lingoConfig,
         publicOutputPath: distDir,
+        metadataFilename: buildMetadataFilename,
       });
+
+      // Cleanup: Remove temporary build metadata file
+      const metadataPath = getMetadataPath(lingoConfig, buildMetadataFilename);
+      try {
+        await fs.unlink(metadataPath);
+        logger.info(
+          `🧹 Cleaned up temporary metadata file: ${buildMetadataFilename}`,
+        );
+      } catch (error: any) {
+        // Ignore if file doesn't exist
+        if (error.code !== "ENOENT") {
+          logger.warn(`Failed to cleanup metadata file: ${error.message}`);
+        }
+      }
     } catch (error) {
       logger.error("Translation generation failed:", error);
       throw error;

cmp/compiler/src/plugin/turbopack-loader.ts

@@ -23,7 +23,8 @@ export default async function lingoCompilerTurbopackLoader(
   const isDev = process.env.NODE_ENV === "development";
 
   try {
-    const config: LingoConfig = this.getOptions();
+    const config: LingoConfig & { buildMetadataFilename: string } =
+      this.getOptions();
 
     // TODO (AleksandrSl 07/12/2025): Remove too I think
     // Check if this file should be transformed
@@ -44,11 +45,13 @@ export default async function lingoCompilerTurbopackLoader(
     }
 
     // Load current metadata
-    const metadata = await loadMetadata(config);
+    // In build mode, use timestamped metadata file; in dev mode, use default
+    const metadataFilename = isDev ? undefined : config.buildMetadataFilename;
+    const metadata = await loadMetadata(config, metadataFilename);
     // Update metadata with new entries
     if (result.newEntries && result.newEntries.length > 0) {
       const updatedMetadata = upsertEntries(metadata, result.newEntries);
-      await saveMetadata(config, updatedMetadata);
+      await saveMetadata(config, updatedMetadata, metadataFilename);
 
       // Log new translations discovered (in dev mode)
       // Note: In production, translations are generated after build via runAfterProductionCompile

cmp/compiler/src/plugin/unplugin.ts

@@ -22,7 +22,11 @@ import {
 import { saveMetadataWithEntries } from "../metadata/manager";
 import { createLingoConfig } from "../utils/config-factory";
 import { logger } from "../utils/logger";
-import { getCacheDir } from "../utils/path-helpers";
+import {
+  generateBuildMetadataFilename,
+  getCacheDir,
+  getMetadataPath,
+} from "../utils/path-helpers";
 import { useI18nRegex } from "./transform/use-i18n";
 import {
   generateClientLocaleCode,
@@ -34,6 +38,7 @@ import * as fs from "fs";
 export type LingoPluginOptions = PartialLingoConfig;
 
 let globalServer: TranslationServer;
+let buildMetadataFilename: string | undefined;
 
 /**
  * Universal plugin for Lingo.dev compiler
@@ -51,6 +56,16 @@ export const lingoUnplugin = createUnplugin<LingoPluginOptions>((options) => {
 
     // Start translation server on build start (dev mode only)
     async buildStart() {
+      // Generate timestamped metadata filename for build mode
+      if (!isDev) {
+        buildMetadataFilename = generateBuildMetadataFilename();
+        logger.info(
+          `Build mode: Using temporary metadata file: ${buildMetadataFilename}`,
+        );
+      } else {
+        buildMetadataFilename = undefined;
+      }
+
       // Only start translation server in development mode
       if (isDev && !globalServer) {
         globalServer = await startTranslationServer({
@@ -172,7 +187,12 @@ export function persistLocale(locale) {
 
             // TODO (AleksandrSl 30/11/2025): Could make async in the future, so we don't pause the main transform, translation server should be able to know if the metadata is finished writing then.
             // Thread-safe atomic update
-            await saveMetadataWithEntries(config, result.newEntries);
+            // In build mode, use timestamped metadata file; in dev mode, use default
+            await saveMetadataWithEntries(
+              config,
+              result.newEntries,
+              buildMetadataFilename,
+            );
 
             // Log new translations discovered (in dev mode)
             if (isDev) {
@@ -206,7 +226,27 @@ export function persistLocale(locale) {
           await processBuildTranslations({
             config,
             publicOutputPath: "public/translations",
+            metadataFilename: buildMetadataFilename,
           });
+
+          // Cleanup: Remove temporary build metadata file
+          if (buildMetadataFilename) {
+            const metadataPath = getMetadataPath(config, buildMetadataFilename);
+            try {
+              await fs.promises.unlink(metadataPath);
+              logger.info(
+                `🧹 Cleaned up temporary metadata file: ${buildMetadataFilename}`,
+              );
+            } catch (error: any) {
+              // Ignore if file doesn't exist
+              if (error.code !== "ENOENT") {
+                logger.warn(
+                  `Failed to cleanup metadata file: ${error.message}`,
+                );
+              }
+            }
+            buildMetadataFilename = undefined;
+          }
         } catch (error) {
           logger.error("Build-time translation processing failed:", error);
           throw error;

cmp/compiler/src/utils/path-helpers.ts

@@ -32,17 +32,39 @@ export function resolveAbsolutePath(
  * Get the absolute path to the metadata.json file
  *
  * @param config - Config with sourceRoot and lingoDir
- * @returns Absolute path to metadata.json
+ * @param filename - Optional custom filename (defaults to "metadata.json")
+ * @returns Absolute path to metadata file
  *
  * @example
  * ```typescript
  * getMetadataPath({ sourceRoot: "src", lingoDir: ".lingo" })
  * // -> "/full/path/to/src/.lingo/metadata.json"
+ *
+ * getMetadataPath({ sourceRoot: "src", lingoDir: ".lingo" }, "metadata.build-123456.json")
+ * // -> "/full/path/to/src/.lingo/metadata.build-123456.json"
  * ```
  */
-export function getMetadataPath(config: PathConfig): string {
+export function getMetadataPath(
+  config: PathConfig,
+  filename: string = "metadata.json",
+): string {
   const rootPath = resolveAbsolutePath(config.sourceRoot);
-  return path.join(rootPath, config.lingoDir, "metadata.json");
+  return path.join(rootPath, config.lingoDir, filename);
+}
+
+/**
+ * Generate a unique build metadata filename with timestamp
+ *
+ * @returns Filename like "metadata.build-1701234567890.json"
+ *
+ * @example
+ * ```typescript
+ * generateBuildMetadataFilename()
+ * // -> "metadata.build-1701234567890.json"
+ * ```
+ */
+export function generateBuildMetadataFilename(): string {
+  return `metadata.build-${Date.now()}.json`;
 }
 
 /**