From 115a6590294e33fa62b1648717bef4be3977c3a9 Mon Sep 17 00:00:00 2001 From: Artur Date: Thu, 29 Jan 2026 12:52:32 +0100 Subject: [PATCH] feat(compiler): add deprecation warnings for legacy compiler --- .changeset/legacy-compiler-deprecation.md | 14 +++ .claude/settings.local.json | 7 ++ packages/cli/README.md | 2 + packages/compiler/README.md | 93 ++++++++++++++++++- packages/compiler/src/_deprecation.ts | 23 +++++ packages/compiler/src/_loader-utils.ts | 6 ++ packages/compiler/src/index.ts | 58 ++++++++++-- .../compiler/src/lingo-turbopack-loader.ts | 6 ++ 8 files changed, 199 insertions(+), 10 deletions(-) create mode 100644 .changeset/legacy-compiler-deprecation.md create mode 100644 .claude/settings.local.json create mode 100644 packages/compiler/src/_deprecation.ts diff --git a/.changeset/legacy-compiler-deprecation.md b/.changeset/legacy-compiler-deprecation.md new file mode 100644 index 000000000..62fbd37b0 --- /dev/null +++ b/.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 diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 000000000..715e55ea3 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,7 @@ +{ + "permissions": { + "allow": [ + "Bash(pnpm build:*)" + ] + } +} diff --git a/packages/cli/README.md b/packages/cli/README.md index fdd3cd28f..a3e788fd4 100644 --- a/packages/cli/README.md +++ b/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 diff --git a/packages/compiler/README.md b/packages/compiler/README.md index 8452bf574..f8fd445b7 100644 --- a/packages/compiler/README.md +++ b/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 { + 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: https://lingo.dev/compiler diff --git a/packages/compiler/src/_deprecation.ts b/packages/compiler/src/_deprecation.ts new file mode 100644 index 000000000..0f21034b8 --- /dev/null +++ b/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); +} diff --git a/packages/compiler/src/_loader-utils.ts b/packages/compiler/src/_loader-utils.ts index 0cb29548c..eb37ba253 100644 --- a/packages/compiler/src/_loader-utils.ts +++ b/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; diff --git a/packages/compiler/src/index.ts b/packages/compiler/src/index.ts index ef758b00e..ed2ef142c 100644 --- a/packages/compiler/src/index.ts +++ b/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 | 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 { + * 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) => (config: any) => { + showDeprecationWarning(); const mergedParams = _.merge( {}, defaultParams, diff --git a/packages/compiler/src/lingo-turbopack-loader.ts b/packages/compiler/src/lingo-turbopack-loader.ts index 456a24164..2c94e9deb 100644 --- a/packages/compiler/src/lingo-turbopack-loader.ts +++ b/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";