feat(cli): add keyColumn option for CSV buckets with duplicate key validation

.changeset/csv-key-column.md

@@ -0,0 +1,6 @@
+---
+"lingo.dev": patch
+"@lingo.dev/_spec": patch
+---
+
+feat(cli): add `keyColumn` option for CSV buckets to specify which column is the unique row identifier, and validate key uniqueness to prevent silent data loss from duplicate keys

packages/cli/demo/csv/i18n.json

@@ -10,7 +10,8 @@
     "csv": {
       "include": [
         "./example.csv"
-      ]
+      ],
+      "keyColumn": "KEY"
     }
   },
   "$schema": "https://lingo.dev/schema/i18n.json"

packages/cli/src/cli/cmd/cleanup.ts

@@ -69,6 +69,7 @@ export default new Command()
             {
               defaultLocale: sourceLocale,
               formatter: i18nConfig!.formatter,
+              keyColumn: bucket.keyColumn,
             },
             bucket.lockedKeys,
             bucket.lockedPatterns,

packages/cli/src/cli/cmd/i18n.ts

@@ -222,6 +222,7 @@ export default new Command()
                 defaultLocale: sourceLocale,
                 injectLocale: bucket.injectLocale,
                 formatter: i18nConfig!.formatter,
+                keyColumn: bucket.keyColumn,
               },
               bucket.lockedKeys,
               bucket.lockedPatterns,
@@ -263,6 +264,7 @@ export default new Command()
                 defaultLocale: sourceLocale,
                 returnUnlocalizedKeys: true,
                 injectLocale: bucket.injectLocale,
+                keyColumn: bucket.keyColumn,
               },
               bucket.lockedKeys,
               bucket.lockedPatterns,
@@ -377,6 +379,7 @@ export default new Command()
                 defaultLocale: sourceLocale,
                 injectLocale: bucket.injectLocale,
                 formatter: i18nConfig!.formatter,
+                keyColumn: bucket.keyColumn,
               },
               bucket.lockedKeys,
               bucket.lockedPatterns,

packages/cli/src/cli/cmd/lockfile.ts

@@ -42,6 +42,7 @@ export default new Command()
             {
               defaultLocale: sourceLocale,
               formatter: i18nConfig!.formatter,
+              keyColumn: bucket.keyColumn,
             },
             bucket.lockedKeys,
             bucket.lockedPatterns,

packages/cli/src/cli/cmd/purge.ts

@@ -102,6 +102,7 @@ export default new Command()
                   defaultLocale: sourceLocale,
                   injectLocale: bucket.injectLocale,
                   formatter: i18nConfig!.formatter,
+                  keyColumn: bucket.keyColumn,
                 },
                 bucket.lockedKeys,
                 bucket.lockedPatterns,

packages/cli/src/cli/cmd/run/_types.ts

@@ -1,9 +1,4 @@
-import {
-  bucketTypeSchema,
-  I18nConfig,
-  localeCodeSchema,
-  bucketTypes,
-} from "@lingo.dev/_spec";
+import { bucketTypeSchema, I18nConfig, bucketTypes } from "@lingo.dev/_spec";
 import { z } from "zod";
 import { ILocalizer } from "../../localizer/_types";
 
