chore:bunch of cleanups

Author: AleksandrSl

cmp/compiler/src/__test-utils__/mocks.ts

@@ -5,7 +5,6 @@
 
 import type { LingoConfig } from "../types";
 import { createLingoConfig } from "../utils/config-factory";
-import type { DictionarySchema } from "../translators";
 
 /**
  * Create a mock loader config for testing
@@ -30,62 +29,3 @@ export function createMockConfig(
     ...overrides,
   });
 }
-
-/**
- * Create a mock dictionary for testing
- *
- * @param entries - Hash-to-translation mapping
- * @param locale - Target locale (default: "en")
- * @param version - Schema version (default: 0.1)
- * @returns Complete DictionarySchema
- *
- * @example
- * ```typescript
- * const dict = createMockDictionary({
- *   "abc123": "Hello",
- *   "def456": "World"
- * }, "de");
- * ```
- */
-export function createMockDictionary(
-  entries: Record<string, string> = {},
-  locale: string = "en",
-  version: number = 0.1,
-): DictionarySchema {
-  return {
-    version,
-    locale,
-    entries,
-  };
-}
-
-/**
- * Create a mock translator for testing
- * Returns a simple translator that prefixes all translations with the locale
- *
- * @param locale - Default locale (unused, kept for backward compatibility)
- * @returns Mock translator object
- *
- * @example
- * ```typescript
- * const translator = createMockTranslator();
- * const result = await translator.translate("de", {
- *   hash1: { text: "Hello", context: {} }
- * });
- * // -> { hash1: "[de] Hello" }
- * ```
- */
-export function createMockTranslator(locale: string = "en") {
-  return {
-    translate: async (
-      targetLocale: string,
-      entries: Record<string, { text: string; context: Record<string, any> }>,
-    ) => {
-      const result: Record<string, string> = {};
-      for (const [hash, { text }] of Object.entries(entries)) {
-        result[hash] = `[${targetLocale}] ${text}`;
-      }
-      return result;
-    },
-  };
-}

cmp/compiler/src/locale/client.ts

@@ -1,9 +1,11 @@
+import type { LocaleCode } from "lingo.dev/spec";
+
 /**
  * Get the current locale on the client
  * Reads from cookie
  * @returns Resolved locale code
  */
