fix: 1737 pluralization defaults (#1888)

* fix(compiler): make pluralization opt-in and infer model

BREAKING CHANGE: Pluralization is now disabled by default to avoid forcing
specific LLM provider dependencies (previously defaulted to Groq).

This fixes a case where users configuring only Google Gemini models would
get errors about missing GROQ_API_KEY because pluralization always used Groq.

Changes:
- Set pluralization.enabled default to false (was true)
- Infer pluralization model from translation models when enabled
- Make inference deterministic (stable fallback order)
- Add validation for empty models map
- Add tests for pluralization configuration

Migration:
If you were using pluralization, add "pluralization: { enabled: true }"
to your config. The model will be inferred from translation models.

Fixes #1737

* chore: add changeset for pluralization defaults

---------

Co-authored-by: Veronica Prilutskaya <veronica@lingo.dev>

Author: yashrajpatilll

.changeset/pluralization-opt-in.md

@@ -0,0 +1,5 @@
+---
+"@lingo.dev/compiler": minor
+---
+
+Make pluralization opt-in by default and infer the pluralization model from translation config.

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

@@ -110,7 +110,7 @@ export async function processBuildTranslations(
 
     // When pluralization is enabled, we need to generate the source locale file too
     // because pluralization modifies the sourceText
-    const needsSourceLocale = config.pluralization?.enabled !== false;
+    const needsSourceLocale = config.pluralization?.enabled === true;
     const allLocales = needsSourceLocale
       ? [config.sourceLocale, ...config.targetLocales]
       : config.targetLocales;
@@ -199,7 +199,7 @@ async function validateCache(
   }> = [];
 
   // Include source locale if pluralization is enabled
-  const needsSourceLocale = config.pluralization?.enabled !== false;
+  const needsSourceLocale = config.pluralization?.enabled === true;
   const allLocales = needsSourceLocale
     ? [config.sourceLocale, ...config.targetLocales]
     : config.targetLocales;
@@ -254,7 +254,7 @@ function buildCacheStats(
   const stats: BuildTranslationResult["stats"] = {};
 
   // Include source locale if pluralization is enabled
-  const needsSourceLocale = config.pluralization?.enabled !== false;
+  const needsSourceLocale = config.pluralization?.enabled === true;
   const allLocales = needsSourceLocale
     ? [config.sourceLocale, ...config.targetLocales]
     : config.targetLocales;
@@ -284,7 +284,7 @@ async function copyStaticFiles(
   logger.info(`📊 Filtering translations to ${usedHashes.size} used hash(es)`);
 
   // Include source locale if pluralization is enabled
-  const needsSourceLocale = config.pluralization?.enabled !== false;
+  const needsSourceLocale = config.pluralization?.enabled === true;
   const allLocales = needsSourceLocale
     ? [config.sourceLocale, ...config.targetLocales]
     : config.targetLocales;

packages/new-compiler/src/translators/pluralization/types.ts

@@ -23,7 +23,7 @@ export type PluralizationConfig = {
   /**
    * LLM provider for pluralization detection
    * Format: "provider:model" (e.g., "groq:llama3-8b-8192")
-   * @default "groq:llama3-8b-8192"
+   * If omitted in user config, the compiler can infer it from translation models.
    */
   model: string;
 };

packages/new-compiler/src/types.ts

@@ -35,16 +35,21 @@ export type LingoConfigRequiredFields = "sourceLocale" | "targetLocales";
 
 export type LingoInternalFields = "environment" | "cacheType";
 
+export type PartialPluralizationConfig = Partial<
+  Omit<PluralizationConfig, "sourceLocale">
+>;
+
 /**
  * Configuration for the Lingo compiler
  */
 export type PartialLingoConfig = Pick<LingoConfig, LingoConfigRequiredFields> &
   Partial<
     Omit<
       LingoConfig,
-      LingoConfigRequiredFields | "dev" | LingoInternalFields
+      LingoConfigRequiredFields | "dev" | LingoInternalFields | "pluralization"
     > & {
       dev: Partial<LingoConfig["dev"]>;
+      pluralization: PartialPluralizationConfig;
     }
   >;
 

packages/new-compiler/src/utils/config-factory.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { createLingoConfig } from "./config-factory";
+
+describe("createLingoConfig pluralization defaults", () => {
+  it("disables pluralization by default when not configured", () => {
+    const config = createLingoConfig({
+      sourceLocale: "en",
+      targetLocales: ["es"],
+    });
+
+    expect(config.pluralization.enabled).toBe(false);
+  });
+
+  it("infers pluralization model from translation models when enabled", () => {
+    const config = createLingoConfig({
+      sourceLocale: "en",
+      targetLocales: ["es"],
+      models: {
+        "*:*": "google:gemini-2.5-flash",
+      },
+      pluralization: {
+        enabled: true,
+      },
+    });
+
+    expect(config.pluralization.enabled).toBe(true);
+    expect(config.pluralization.model).toBe("google:gemini-2.5-flash");
+  });
+
+  it("prefers specific locale models over wildcard fallback", () => {
+    const config = createLingoConfig({
+      sourceLocale: "en",
+      targetLocales: ["es"],
+      models: {
+        "*:*": "google:gemini-2.5-flash",
+        "en:es": "openai:gpt-4",
+      },
+      pluralization: {
+        enabled: true,
+      },
+    });
+
+    expect(config.pluralization.model).toBe("openai:gpt-4");
+  });
+
+  it("enables pluralization when model is provided without explicit enabled", () => {
+    const config = createLingoConfig({
+      sourceLocale: "en",
+      targetLocales: ["es"],
+      models: {
+        "*:*": "google:gemini-2.5-flash",
+      },
+      pluralization: {
+        model: "groq:llama-3.1-8b-instant",
+      },
+    });
+
+    expect(config.pluralization.enabled).toBe(true);
+    expect(config.pluralization.model).toBe("groq:llama-3.1-8b-instant");
+  });
+
+  it("throws when pluralization is enabled with empty models map", () => {
+    expect(() =>
+      createLingoConfig({
+        sourceLocale: "en",
+        targetLocales: ["es"],
+        models: {},
+        pluralization: {
+          enabled: true,
+        },
+      }),
+    ).toThrow(/pluralization\.model/);
+  });
+
+  it("throws when pluralization is enabled without a model and models are lingo.dev", () => {
+    expect(() =>
+      createLingoConfig({
+        sourceLocale: "en",
+        targetLocales: ["es"],
+        models: "lingo.dev",
+        pluralization: {
+          enabled: true,
+        },
+      }),
+    ).toThrow(/pluralization\.model/);
+  });
+});

packages/new-compiler/src/utils/config-factory.ts

@@ -27,7 +27,7 @@ export const DEFAULT_CONFIG = {
   },
   models: "lingo.dev",
   pluralization: {
-    enabled: true,
+    enabled: false,
     model: "groq:llama-3.1-8b-instant",
   },
   buildMode: "translate",
@@ -37,6 +37,49 @@ export const DEFAULT_CONFIG = {
   LingoConfigRequiredFields | "environment" | "cacheType"
 >;
 
+function getModelStringForLocales(
+  models: Record<string, string>,
+  sourceLocale: string,
+  targetLocale: string | undefined,
+): string | undefined {
+  const localeKeys = targetLocale
+    ? [
+        `${sourceLocale}:${targetLocale}`,
+        `*:${targetLocale}`,
+        `${sourceLocale}:*`,
+        "*:*",
+      ]
+    : [`${sourceLocale}:*`, "*:*"];
+
+  const modelKey = localeKeys.find((key) => key in models);
+  if (modelKey) {
+    return models[modelKey];
+  }
+
+  const sortedKeys = Object.keys(models).sort();
+  if (sortedKeys.length === 0) {
+    return undefined;
+  }
+
+  return models[sortedKeys[0]];
+}
+
+function inferPluralizationModel(
+  models: "lingo.dev" | Record<string, string>,
+  sourceLocale: string,
+  targetLocales: string[],
+): string | undefined {
+  if (models === "lingo.dev") {
+    return undefined;
+  }
+
+  return getModelStringForLocales(
+    models,
+    sourceLocale,
+    targetLocales[0],
+  );
+}
+
 /**
  * Create a LoaderConfig with defaults applied
  *
@@ -47,7 +90,7 @@ export const DEFAULT_CONFIG = {
 export function createLingoConfig(
   options: PartialLingoConfig & Partial<Pick<LingoConfig, LingoInternalFields>>,
 ): LingoConfig {
-  return {
+  const config: LingoConfig = {
     ...DEFAULT_CONFIG,
     ...options,
     environment:
@@ -71,4 +114,42 @@ export function createLingoConfig(
       },
     },
   };
+
+  const explicitEnabled = options.pluralization?.enabled;
+  const explicitModel = options.pluralization?.model;
+  const hasExplicitModel =
+    typeof explicitModel === "string" && explicitModel.trim().length > 0;
+  const hasExplicitEnabled = typeof explicitEnabled === "boolean";
+
+  const pluralizationEnabled = hasExplicitEnabled
+    ? explicitEnabled
+    : hasExplicitModel;
+
+  let pluralizationModel = hasExplicitModel
+    ? explicitModel!.trim()
+    : config.pluralization.model;
+
+  if (pluralizationEnabled && !hasExplicitModel) {
+    const inferredModel = inferPluralizationModel(
+      config.models,
+      config.sourceLocale,
+      config.targetLocales,
+    );
+
+    if (!inferredModel) {
+      throw new Error(
+        'Pluralization is enabled but no "pluralization.model" is configured. Please set "pluralization.model" explicitly or use direct LLM models (not "lingo.dev") so the model can be inferred.',
+      );
+    }
+
+    pluralizationModel = inferredModel;
+  }
+
+  config.pluralization = {
+    ...config.pluralization,
+    enabled: pluralizationEnabled,
+    model: pluralizationModel,
+  };
+
+  return config;
 }