@@ -36,6 +31,7 @@ export type CmdRunTask = {
   localizableKeys: string[];
   onlyKeys: string[];
   formatter?: "prettier" | "biome";
+  keyColumn?: string;
 };
 
 export const flagsSchema = z.object({

packages/cli/src/cli/cmd/run/execute.ts

@@ -34,9 +34,7 @@ export default async function execute(input: CmdRunContext) {
       {
         title: "Initializing localization engine",
         task: async (ctx, task) => {
-          task.title = `Localization engine ${chalk.hex(colors.green)(
-            "ready",
-          )} (${ctx.localizer!.id})`;
+          task.title = `Localization engine ${chalk.hex(colors.green)("ready")} (${ctx.localizer!.id})`;
         },
       },
       {
@@ -124,9 +122,9 @@ function createWorkerStatusMessage(args: {
     "[locale]",
     args.assignedTask.targetLocale,
   );
-  return `[${chalk.hex(colors.yellow)(
-    `${args.percentage}%`,
-  )}] Processing: ${chalk.dim(displayPath)} (${chalk.hex(colors.yellow)(
+  return `[${chalk.hex(colors.yellow)(`${args.percentage}%`)}] Processing: ${chalk.dim(displayPath)} (${chalk.hex(
+    colors.yellow,
+  )(
     args.assignedTask.sourceLocale,
   )} -> ${chalk.hex(colors.yellow)(args.assignedTask.targetLocale)})`;
 }
@@ -147,9 +145,7 @@ function createExecutionProgressMessage(ctx: CmdRunContext) {
 
   return `Processed ${chalk.green(succeededTasksCount)}/${
     ctx.tasks.length
-  }, Failed ${chalk.red(failedTasksCount)}, Skipped ${chalk.dim(
-    skippedTasksCount,
-  )}`;
+  }, Failed ${chalk.red(failedTasksCount)}, Skipped ${chalk.dim(skippedTasksCount)}`;
 }
 
 function createLoaderForTask(assignedTask: CmdRunTask) {
@@ -160,6 +156,7 @@ function createLoaderForTask(assignedTask: CmdRunTask) {
       defaultLocale: assignedTask.sourceLocale,
       injectLocale: assignedTask.injectLocale,
       formatter: assignedTask.formatter,
+      keyColumn: assignedTask.keyColumn,
     },
     assignedTask.lockedKeys,
     assignedTask.lockedPatterns,

packages/cli/src/cli/cmd/run/frozen.ts

@@ -60,6 +60,7 @@ export default async function frozen(input: CmdRunContext) {
                     defaultLocale: resolvedSourceLocale,
                     injectLocale: bucket.injectLocale,
                     formatter: input.config!.formatter,
+                    keyColumn: bucket.keyColumn,
                   },
                   bucket.lockedKeys,
                   bucket.lockedPatterns,
@@ -101,6 +102,7 @@ export default async function frozen(input: CmdRunContext) {
                   defaultLocale: resolvedSourceLocale,
                   returnUnlocalizedKeys: true,
                   injectLocale: bucket.injectLocale,
+                  keyColumn: bucket.keyColumn,
                 },
                 bucket.lockedKeys,
                 bucket.lockedPatterns,

packages/cli/src/cli/cmd/run/plan.ts

@@ -39,23 +39,15 @@ export default async function plan(
         task: async (ctx, task) => {
           const bucketCount = buckets.length;
           const bucketFilter = input.flags.bucket
-            ? ` ${chalk.dim(
-                `(filtered by: ${chalk.hex(colors.yellow)(
-                  input.flags.bucket!.join(", "),
-                )})`,
-              )}`
+            ? ` ${chalk.dim(`(filtered by: ${chalk.hex(colors.yellow)(input.flags.bucket!.join(", "))})`)}`
             : "";
-          task.title = `Found ${chalk.hex(colors.yellow)(
-            bucketCount.toString(),
-          )} bucket(s)${bucketFilter}`;
+          task.title = `Found ${chalk.hex(colors.yellow)(bucketCount.toString())} bucket(s)${bucketFilter}`;
         },
       },
       {
         title: "Detecting locales",
         task: async (ctx, task) => {
-          task.title = `Found ${chalk.hex(colors.yellow)(
-            _targetLocales.length.toString(),
-          )} target locale(s)`;
+          task.title = `Found ${chalk.hex(colors.yellow)(_targetLocales.length.toString())} target locale(s)`;
         },
       },
       {
@@ -82,15 +74,9 @@ export default async function plan(
           }
 
           const fileFilter = input.flags.file
-            ? ` ${chalk.dim(
-                `(filtered by: ${chalk.hex(colors.yellow)(
-                  input.flags.file.join(", "),
-                )})`,
-              )}`
+            ? ` ${chalk.dim(`(filtered by: ${chalk.hex(colors.yellow)(input.flags.file.join(", "))})`)}`
             : "";
-          task.title = `Found ${chalk.hex(colors.yellow)(
-            patterns.length.toString(),
-          )} path pattern(s)${fileFilter}`;
+          task.title = `Found ${chalk.hex(colors.yellow)(patterns.length.toString())} path pattern(s)${fileFilter}`;
         },
       },
       {
@@ -137,14 +123,13 @@ export default async function plan(
                   localizableKeys: bucket.localizableKeys || [],
                   onlyKeys: input.flags.key || [],
                   formatter: input.config!.formatter,
+                  keyColumn: bucket.keyColumn,
                 });
               }
             }
           }
 
-          task.title = `Prepared ${chalk.hex(colors.green)(
-            ctx.tasks.length.toString(),
-          )} translation task(s)`;
+          task.title = `Prepared ${chalk.hex(colors.green)(ctx.tasks.length.toString())} translation task(s)`;
         },
       },
     ],

packages/cli/src/cli/cmd/show/_shared-key-command.ts

