feat(compiler): add deprecation warnings for legacy compiler (#1934)

* feat(compiler): add deprecation warnings for legacy compiler

* chore: remove deprecated local settings file

* docs(compiler): update documentation link format in README

Author: cherkanovart

.changeset/legacy-compiler-deprecation.md

@@ -0,0 +1,14 @@
+---
+"@lingo.dev/_compiler": patch
+---
+
+Add deprecation warnings throughout legacy compiler
+
+The legacy compiler (`@lingo.dev/_compiler`) now shows deprecation warnings when used.
+Users are encouraged to migrate to the new compiler (`@lingo.dev/compiler`).
+
+Changes:
+- Added runtime deprecation warnings in `next()`, `vite()`, and the Turbopack loader
+- Added `@deprecated` JSDoc tags to all public APIs
+- Updated package README with migration guide and examples
+- The deprecation warning includes information about new compiler features and migration guide link

packages/cli/README.md

@@ -48,6 +48,8 @@
 
 **Lingo.dev Compiler** is a free, open-source compiler middleware, designed to make any React app multilingual at build time without requiring any changes to the existing React components.
 
+> **Note:** If you're using the legacy compiler (`@lingo.dev/_compiler`), please migrate to `@lingo.dev/compiler`. The legacy compiler is deprecated and will be removed in a future release.
+
 Install once:
 
 ```bash

packages/compiler/README.md

@@ -1,5 +1,92 @@
-# Lingo.dev Compiler
+# Lingo.dev Compiler (Legacy)
 
-**Lingo.dev Compiler** is a free, open-source compiler middleware, that makes React apps multilingual at build time without requiring any changes to the existing React components.
+> **DEPRECATED:** This package (`@lingo.dev/_compiler`) is deprecated. Please migrate to `@lingo.dev/compiler` (the new compiler).
 
-Documentation: https://lingo.dev/compiler
+## Migration
+
+Install the new compiler:
+
+```bash
+npm install @lingo.dev/compiler
+```
+
+Update your configuration:
+
+**Next.js (before):**
+```ts
+import lingoCompiler from "@lingo.dev/_compiler";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {};
+
+export default lingoCompiler.next({
+  sourceRoot: "app",
+  models: "lingo.dev",
+})(nextConfig);
+```
+
+**Next.js (after):**
+```ts
+import type { NextConfig } from "next";
+import { withLingo } from "@lingo.dev/compiler/next";
+
+const nextConfig: NextConfig = {};
+
+export default async function (): Promise<NextConfig> {
+  return await withLingo(nextConfig, {
+    sourceLocale: "en",
+    targetLocales: ["es", "fr"],
+    models: "lingo.dev",
+  });
+}
+```
+
+**Vite (before):**
+```ts
+import { defineConfig, type UserConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import lingoCompiler from "@lingo.dev/_compiler";
+
+const viteConfig: UserConfig = {
+  plugins: [react()],
+};
+
+export default defineConfig(() =>
+  lingoCompiler.vite({
+    models: "lingo.dev",
+  })(viteConfig)
+);
+```
+
+**Vite (after):**
+```ts
+import { defineConfig, type UserConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { withLingo } from "@lingo.dev/compiler/vite";
+
+const viteConfig: UserConfig = {
+  plugins: [react()],
+};
+
+export default defineConfig(async () =>
+  await withLingo(viteConfig, {
+    sourceLocale: "en",
+    targetLocales: ["es", "fr"],
+    models: "lingo.dev",
+  })
+);
+```
+
+## New Compiler Features
+
+The new compiler (`@lingo.dev/compiler`) offers:
+
+- Advanced virtual module system for better code splitting
+- Built-in development translation server
+- Pluralization detection with ICU MessageFormat support
+- Improved metadata management for better caching
+- Thread-safe concurrent build support
+
+## Documentation
+
+Full documentation: [lingo.dev/compiler](https://lingo.dev/compiler)

packages/compiler/src/_deprecation.ts

@@ -0,0 +1,23 @@
+const DEPRECATION_WARNING = `
+⚠️  DEPRECATION WARNING: @lingo.dev/_compiler is deprecated.
+   Please migrate to @lingo.dev/compiler (the new compiler).
+
+   The new compiler offers:
+   • Advanced virtual module system for better code splitting
+   • Built-in development translation server
+   • Pluralization detection with ICU MessageFormat support
+   • Improved metadata management for better caching
+   • Thread-safe concurrent build support
+
+   Migration guide: https://lingo.dev/compiler
+
+   This legacy compiler will be removed in a future release.
+`;
+
+let deprecationWarningShown = false;
+
+export function showDeprecationWarning() {
+  if (deprecationWarningShown) return;
+  deprecationWarningShown = true;
+  console.warn(DEPRECATION_WARNING);
+}

packages/compiler/src/_loader-utils.ts

@@ -23,6 +23,9 @@ import { parseParametrizedModuleId } from "./utils/module-params";
 
 /**
  * Loads a dictionary for a specific locale
+ *
+ * @deprecated This function is part of the legacy compiler (@lingo.dev/_compiler).
+ * Please migrate to @lingo.dev/compiler. See https://lingo.dev/compiler
  */
 export async function loadDictionary(options: {
   resourcePath: string;
@@ -79,6 +82,9 @@ export async function loadDictionary(options: {
 
 /**
  * Transforms component code
+ *
+ * @deprecated This function is part of the legacy compiler (@lingo.dev/_compiler).
+ * Please migrate to @lingo.dev/compiler. See https://lingo.dev/compiler
  */
 export function transformComponent(options: {
   code: string;

packages/compiler/src/index.ts

@@ -19,6 +19,7 @@ import {
 } from "./utils/llm-api-key";
 import { isRunningInCIOrDocker } from "./utils/env";
 import { providerDetails } from "./lib/lcp/api/provider-details";
+import { showDeprecationWarning } from "./_deprecation";
 import { loadDictionary, transformComponent } from "./_loader-utils";
 import trackEvent from "./utils/observability";
 
@@ -61,6 +62,7 @@ function sendBuildEvent(framework: string, config: any, isDev: boolean) {
 
 const unplugin = createUnplugin<Partial<typeof defaultParams> | undefined>(
   (_params, _meta) => {
+    showDeprecationWarning();
     console.log("ℹ️  Starting Lingo.dev compiler...");
 
     const params = _.defaults(_params, defaultParams);
@@ -155,13 +157,32 @@ export default {
   /**
    * Initializes Lingo.dev Compiler for Next.js (App Router).
    *
+   * @deprecated This legacy compiler is deprecated. Please migrate to `@lingo.dev/compiler`.
+   * See migration guide at https://lingo.dev/compiler
+   *
    * @param compilerParams - The compiler parameters.
    *
    * @returns The Next.js configuration.
    *
-   * @example Configuration for Next.js's default template
+   * @example New compiler usage (recommended):
    * ```ts
-   * import lingoCompiler from "lingo.dev/compiler";
+   * import type { NextConfig } from "next";
+   * import { withLingo } from "@lingo.dev/compiler/next";
+   *
+   * const nextConfig: NextConfig = {};
+   *
+   * export default async function (): Promise<NextConfig> {
+   *   return await withLingo(nextConfig, {
+   *     sourceLocale: "en",
+   *     targetLocales: ["es", "fr"],
+   *     models: "lingo.dev",
+   *   });
+   * }
+   * ```
+   *
+   * @example Legacy compiler usage (deprecated):
+   * ```ts
+   * import lingoCompiler from "@lingo.dev/_compiler";
    * import type { NextConfig } from "next";
    *
    * const nextConfig: NextConfig = {
@@ -184,6 +205,7 @@ export default {
       },
     ) =>
     (nextConfig: any = {}): NextConfig => {
+      showDeprecationWarning();
       const mergedParams = _.merge(
         {},
         defaultParams,
@@ -272,17 +294,38 @@ export default {
   /**
    * Initializes Lingo.dev Compiler for Vite.
    *
+   * @deprecated This legacy compiler is deprecated. Please migrate to `@lingo.dev/compiler`.
+   * See migration guide at https://lingo.dev/compiler
+   *
    * @param compilerParams - The compiler parameters.
    *
    * @returns The Vite configuration.
    *
-   * @example Configuration for Vite's "react-ts" template
+   * @example New compiler usage (recommended):
+   * ```ts
+   * import { defineConfig, type UserConfig } from "vite";
+   * import react from "@vitejs/plugin-react";
+   * import { withLingo } from "@lingo.dev/compiler/vite";
+   *
+   * const viteConfig: UserConfig = {
+   *   plugins: [react()],
+   * };
+   *
+   * export default defineConfig(async () =>
+   *   await withLingo(viteConfig, {
+   *     sourceLocale: "en",
+   *     targetLocales: ["es", "fr"],
+   *     models: "lingo.dev",
+   *   })
+   * );
+   * ```
+   *
+   * @example Legacy Vite configuration (deprecated):
    * ```ts
    * import { defineConfig, type UserConfig } from "vite";
    * import react from "@vitejs/plugin-react";
-   * import lingoCompiler from "lingo.dev/compiler";
+   * import lingoCompiler from "@lingo.dev/_compiler";
    *
-   * // https://vite.dev/config/
    * const viteConfig: UserConfig = {
    *   plugins: [react()],
    * };
@@ -294,11 +337,11 @@ export default {
    * );
    * ```
    *
-   * @example Configuration for React Router's default template
+   * @example Legacy React Router configuration (deprecated):
    * ```ts
    * import { reactRouter } from "@react-router/dev/vite";
    * import tailwindcss from "@tailwindcss/vite";
-   * import lingoCompiler from "lingo.dev/compiler";
+   * import lingoCompiler from "@lingo.dev/_compiler";
    * import { defineConfig, type UserConfig } from "vite";
    * import tsconfigPaths from "vite-tsconfig-paths";
    *
@@ -315,6 +358,7 @@ export default {
    * ```
    */
   vite: (compilerParams?: Partial<typeof defaultParams>) => (config: any) => {
+    showDeprecationWarning();
     const mergedParams = _.merge(
       {},
       defaultParams,

packages/compiler/src/lingo-turbopack-loader.ts

@@ -1,7 +1,13 @@
+import { showDeprecationWarning } from "./_deprecation";
 import { loadDictionary, transformComponent } from "./_loader-utils";
 
+/**
+ * @deprecated This loader is part of the legacy compiler. Please migrate to @lingo.dev/compiler.
+ * See migration guide at https://lingo.dev/compiler
+ */
 // This loader handles component transformations and dictionary generation
 export default async function (this: any, source: string) {
+  showDeprecationWarning();
   const callback = this.async();
   const params = this.getOptions();
   const isDev = process.env.NODE_ENV !== "production";