feat: SPA build translations

Author: AleksandrSl

cmp/compiler/src/plugin/unplugin.ts

@@ -43,10 +43,10 @@ export const lingoUnplugin = createUnplugin<LingoPluginOptions>((options) => {
     name: "lingo-compiler",
     enforce: "pre", // Run before other plugins (especially before React plugin)
 
-    // Start translation server on build start
+    // Start translation server on build start (dev mode only)
     async buildStart() {
-      // Start translation server if not already running
-      if (!globalServer) {
+      // Only start translation server in development mode
+      if (isDev && !globalServer) {
         globalServer = await startTranslationServer({
           startPort,
           onError: (err) => {
@@ -144,9 +144,7 @@ export const cacheDir = ${JSON.stringify(cacheDir)};`;
 
           await processBuildTranslations({
             config,
-            // Note: publicOutputPath can be set by users in their config
-            // For Vite, this might be dist/public or public/translations
-            // For now, we don't set it here - users can handle it in their pipeline
+            publicOutputPath: "public/translations",
           });
         } catch (error) {
           logger.error("Build-time translation processing failed:", error);

cmp/compiler/src/react/shared/TranslationContext.tsx

@@ -165,15 +165,64 @@ function TranslationProvider__Prod({
   const [cookieConfig] = useState(customCookieConfig || defaultCookieConfig);
   // TODO (AleksandrSl 01/12/2025): Correctly provide default locale.
   const [locale, setLocaleState] = useState(initialLocale ?? "en");
+  const [translations, setTranslations] =
+    useState<Record<string, string>>(initialTranslations);
+  const [isLoading, setIsLoading] = useState(false);
 
   logger.debug(
     `TranslationProvider initialized with locale: ${locale}`,
     initialTranslations,
   );
 
   /**
-   * Change locale - triggers server re-render via router.refresh()
-   * Following next-intl pattern: locale changes reload the page with new translations from server
+   * Load translations from public/translations/{locale}.json
+   * Lazy loads on-demand for SPAs
+   */
+  const loadTranslations = useCallback(
+    async (targetLocale: string) => {
+      // If we already have initialTranslations (Next.js SSR), don't fetch
+      if (Object.keys(initialTranslations).length > 0) {
+        return;
+      }
+
+      setIsLoading(true);
+      try {
+        const response = await fetch(`/translations/${targetLocale}.json`);
+        if (!response.ok) {
+          throw new Error(
+            `Failed to load translations for ${targetLocale}: ${response.statusText}`,
+          );
+        }
+
+        const data = await response.json();
+        // Translation files have format: { version, locale, entries: {...} }
+        setTranslations(data.entries || data);
+        logger.debug(
+          `Loaded translations for ${targetLocale}:`,
+          Object.keys(data.entries || data).length,
+        );
+      } catch (error) {
+        logger.error(`Failed to load translations for ${targetLocale}:`, error);
+        // Fallback to empty translations
+        setTranslations({});
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [initialTranslations],
+  );
+
+  // Load translations on mount if not provided via initialTranslations
+  useEffect(() => {
+    if (Object.keys(initialTranslations).length === 0) {
+      loadTranslations(locale);
+    }
+  }, []); // Only run on mount
+
+  /**
+   * Change locale
+   * - For Next.js SSR: triggers server re-render via router.refresh()
+   * - For SPAs: lazy loads translations from /translations/{locale}.json
    */
   const setLocale = useCallback(
     async (newLocale: string) => {
@@ -183,23 +232,26 @@ function TranslationProvider__Prod({
       // 2. Update local state for immediate UI feedback
       setLocaleState(newLocale);
 
-      // 3. Trigger server re-render - Server Components will fetch new translations
-      // and pass them as initialTranslations prop, causing this component to re-render
+      // 3a. Next.js pattern: Trigger server re-render
       if (router) {
         router.refresh();
       }
+      // 3b. SPA pattern: Lazy load translations
+      else {
+        await loadTranslations(newLocale);
+      }
     },
-    [cookieConfig, router],
+    [cookieConfig, router, loadTranslations],
   );
 
   return (
     <TranslationContext.Provider
       value={{
         locale,
         setLocale,
-        translations: initialTranslations,
+        translations,
         registerHashes: () => {}, // No-op in production
-        isLoading: false, // No loading state - translations come from server
+        isLoading,
         sourceLocale,
       }}
     >

cmp/compiler/src/translation-server/translation-server.ts

@@ -12,6 +12,7 @@
  */
 
 import http from "http";
+import type { Socket } from "net";
 import { URL } from "url";
 import type { MetadataSchema, TranslationMiddlewareConfig } from "../types";
 import { getLogger } from "./logger";
@@ -55,6 +56,7 @@ export class TranslationServer {
   private onErrorCallback?: (error: Error) => void;
   private translationService: TranslationService | null = null;
   private metadata: MetadataSchema | null = null;
+  private connections: Set<Socket> = new Set();
 
   constructor(options: TranslationServerOptions) {
     this.config = options.config;
@@ -118,6 +120,14 @@ export class TranslationServer {
 
       this.logger.debug(`Starting translation server on port ${port}`);
 
+      // Track connections for graceful shutdown
+      this.server.on("connection", (socket) => {
+        this.connections.add(socket);
+        socket.once("close", () => {
+          this.connections.delete(socket);
+        });
+      });
+
       this.server.on("error", (error: NodeJS.ErrnoException) => {
         if (error.code === "EADDRINUSE") {
           // Port is in use, try next one
@@ -147,6 +157,12 @@ export class TranslationServer {
       return;
     }
 
+    // Destroy all active connections to prevent hanging
+    for (const socket of this.connections) {
+      socket.destroy();
+    }
+    this.connections.clear();
+
     return new Promise((resolve, reject) => {
       this.server!.close((error) => {
         if (error) {