feat: move translation service initialization to see the logs

We don't really need to initialize it inside the server,
since server is only a way to use the service in the dev mode.

Logs of the server are written to a file due to it being started
from process which doesn't have access to console.
But we want to see TranslationService initialization logs
in the console, and the clearest way is to start it early,
rather than extracting validation into a separate function.

Author: AleksandrSl

packages/new-compiler/src/plugin/build-translator.ts

@@ -11,12 +11,9 @@ import fs from "fs/promises";
 import path from "path";
 import type { LingoConfig, MetadataSchema } from "../types";
 import { logger } from "../utils/logger";
-import {
-  startTranslationServer,
-  type TranslationServer,
-} from "../translation-server";
+import { startTranslationServer, type TranslationServer, } from "../translation-server";
 import { loadMetadata } from "../metadata/manager";
-import { createCache, type TranslationCache } from "../translators";
+import { createCache, type TranslationCache, TranslationService, } from "../translators";
 import { dictionaryFrom } from "../translators/api";
 import type { LocaleCode } from "lingo.dev/spec";
 
@@ -108,7 +105,7 @@ export async function processBuildTranslations(
 
   try {
     translationServer = await startTranslationServer({
-      startPort: config.dev.translationServerStartPort,
+      translationService: new TranslationService(config, logger),
       onError: (err) => {
         logger.error("Translation server error:", err);
       },

packages/new-compiler/src/plugin/next.ts

@@ -12,6 +12,7 @@ import { startOrGetTranslationServer } from "../translation-server/translation-s
 import { cleanupExistingMetadata, getMetadataPath } from "../metadata/manager";
 import { registerCleanupOnCurrentProcess } from "./cleanup";
 import { useI18nRegex } from "./transform/use-i18n";
+import { TranslationService } from "../translators";
 
 export type LingoNextPluginOptions = PartialLingoConfig;
 
@@ -205,14 +206,12 @@ export async function withLingo(
     `Initializing Lingo.dev compiler. Is dev mode: ${isDev}. Is main runner: ${isMainRunner()}`,
   );
 
-  // TODO (AleksandrSl 12/12/2025): Add API keys validation too, so we can log it nicely.
-
   // Try to start up the translation server once.
   // We have two barriers, a simple one here and a more complex one inside the startTranslationServer which doesn't start the server if it can find one running.
   // We do not use isMainRunner here, because we need to start the server as early as possible, so the loaders get the translation server url. The main runner in dev mode runs after a dev server process is started.
   if (isDev && !process.env.LINGO_TRANSLATION_SERVER_URL) {
     const translationServer = await startOrGetTranslationServer({
-      startPort: lingoConfig.dev.translationServerStartPort,
+      translationService: new TranslationService(lingoConfig, logger),
       onError: (err) => {
         logger.error("Translation server error:", err);
       },

packages/new-compiler/src/plugin/unplugin.ts

@@ -26,6 +26,7 @@ import { processBuildTranslations } from "./build-translator";
 import { registerCleanupOnCurrentProcess } from "./cleanup";
 import path from "path";
 import fs from "fs";
+import { TranslationService } from "../translators";
 
 export type LingoPluginOptions = PartialLingoConfig;
 
@@ -112,7 +113,7 @@ export const lingoUnplugin = createUnplugin<
 
   async function startServer() {
     const server = await startTranslationServer({
-      startPort,
+      translationService: new TranslationService(config, logger),
       onError: (err) => {
         logger.error("Translation server error:", err);
       },

packages/new-compiler/src/translation-server/cli.ts

@@ -444,7 +444,6 @@ export async function main(): Promise<void> {
 
     // Start server
     const { server, url } = await startOrGetTranslationServer({
-      startPort,
       config,
       // requestTimeout: cliOpts.timeout || 30000,
       onError: (err) => {

packages/new-compiler/src/translation-server/translation-server.ts

@@ -17,11 +17,7 @@ import { URL } from "url";
 import { WebSocket, WebSocketServer } from "ws";
 import type { MetadataSchema, TranslationMiddlewareConfig } from "../types";
 import { getLogger } from "./logger";
-import {
-  createCache,
-  createTranslator,
-  TranslationService,
-} from "../translators";
+import { TranslationService } from "../translators";
 import {
   createEmptyMetadata,
   getMetadataPath,
@@ -33,38 +29,21 @@ import type { LocaleCode } from "lingo.dev/spec";
 import { parseLocaleOrThrow } from "../utils/is-valid-locale";
 
 export interface TranslationServerOptions {
-  /**
-   * Starting port to try (will find next available if taken)
-   * @default 3456
-   */
-  startPort?: number;
-
-  /**
-   * Configuration for translation generation
-   */
   config: TranslationMiddlewareConfig;
-
-  /**
-   * Callback when server is ready
-   */
+  translationService?: TranslationService;
   onReady?: (port: number) => void;
-
-  /**
-   * Callback on error
-   */
   onError?: (error: Error) => void;
 }
 
 export class TranslationServer {
   private server: http.Server | null = null;
   private url: string | undefined = undefined;
   private logger;
-  private config: TranslationMiddlewareConfig;
-  private configHash: string;
-  private startPort: number;
-  private onReadyCallback?: (port: number) => void;
-  private onErrorCallback?: (error: Error) => void;
-  private translationService: TranslationService | null = null;
+  private readonly config: TranslationMiddlewareConfig;
+  private readonly configHash: string;
+  private readonly startPort: number;
+  private readonly onReadyCallback?: (port: number) => void;
+  private readonly onErrorCallback?: (error: Error) => void;
   private metadata: MetadataSchema | null = null;
   private connections: Set<Socket> = new Set();
   private wss: WebSocketServer | null = null;
@@ -75,11 +54,16 @@ export class TranslationServer {
   private isBusy = false;
   private busyTimeout: NodeJS.Timeout | null = null;
   private readonly BUSY_DEBOUNCE_MS = 500; // Time after last translation to send "idle" event
+  private readonly translationService: TranslationService;
 
   constructor(options: TranslationServerOptions) {
     this.config = options.config;
     this.configHash = hashConfig(options.config);
-    this.startPort = options.startPort || 60000;
+    this.translationService =
+      options.translationService ??
+      // Fallback is for CLI start only.
+      new TranslationService(options.config, getLogger(options.config));
+    this.startPort = options.config.dev.translationServerStartPort;
     this.onReadyCallback = options.onReady;
     this.onErrorCallback = options.onError;
     this.logger = getLogger(this.config);
@@ -95,19 +79,6 @@ export class TranslationServer {
 
     this.logger.info(`🔧 Initializing translator...`);
 
-    const translator = createTranslator(this.config, this.logger);
-    const cache = createCache(this.config);
-
-    this.translationService = new TranslationService(
-      translator,
-      cache,
-      {
-        sourceLocale: this.config.sourceLocale,
-        pluralization: this.config.pluralization,
-      },
-      this.logger,
-    );
-
     const port = await this.findAvailablePort(this.startPort);
 
     return new Promise((resolve, reject) => {
@@ -281,14 +252,13 @@ export class TranslationServer {
    * Start a new server or get the URL of an existing one on the preferred port.
    *
    * This method optimizes for the common case where a translation server is already
-   * running on port 60000. If that port is taken, it checks if it's our service
+   * running on a preferred port. If that port is taken, it checks if it's our service
    * by calling the health check endpoint. If it is, we reuse it instead of starting
    * a new server on a different port.
    *
    * @returns URL of the running server (new or existing)
    */
   async startOrGetUrl(): Promise<string> {
-    // If this instance already has a server running, return its URL
     if (this.server && this.url) {
       this.logger.info(`Using existing server instance at ${this.url}`);
       return this.url;
@@ -527,7 +497,6 @@ export class TranslationServer {
 
         res.on("end", () => {
           try {
-            // Check if response is valid and has the expected structure
             if (res.statusCode === 200) {
               const json = JSON.parse(data);
               // Our translation server returns { status: "ok", port: ..., configHash: ... }
@@ -680,11 +649,6 @@ export class TranslationServer {
         );
         return;
       }
-
-      if (!this.translationService) {
-        throw new Error("Translation service not initialized");
-      }
-
       // Reload metadata to ensure we have the latest entries
       // (new entries may have been added since server started)
       await this.reloadMetadata();
@@ -747,10 +711,6 @@ export class TranslationServer {
     try {
       const parsedLocale = parseLocaleOrThrow(locale);
 
-      if (!this.translationService) {
-        throw new Error("Translation service not initialized");
-      }
-
       // Reload metadata to ensure we have the latest entries
       // (new entries may have been added since server started)
       await this.reloadMetadata();
@@ -842,9 +802,6 @@ export function hashConfig(config: Record<string, SerializableValue>): string {
   return crypto.createHash("md5").update(serialized).digest("hex").slice(0, 12);
 }
 
-/**
- * Create and start a translation server
- */
 export async function startTranslationServer(
   options: TranslationServerOptions,
 ): Promise<TranslationServer> {
@@ -856,10 +813,10 @@ export async function startTranslationServer(
 /**
  * Create a translation server and start it or reuse an existing one on the preferred port
  *
- * Since we have little control over the dev server start in next, we can start the translation server only in the loader,
- * and loaders could be started from multiple processes (it seems) or similar we need a way to avoid starting multiple servers.
+ * Since we have little control over the dev server start in next, we can start the translation server only in the async config or in the loader,
+ * they both could be run in different processes, and we need a way to avoid starting multiple servers.
  * This one will try to start a server on the preferred port (which seems to be an atomic operation), and if it fails,
- * it checks if the server already started is ours and returns its url.
+ * it checks if the server that is already started is ours and returns its url.
  *
  * @returns Object containing the server instance and its URL
  */

packages/new-compiler/src/translators/cache-factory.ts

@@ -8,6 +8,8 @@ import { LocalTranslationCache } from "./local-cache";
 import { logger } from "../utils/logger";
 import { getCacheDir } from "../utils/path-helpers";
 
+export type CacheConfig = Pick<LingoConfig, "cacheType"> & PathConfig;
+
 /**
  * Create a cache instance based on the config
  *
@@ -21,7 +23,7 @@ import { getCacheDir } from "../utils/path-helpers";
  * ```
  */
 export function createCache(
-  config: Pick<LingoConfig, "cacheType"> & PathConfig,
+  config: CacheConfig,
 ): TranslationCache {
   switch (config.cacheType) {
     case "local":

packages/new-compiler/src/translators/index.ts

@@ -9,9 +9,8 @@ export type { Translator, TranslatableEntry } from "./api";
 
 // Translators
 export { PseudoTranslator } from "./pseudotranslator";
-export { Service } from "./lingo";
+export { LingoTranslator } from "./lingo";
 export type { LingoTranslatorConfig } from "./lingo";
-export { createTranslator } from "./translator-factory";
 
 // Translation Service (orchestrator)
 export { TranslationService } from "./translation-service";

packages/new-compiler/src/translators/lingo/index.ts

@@ -4,5 +4,5 @@
  * Real AI-powered translation using various LLM providers
  */
 
-export { Service } from "./service";
-export type { LingoTranslatorConfig } from "./service";
+export { LingoTranslator } from "./translator";
+export type { LingoTranslatorConfig } from "./translator";

…ompiler/src/translators/lingo/service.ts …iler/src/translators/lingo/translator.tspackages/new-compiler/src/translators/lingo/service.ts renamed to packages/new-compiler/src/translators/lingo/translator.ts packages/new-compiler/src/translators/lingo/service.ts renamed to packages/new-compiler/src/translators/lingo/translator.ts

@@ -31,7 +31,7 @@ export interface LingoTranslatorConfig {
 /**
  * Lingo translator using AI models
  */
-export class Service implements Translator<LingoTranslatorConfig> {
+export class LingoTranslator implements Translator<LingoTranslatorConfig> {
   private readonly validatedKeys: ValidatedApiKeys;
 
   constructor(

packages/new-compiler/src/translators/memory-cache.ts

@@ -0,0 +1,67 @@
+import type { TranslationCache } from "./cache";
+import type { LocaleCode } from "lingo.dev/spec";
+
+/**
+ * In memory translation cache implementation
+ */
+export class MemoryTranslationCache implements TranslationCache {
+  private cache: Map<LocaleCode, Map<string, string>> = new Map();
+
+  constructor() {}
+
+  async get(
+    locale: LocaleCode,
+    hashes?: string[],
+  ): Promise<Record<string, string>> {
+    const localeCache = this.cache.get(locale);
+    if (!localeCache) {
+      return {};
+    }
+    if (hashes) {
+      return hashes.reduce(
+        (acc, hash) => ({ ...acc, [hash]: localeCache.get(hash) }),
+        {},
+      );
+    }
+    return Object.fromEntries(localeCache);
+  }
+
+  /**
+   * Update cache with new translations (merge)
+   */
+  async update(
+    locale: LocaleCode,
+    translations: Record<string, string>,
+  ): Promise<void> {
+    let localeCache = this.cache.get(locale);
+    if (!localeCache) {
+      localeCache = new Map();
+      this.cache.set(locale, localeCache);
+    }
+    for (const [key, value] of Object.entries(translations)) {
+      localeCache.set(key, value);
+    }
+  }
+
+  /**
+   * Replace entire cache for a locale
+   */
+  async set(
+    locale: LocaleCode,
+    translations: Record<string, string>,
+  ): Promise<void> {
+    this.cache.set(locale, new Map(Object.entries(translations)));
+  }
+
+  async has(locale: LocaleCode): Promise<boolean> {
+    return this.cache.has(locale);
+  }
+
+  async clear(locale: LocaleCode): Promise<void> {
+    this.cache.delete(locale);
+  }
+
+  async clearAll(): Promise<void> {
+    this.cache.clear();
+  }
+}