WIP: move environment detection to config and start webpack work

Author: AleksandrSl

cmp/compiler/src/metadata/manager.ts

@@ -44,13 +44,13 @@ export function cleanupExistingMetadata(metadataFilePath: string) {
 /**
  * Get the absolute path to the metadata file
  *
- * @param config - Config with sourceRoot and lingoDir
+ * @param config - Config with sourceRoot, lingoDir, and environment
  * @returns Absolute path to metadata file
  */
 export function getMetadataPath(config: PathConfig): string {
   const filename =
     // Similar to next keeping dev build separate, let's keep the build metadata clean of any dev mode additions
-    process.env.NODE_ENV === "development"
+    config.environment === "development"
       ? "metadata-dev.json"
       : "metadata-build.json";
   return path.join(getLingoDir(config), filename);

cmp/compiler/src/plugin/next.ts

@@ -82,7 +82,7 @@ export async function withLingo(
 ): Promise<NextConfig> {
   const lingoConfig = createLingoConfig(lingoOptions);
   let metadataFilePath = getMetadataPath(lingoConfig);
-  const isDev = process.env.NODE_ENV === "development";
+  const isDev = lingoConfig.environment === "development";
 
   logger.debug(
     `Initializing Lingo.dev compiler. Is dev mode: ${isDev}. Is main runner: ${isMainRunner()}`,

cmp/compiler/src/plugin/unplugin.ts

@@ -16,7 +16,11 @@ import {
   startTranslationServer,
   type TranslationServer,
 } from "../translation-server";
-import { getMetadataPath, MetadataManager } from "../metadata/manager";
+import {
+  cleanupExistingMetadata,
+  getMetadataPath,
+  MetadataManager,
+} from "../metadata/manager";
 import { createLingoConfig } from "../utils/config-factory";
 import { logger } from "../utils/logger";
 import { getCacheDir } from "../utils/path-helpers";
@@ -36,60 +40,29 @@ let translationServer: TranslationServer;
 
 const PLUGIN_NAME = "lingo-compiler";
 
-export async function cleanup(
-  server: TranslationServer | undefined,
-  metadataFilePath: string,
-) {
-  // General cleanup. Delete metadata and stop the server if any was started.
-  logger.debug(`Attempting to cleanup metadata file: ${metadataFilePath}`);
-
-  try {
-    fs.unlinkSync(metadataFilePath);
-    logger.info(`🧹 Cleaned up build metadata file: ${metadataFilePath}`);
-  } catch (error: any) {
-    // Ignore if file doesn't exist
-    if (error.code === "ENOENT") {
-      logger.debug(
-        `Metadata file already deleted or doesn't exist: ${metadataFilePath}`,
-      );
-    } else {
-      logger.warn(`Failed to cleanup metadata file: ${error.message}`);
-    }
-  }
-
-  if (server) {
-    logger.debug("Stopping translation server...");
-    await server.stop();
-    logger.info("Translation server stopped");
-  }
-}
-
 /**
  * Universal plugin for Lingo.dev compiler
  * Supports Vite, Webpack, Rollup, and esbuild
  */
 export const lingoUnplugin = createUnplugin<LingoPluginOptions>((options) => {
   const config = createLingoConfig(options);
 
-  const isDev = process.env.NODE_ENV === "development";
+  // Won't work for webpack most likely. Use mode there to set correct environment in configs.
+  const isDev = config.environment === "development";
   const startPort = config.dev.translationServerStartPort;
   const metadataFilePath = getMetadataPath(config);
 
-  // Warn if NODE_ENV is not set (common webpack issue)
-  if (!process.env.NODE_ENV) {
-    logger.warn(
-      "⚠️  process.env.NODE_ENV is undefined. Lingo will assume production mode.\n" +
-        "   For webpack users: Add webpack.DefinePlugin to set process.env.NODE_ENV.\n" +
-        "   See: https://webpack.js.org/plugins/define-plugin/",
-    );
-  }
-
   return {
     name: PLUGIN_NAME,
     enforce: "pre", // Run before other plugins (especially before React plugin)
 
     vite: {
       async buildStart() {
+        cleanupExistingMetadata(metadataFilePath);
+
+        registerCleanupOnCurrentProcess({
+          cleanup: () => cleanupExistingMetadata(metadataFilePath),
+        });
         if (isDev && !translationServer) {
           translationServer = await startTranslationServer({
             startPort,
@@ -112,7 +85,6 @@ export const lingoUnplugin = createUnplugin<LingoPluginOptions>((options) => {
         }
       },
 
-      // Doesn't fire when error happens
       async buildEnd() {
         if (!isDev) {
           try {
@@ -123,15 +95,64 @@ export const lingoUnplugin = createUnplugin<LingoPluginOptions>((options) => {
             });
           } catch (error) {
             logger.error("Build-time translation processing failed:", error);
-            // throw error;
           }
         }
-
-        logger.warn("Build end");
-        await cleanup(translationServer, metadataFilePath);
       },
     },
 
+    webpack(compiler) {
+      // if (config.isEmbeddedIntoNext) {
+      //   return;
+      // }
+      compiler.hooks.watchRun.tapPromise(PLUGIN_NAME, async () => {
+        cleanupExistingMetadata(metadataFilePath);
+        registerCleanupOnCurrentProcess({
+          cleanup: () => cleanupExistingMetadata(metadataFilePath),
+        });
+
+        if (compiler.options.mode === "development" && !translationServer) {
+          translationServer = await startTranslationServer({
+            startPort,
+            onError: (err) => {
+              logger.error("Translation server error:", err);
+            },
+            onReady: (port) => {
+              logger.info(
+                `Translation server started successfully on port: ${port}`,
+              );
+            },
+            config: { ...config, environment: compiler.options.mode },
+          });
+          registerCleanupOnCurrentProcess({
+            asyncCleanup: async () => {
+              await translationServer.stop();
+            },
+          });
+        }
+      });
+
+      compiler.hooks.additionalPass.tapPromise(PLUGIN_NAME, async () => {
+        if (compiler.options.mode === "production") {
+          try {
+            await processBuildTranslations({
+              config: { ...config, environment: compiler.options.mode },
+              publicOutputPath: "public/translations",
+              metadataFilePath: metadataFilePath,
+            });
+          } catch (error) {
+            logger.error("Build-time translation processing failed:", error);
+            throw error;
+          }
+        }
+      });
+
+      // Duplicates process handlers, but won't hurt
+      compiler.hooks.shutdown.tapPromise(PLUGIN_NAME, async () => {
+        cleanupExistingMetadata(metadataFilePath);
+        await translationServer?.stop();
+      });
+    },
+
     resolveId(id) {
       if (id === "@lingo.dev/compiler/dev-config") {
         // Return a virtual module ID (prefix with \0 to mark it as virtual)
@@ -169,6 +190,7 @@ export const lingoUnplugin = createUnplugin<LingoPluginOptions>((options) => {
     },
 
     load(id) {
+      logger.warn(`ID: ${id}`);
       if (id === "\0virtual:lingo-dev-config") {
         const serverUrl =
           translationServer?.getUrl() || `http://127.0.0.1:${startPort}`;
@@ -218,6 +240,7 @@ export function persistLocale(locale) {
       },
       handler: async (code, id) => {
         try {
+          // TODO (AleksandrSl 13/12/2025): How do I get Webpack mode here?
           // Transform the component
           const result = transformComponent({
             code,
@@ -243,7 +266,6 @@ export function persistLocale(locale) {
 
             await metadataManager.saveMetadataWithEntries(result.newEntries);
 
-            // Log new translations discovered (in dev mode)
             if (isDev) {
               logger.info(
                 `Found ${result.newEntries.length} translatable text(s) in ${id}`,

cmp/compiler/src/translators/translator-factory.ts

@@ -15,6 +15,7 @@ export interface TranslatorFactoryConfig {
   sourceLocale: string;
   models?: "lingo.dev" | Record<string, string>;
   prompt?: string;
+  environment: "development" | "production";
   dev?: {
     usePseudotranslator?: boolean;
   };
@@ -42,7 +43,7 @@ export function createTranslator(
   config: TranslatorFactoryConfig,
   logger: Logger,
 ): Translator<any> {
-  const isDev = process.env.NODE_ENV === "development";
+  const isDev = config.environment === "development";
 
   // 1. Explicit dev override takes precedence
   if (isDev && config.dev?.usePseudotranslator) {

cmp/compiler/src/types.ts

@@ -32,12 +32,17 @@ export type LocalePersistenceConfig = { type: "cookie"; cookieName?: string };
  */
 export type LingoConfigRequiredFields = "sourceLocale" | "targetLocales";
 
+export type LingoInternalFields = "environment";
+
 /**
  * Configuration for the Lingo compiler
  */
 export type PartialLingoConfig = Pick<LingoConfig, LingoConfigRequiredFields> &
   Partial<
-    Omit<LingoConfig, LingoConfigRequiredFields | "dev"> & {
+    Omit<
+      LingoConfig,
+      LingoConfigRequiredFields | "dev" | LingoInternalFields
+    > & {
       dev: Partial<LingoConfig["dev"]>;
     }
   >;
@@ -74,6 +79,14 @@ export type LingoConfig = {
    */
   lingoDir: string;
 
+  /**
+   * Environment mode
+   * Determines metadata file naming and translator behavior
+   *
+   * @default "production"
+   */
+  environment: "development" | "production";
+
   /**
    * The locale to translate from.
    *
@@ -216,13 +229,17 @@ export type TranslationMiddlewareConfig = Pick<
   | "targetLocales"
   | "dev"
   | "pluralization"
+  | "environment"
 >;
 
 /**
  * Config needed for path operations
- * Alias for MetadataConfig (same fields)
+ * Includes environment to determine metadata file naming
  */
-export type PathConfig = Pick<LingoConfig, "sourceRoot" | "lingoDir">;
+export type PathConfig = Pick<
+  LingoConfig,
+  "sourceRoot" | "lingoDir" | "environment"
+>;
 
 export type MetadataTranslationEntry = BaseTranslationEntry<
   "metadata",

cmp/compiler/src/utils/config-factory.ts

@@ -16,7 +16,7 @@ export const DEFAULT_CONFIG = {
   useDirective: false,
   skipPatterns: [/node_modules/, /\.spec\./, /\.test\./] as RegExp[],
   dev: {
-    serverStartPort: 60000,
+    translationServerStartPort: 60000,
   },
   cookieConfig: {
     name: "locale",
@@ -32,7 +32,7 @@ export const DEFAULT_CONFIG = {
     model: "groq:llama-3.1-8b-instant",
   },
   buildMode: "translate",
-} satisfies Omit<LingoConfig, LingoConfigRequiredFields>;
+} satisfies Omit<LingoConfig, LingoConfigRequiredFields | "environment">;
 
 /**
  * Create a LoaderConfig with defaults applied
@@ -45,6 +45,8 @@ export function createLingoConfig(options: PartialLingoConfig): LingoConfig {
   return {
     ...DEFAULT_CONFIG,
     ...options,
+    environment:
+      process.env.NODE_ENV === "development" ? "development" : "production",
     dev: {
       ...DEFAULT_CONFIG.dev,
       ...options.dev,