@@ -61,6 +61,7 @@ export async function executeKeyCommand(
           {
             defaultLocale: sourceLocale,
             injectLocale: bucket.injectLocale,
+            keyColumn: bucket.keyColumn,
           },
           [], // Don't apply any filtering when reading
           [],

packages/cli/src/cli/cmd/status.ts

@@ -199,6 +199,7 @@ export default new Command()
                 defaultLocale: sourceLocale,
                 injectLocale: bucket.injectLocale,
                 formatter: i18nConfig!.formatter,
+                keyColumn: bucket.keyColumn,
               },
               bucket.lockedKeys,
               bucket.lockedPatterns,

packages/cli/src/cli/loaders/csv.spec.ts

@@ -94,4 +94,106 @@ describe("csv loader", () => {
       "The first pull must be for the default locale",
     );
   });
+
+  describe("key column validation", () => {
+    it("should throw a descriptive error when the key column has duplicate values", async () => {
+      // Mirrors the Salesfloor bug: first column is categorical, not unique,
+      // which previously caused silent row collapse.
+      const dupeCsv = buildCsv([
+        ["type", "en", "es"],
+        ["code", "Hello", ""],
+        ["code", "Bye", ""],
+        ["menu", "Home", ""],
+        ["menu", "Profile", ""],
+      ]);
+
+      const loader = createCsvLoader();
+      loader.setDefaultLocale("en");
+
+      await expect(loader.pull("en", dupeCsv)).rejects.toThrow(
+        /CSV column "type" has duplicate values/,
+      );
+    });
+
+    it("should not throw when the detected key column is unique", async () => {
+      const loader = createCsvLoader();
+      loader.setDefaultLocale("en");
+
+      // sampleCsv has unique `id` values — this should just work.
+      await expect(loader.pull("en", sampleCsv)).resolves.toBeDefined();
+    });
+
+    it("should use the `keyColumn` option instead of the first column", async () => {
+      // First column `type` is repeated; `id` is unique.
+      // With keyColumn: "id", the loader must use `id` and not fail on `type` dupes.
+      const csv = buildCsv([
+        ["type", "id", "en", "es"],
+        ["code", "hello", "Hello", ""],
+        ["code", "bye", "Bye", ""],
+        ["menu", "home", "Home", ""],
+      ]);
+
+      const loader = createCsvLoader({ keyColumn: "id" });
+      loader.setDefaultLocale("en");
+
+      const result = await loader.pull("en", csv);
+      expect(result).toEqual({ hello: "Hello", bye: "Bye", home: "Home" });
+    });
+
+    it("should throw when `keyColumn` points to a column not in the CSV", async () => {
+      const loader = createCsvLoader({ keyColumn: "nonexistent" });
+      loader.setDefaultLocale("en");
+
+      await expect(loader.pull("en", sampleCsv)).rejects.toThrow(
+        /CSV key column "nonexistent" is not present/,
+      );
+    });
+
+    it("should still throw on duplicates when `keyColumn` points at a non-unique column", async () => {
+      const csv = buildCsv([
+        ["id", "group", "en"],
+        ["1", "menu", "Hello"],
+        ["2", "menu", "Bye"],
+      ]);
+
+      const loader = createCsvLoader({ keyColumn: "group" });
+      loader.setDefaultLocale("en");
+
+      await expect(loader.pull("en", csv)).rejects.toThrow(
+        /CSV column "group" has duplicate values/,
+      );
+    });
+
+    it("should correctly push translations when `keyColumn` is not the first column", async () => {
+      // Metadata columns (`type`, `group`) come first; `id` is the key in the middle.
+      // Verifies that push matches translations by id (not row index) and preserves
+      // non-key columns through the round-trip.
+      const csv = buildCsv([
+        ["type", "group", "id", "en"],
+        ["code", "ui", "hello", "Hello"],
+        ["code", "ui", "bye", "Bye"],
+        ["menu", "nav", "home", "Home"],
+      ]);
+
+      const loader = createCsvLoader({ keyColumn: "id" });
+      loader.setDefaultLocale("en");
+      await loader.pull("en", csv);
+
+      const esCsv = await loader.push("es", {
+        hello: "Hola",
+        bye: "Adiós",
+        home: "Inicio",
+      });
+
+      const parsed = parse(esCsv, {
+        columns: true,
+        skip_empty_lines: true,
+      });
+      expect(parsed).toEqual([
+        { type: "code", group: "ui", id: "hello", en: "Hello", es: "Hola" },
+        { type: "code", group: "ui", id: "bye", en: "Bye", es: "Adiós" },
+        { type: "menu", group: "nav", id: "home", en: "Home", es: "Inicio" },
+      ]);
+    });
+  });
 });