-export function getClientLocale(): string {
+export function getClientLocale(): LocaleCode {
   return "en";
 }
 
@@ -14,6 +16,6 @@ const __NOOP_PERSIST_LOCALE__ = () => {};
  * Writes to cookie
  * @param locale - Locale code to persist
  */
-export function persistLocale(locale: string): void {
+export function persistLocale(locale: LocaleCode): void {
   return __NOOP_PERSIST_LOCALE__();
 }

cmp/compiler/src/locale/server.ts

@@ -1,8 +1,10 @@
+import type { LocaleCode } from "lingo.dev/spec";
+
 /**
  * Get the current locale on the server
  * Uses cookies, headers, or other server-side mechanisms
  * @returns Resolved locale code
  */
-export async function getServerLocale(): Promise<string> {
+export async function getServerLocale(): Promise<LocaleCode> {
   return "en";
 }

cmp/compiler/src/plugin/build-translator.ts

@@ -17,6 +17,8 @@ import {
 } from "../translation-server";
 import { loadMetadata } from "../metadata/manager";
 import { createCache, type TranslationCache } from "../translators";
+import { dictionaryFrom } from "../translators/api";
+import type { LocaleCode } from "lingo.dev/spec";
 
 export interface BuildTranslationOptions {
   config: LingoConfig;
@@ -125,7 +127,7 @@ export async function processBuildTranslations(
     );
 
     const stats: BuildTranslationResult["stats"] = {};
-    const errors: Array<{ locale: string; error: string }> = [];
+    const errors: Array<{ locale: LocaleCode; error: string }> = [];
 
     // Translate all locales in parallel
     const localePromises = allLocales.map(async (locale) => {
@@ -195,7 +197,7 @@ async function validateCache(
   const allHashes = Object.keys(metadata.entries);
   const missingLocales: string[] = [];
   const incompleteLocales: Array<{
-    locale: string;
+    locale: LocaleCode;
     missing: number;
     total: number;
   }> = [];
@@ -295,36 +297,8 @@ async function copyStaticFiles(
     const publicFilePath = path.join(publicOutputPath, `${locale}.json`);
 
     try {
-      // TODO (AleksandrSl 14/12/2025): Probably make it required?
-      // Use getDictionary if available (for LocalTranslationCache), otherwise use get
-      const dictionary = cache.getDictionary
-        ? await cache.getDictionary(locale)
-        : null;
-
-      if (!dictionary) {
-        logger.error(`❌ Failed to read cache for ${locale}`);
-        process.exit(1);
-      }
-
-      const filteredEntries: Record<string, string> = {};
-      let includedCount = 0;
-      let skippedCount = 0;
-
-      for (const [hash, translation] of Object.entries(dictionary.entries)) {
-        if (usedHashes.has(hash)) {
-          filteredEntries[hash] = translation;
-          includedCount++;
-        } else {
-          skippedCount++;
-        }
-      }
-
-      // Write filtered translations
-      const outputData = {
-        locale,
-        entries: filteredEntries,
-        version: dictionary.version,
-      };
+      const entries = await cache.get(locale, Array.from(usedHashes));
+      const outputData = dictionaryFrom(locale, entries);
 
       await fs.writeFile(
         publicFilePath,
@@ -333,7 +307,7 @@ async function copyStaticFiles(
       );
 
       logger.info(
-        `✓ Generated ${locale}.json (${includedCount} translations, ${skippedCount} unused skipped)`,
+        `✓ Generated ${locale}.json (${Object.keys(entries).length} translations)`,
       );
     } catch (error) {
       logger.error(`❌ Failed to generate ${locale}.json:`, error);
@@ -344,7 +318,11 @@ async function copyStaticFiles(
 
 function formatCacheValidationError(
   missingLocales: string[],
-  incompleteLocales: Array<{ locale: string; missing: number; total: number }>,
+  incompleteLocales: Array<{
+    locale: LocaleCode;
+    missing: number;
+    total: number;
+  }>,
 ): string {
   let msg = "❌ Cache validation failed in cache-only mode:\n\n";
 
@@ -374,7 +352,7 @@ function formatCacheValidationError(
 }
 
 function formatTranslationErrors(
-  errors: Array<{ locale: string; error: string }>,
+  errors: Array<{ locale: LocaleCode; error: string }>,
 ): string {
   let msg = "❌ Translation generation failed:\n\n";
 

cmp/compiler/src/plugin/next-compiler-loader.ts

@@ -15,7 +15,9 @@ export default async function nextCompilerLoader(
   this: any,
   source: string,
 ): Promise<void> {
-  // TODO (AleksandrSl 14/12/2025): Webpack doesn't like callback usage in async function. But asycn function can return only code, so we have to use promises which is sad.
+  // TODO (AleksandrSl 14/12/2025): Webpack doesn't like callback usage in async function.
+  //  But async function can return only code, so we have to use promises which is sad. It actually errors only when we catch an error, so it's not an urgent problem
+
   // Ensure we're running in loader context
   if (typeof this.async !== "function") {
     throw new Error("This module must be run as a loader");

cmp/compiler/src/plugin/transform/utils.ts

@@ -133,7 +133,7 @@ export function createTranslationEntry<T extends keyof TranslationEntryByType>(
     },
     overrides:
       overrides && Object.keys(overrides).length > 0 ? overrides : undefined,
-    // TODO (AleksandrSl 08/12/2025): Figure out why it doesn't work without the cast
+    // Seems like the only approach without the cast is function overloads, which are noisy. The type cast is not that bad since it's inside the function.
   } as TranslationEntryByType[T];
 }
 

cmp/compiler/src/react/server-only/index.ts

@@ -17,6 +17,7 @@ import type { ReactNode } from "react";
 import { logger } from "../../utils/logger";
 // Keep this import full for replacement during build.
 import { getServerLocale } from "@lingo.dev/compiler/locale/server";
+import type { LocaleCode } from "lingo.dev/spec";
 
 /**
  * Get server-side translations function
@@ -31,7 +32,7 @@ export async function getServerTranslations(options: {
   /**
    * Target locale for translations (required)
    */
-  locale?: string;
+  locale?: LocaleCode;
 
   /**
    * List of translation hashes needed for this component
@@ -50,7 +51,7 @@ export async function getServerTranslations(options: {
     sourceText: string,
     params?: RichTextParams,
   ) => string | ReactNode;
-  locale: string;
+  locale: LocaleCode;
   translations: Record<string, string>;
 }> {
   const locale = options.locale || (await getServerLocale());

cmp/compiler/src/react/server-only/translations.ts

@@ -13,6 +13,7 @@ import { join } from "path";
 import { logger } from "../../utils/logger";
 import { fetchTranslations as fetchFromDevServer } from "../shared/utils";
 import { cacheDir, serverUrl } from "@lingo.dev/compiler/dev-config";
+import type { LocaleCode } from "lingo.dev/spec";
 
 /**
  * Configuration for translation fetching
@@ -37,7 +38,7 @@ export interface TranslationFetchConfig {
  * @returns Translation dictionary (hash -> translated text)
  */
 async function readFromFilesystem(
-  locale: string,
+  locale: LocaleCode,
   basePath: string = process.cwd(),
 ): Promise<Record<string, string>> {
   // TODO (AleksandrSl 02/12/2025): Sanity check. We need to try loading the most up to date translations first. Fo the dev mode they are in lingo. Gor build they are in next.
@@ -101,7 +102,7 @@ async function readFromFilesystem(
  * ```
  */
 export async function fetchTranslationsOnServer(
-  locale: string,
+  locale: LocaleCode,
   hashes: string[],
   config: TranslationFetchConfig = {},
 ): Promise<Record<string, string>> {

cmp/compiler/src/react/shared/LingoContext.ts

@@ -1,15 +1,21 @@
 import { createContext, useContext } from "react";
+import type { LocaleCode } from "lingo.dev/spec";
 
 interface LingoContextType {
+  /**
+   * Source locale (default language)
+   */
+  sourceLocale: LocaleCode;
+
   /**
    * Current locale (e.g., 'en', 'de', 'fr')
    */
-  locale: string;
+  locale: LocaleCode;
 
   /**
    * Change the current locale and dynamically load translations
    */
-  setLocale: (locale: string) => Promise<void>;
+  setLocale: (locale: LocaleCode) => Promise<void>;
 
   /**
    * Translation dictionary: hash -> translated text
@@ -27,11 +33,6 @@ interface LingoContextType {
    */
   isLoading: boolean;
 
-  /**
-   * Source locale (default language)
-   */
-  sourceLocale: string;
-
   /**
    * Development statistics (only in dev mode)
    */

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

@@ -16,6 +16,7 @@ import {
   persistLocale,
 } from "@lingo.dev/compiler/locale/client";
 import { LingoContext } from "./LingoContext";
+import type { LocaleCode } from "lingo.dev/spec";
 
 const noop = () => {};
 
@@ -26,12 +27,12 @@ export interface LingoProviderProps {
   /**
    * Initial locale to use
    */
-  initialLocale?: string;
+  initialLocale?: LocaleCode;
 
   /**
    * Source locale (default language)
    */
-  sourceLocale?: string;
+  sourceLocale?: LocaleCode;
 
   /**
    * Initial translations (pre-loaded)
@@ -97,13 +98,14 @@ export const LingoProvider = IS_DEV ? LingoProvider__Dev : LingoProvider__Prod;
 
 function LingoProvider__Prod({
   initialLocale,
+  // TODO (AleksandrSl 14/12/2025): Remove sourceLocale here.
   sourceLocale = "en",
   initialTranslations = {},
   router,
   children,
 }: LingoProviderProps) {
   // Use client locale detection if no initialLocale provided
-  const [locale, setLocaleState] = useState(() => {
+  const [locale, setLocaleState] = useState<LocaleCode>(() => {
     if (initialLocale) return initialLocale;
     // Only detect on client-side (not during SSR)
     if (typeof window !== "undefined") {
@@ -135,7 +137,7 @@ function LingoProvider__Prod({
    * Lazy loads on-demand for SPAs
    */
   const loadTranslations = useCallback(
-    async (targetLocale: string) => {
+    async (targetLocale: LocaleCode) => {
       // If we already have initialTranslations (Next.js SSR), don't fetch
       if (Object.keys(initialTranslations).length > 0) {
         return;
@@ -189,7 +191,7 @@ function LingoProvider__Prod({
    * - For SPAs: lazy loads translations from /translations/{locale}.json
    */
   const setLocale = useCallback(
-    async (newLocale: string) => {
+    async (newLocale: LocaleCode) => {
       // 1. Persist to cookie so server can read it on next render
       persistLocale(newLocale);
 
@@ -391,7 +393,7 @@ function LingoProvider__Dev({
    * Change locale and load translations dynamically
    */
   const setLocale = useCallback(
-    async (newLocale: string) => {
+    async (newLocale: LocaleCode) => {
       // 1. Persist to cookie (unless disabled)
       persistLocale(newLocale);