feat: key locking support (#627)

* feat: add config 1.6

* feat: add key locking support

* test: added tests for key lockin

* fix: cache restore support in locked keys mdoe

* test: upd test

* chore: cleanup

Author: maxprilutskiy

.changeset/sixty-houses-marry.md

@@ -0,0 +1,6 @@
+---
+"@lingo.dev/_spec": minor
+"lingo.dev": minor
+---
+
+add support for json/yaml key locking

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

@@ -124,11 +124,16 @@ export default new Command()
         for (const bucket of buckets) {
           for (const bucketPath of bucket.paths) {
             const sourceLocale = resolveOverriddenLocale(i18nConfig!.locale.source, bucketPath.delimiter);
-            const bucketLoader = createBucketLoader(bucket.type, bucketPath.pathPattern, {
-              isCacheRestore: false,
-              defaultLocale: sourceLocale,
-              injectLocale: bucket.injectLocale,
-            });
+            const bucketLoader = createBucketLoader(
+              bucket.type,
+              bucketPath.pathPattern,
+              {
+                isCacheRestore: false,
+                defaultLocale: sourceLocale,
+                injectLocale: bucket.injectLocale,
+              },
+              bucket.lockedKeys,
+            );
             bucketLoader.setDefaultLocale(sourceLocale);
             await bucketLoader.init();
 
@@ -216,11 +221,16 @@ export default new Command()
             bucketOra.info(`Processing path: ${bucketPath.pathPattern}`);
 
             const sourceLocale = resolveOverriddenLocale(i18nConfig!.locale.source, bucketPath.delimiter);
-            const bucketLoader = createBucketLoader(bucket.type, bucketPath.pathPattern, {
-              isCacheRestore: true,
-              defaultLocale: sourceLocale,
-              injectLocale: bucket.injectLocale,
-            });
+            const bucketLoader = createBucketLoader(
+              bucket.type,
+              bucketPath.pathPattern,
+              {
+                isCacheRestore: true,
+                defaultLocale: sourceLocale,
+                injectLocale: bucket.injectLocale,
+              },
+              bucket.lockedKeys,
+            );
             bucketLoader.setDefaultLocale(sourceLocale);
             await bucketLoader.init();
             const sourceData = await bucketLoader.pull(sourceLocale);
@@ -264,12 +274,17 @@ export default new Command()
           for (const bucketPath of bucket.paths) {
             const sourceLocale = resolveOverriddenLocale(i18nConfig!.locale.source, bucketPath.delimiter);
 
-            const bucketLoader = createBucketLoader(bucket.type, bucketPath.pathPattern, {
-              isCacheRestore: false,
-              defaultLocale: sourceLocale,
-              returnUnlocalizedKeys: true,
-              injectLocale: bucket.injectLocale,
-            });
+            const bucketLoader = createBucketLoader(
+              bucket.type,
+              bucketPath.pathPattern,
+              {
+                isCacheRestore: false,
+                defaultLocale: sourceLocale,
+                returnUnlocalizedKeys: true,
+                injectLocale: bucket.injectLocale,
+              },
+              bucket.lockedKeys,
+            );
             bucketLoader.setDefaultLocale(sourceLocale);
             await bucketLoader.init();
 
@@ -346,11 +361,16 @@ export default new Command()
 
             const sourceLocale = resolveOverriddenLocale(i18nConfig!.locale.source, bucketPath.delimiter);
 
-            const bucketLoader = createBucketLoader(bucket.type, bucketPath.pathPattern, {
-              isCacheRestore: false,
-              defaultLocale: sourceLocale,
-              injectLocale: bucket.injectLocale,
-            });
+            const bucketLoader = createBucketLoader(
+              bucket.type,
+              bucketPath.pathPattern,
+              {
+                isCacheRestore: false,
+                defaultLocale: sourceLocale,
+                injectLocale: bucket.injectLocale,
+              },
+              bucket.lockedKeys,
+            );
             bucketLoader.setDefaultLocale(sourceLocale);
             await bucketLoader.init();
             let sourceData = await bucketLoader.pull(sourceLocale);

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

@@ -444,6 +444,65 @@ describe("bucket loaders", () => {
       expect(fs.writeFile).toHaveBeenCalledWith("i18n/es.json", expectedOutput, { encoding: "utf-8", flag: "w" });
     });
 
+    it("should respect locked keys during cache restoration", async () => {
+      setupFileMocks();
+
+      const input = {
+        "button.title": "Submit",
+        "button.description": "Extra field not in payload",
+        "locked.key": "Should not change",
+        nested: {
+          locked: "This is locked",
+          unlocked: "This can change",
+          extra: "This should be removed in cache restore",
+        },
+      };
+      const payload = {
+        "button.title": "Enviar",
+        "locked.key": "This should not be applied",
+        "nested/locked": "This should not be applied either",
+        "nested/unlocked": "Este puede cambiar",
+      };
+
+      mockFileOperations(JSON.stringify(input));
+
+      const jsonLoader = createBucketLoader(
+        "json",
+        "i18n/[locale].json",
+        { isCacheRestore: true, defaultLocale: "en" },
+        ["locked.key", "nested/locked"],
+      );
+
+      jsonLoader.setDefaultLocale("en");
+      await jsonLoader.pull("en");
+
+      await jsonLoader.push("es", payload);
+
+      expect(fs.writeFile).toHaveBeenCalled();
+      const writeFileCall = (fs.writeFile as any).mock.calls[0];
+      const writtenContent = JSON.parse(writeFileCall[1]);
+
+      // During cache restoration, only keys in the payload should be included
+      // but locked keys should still be preserved
+      expect(Object.keys(writtenContent)).toContain("button.title");
+      expect(Object.keys(writtenContent)).toContain("locked.key");
+      expect(writtenContent["locked.key"]).toBe("Should not change");
+
+      // Fields not in the payload should be removed in cache restoration
+      expect(Object.keys(writtenContent)).not.toContain("button.description");
+
+      // Nested keys should follow the same pattern
+      expect(writtenContent.nested).toHaveProperty("unlocked", "Este puede cambiar");
+      expect(writtenContent.nested).toHaveProperty("locked", "This is locked");
+      expect(writtenContent.nested).not.toHaveProperty("extra");
+
+      // Only locked keys and payload keys should be present
+      expect(Object.keys(writtenContent)).toEqual(expect.arrayContaining(["button.title", "locked.key", "nested"]));
+      expect(Object.keys(writtenContent)).toHaveLength(3);
+      expect(Object.keys(writtenContent.nested)).toEqual(expect.arrayContaining(["locked", "unlocked"]));
+      expect(Object.keys(writtenContent.nested)).toHaveLength(2);
+    });
+
     it("should load and save json data for paths with multiple locales", async () => {
       setupFileMocks();
 
@@ -507,6 +566,186 @@ describe("bucket loaders", () => {
     });
   });
 
+  describe("locked keys functionality", () => {
+    it("should respect locked keys for JSON format", async () => {
+      setupFileMocks();
+
+      const input = {
+        "button.title": "Submit",
+        "button.description": "Submit description",
+        "locked.key": "Should not change",
+        nested: {
+          locked: "This is locked",
+          unlocked: "This can change",
+        },
+      };
+      const payload = {
+        "button.title": "Enviar",
+        "button.description": "Descripción de envío",
+        "locked.key": "This should not be applied",
+        "nested/locked": "This should not be applied either",
+        "nested/unlocked": "Este puede cambiar",
+      };
+
+      mockFileOperations(JSON.stringify(input));
+
+      const jsonLoader = createBucketLoader(
+        "json",
+        "i18n/[locale].json",
+        { isCacheRestore: false, defaultLocale: "en" },
+        ["locked.key", "nested/locked"],
+      );
+
+      jsonLoader.setDefaultLocale("en");
+      await jsonLoader.pull("en");
+
+      await jsonLoader.push("es", payload);
+
+      expect(fs.writeFile).toHaveBeenCalled();
+      const writeFileCall = (fs.writeFile as any).mock.calls[0];
+      const writtenContent = JSON.parse(writeFileCall[1]);
+
+      // Check that locked keys retain their original values
+      expect(writtenContent["locked.key"]).toBe("Should not change");
+      expect(writtenContent.nested.locked).toBe("This is locked");
+
+      // Check that unlocked keys are updated
+      expect(writtenContent["button.title"]).toBe("Enviar");
+      expect(writtenContent["button.description"]).toBe("Descripción de envío");
+      expect(writtenContent.nested.unlocked).toBe("Este puede cambiar");
+    });
+
+    it("should respect locked keys during cache restoration", async () => {
+      setupFileMocks();
+
+      const input = {
+        "button.title": "Submit",
+        "locked.key": "Should not change",
+        nested: {
+          locked: "This is locked",
+          unlocked: "This can change",
+        },
+      };
+      const payload = {
+        "button.title": "Enviar",
+        "locked.key": "This should not be applied",
+        "nested/locked": "This should not be applied either",
+        "nested/unlocked": "Este puede cambiar",
+      };
+
+      mockFileOperations(JSON.stringify(input));
+
+      const jsonLoader = createBucketLoader(
+        "json",
+        "i18n/[locale].json",
+        { isCacheRestore: true, defaultLocale: "en" },
+        ["locked.key", "nested/locked"],
+      );
+
+      jsonLoader.setDefaultLocale("en");
+      await jsonLoader.pull("en");
+
+      await jsonLoader.push("es", payload);
+
+      expect(fs.writeFile).toHaveBeenCalled();
+      const writeFileCall = (fs.writeFile as any).mock.calls[0];
+      const writtenContent = JSON.parse(writeFileCall[1]);
+
+      expect(Object.keys(writtenContent)).toContain("button.title");
+      expect(writtenContent["locked.key"]).toBe("Should not change");
+      expect(writtenContent.nested).toHaveProperty("unlocked", "Este puede cambiar");
+      expect(writtenContent.nested).toHaveProperty("locked", "This is locked");
+    });
+
+    it("should handle deeply nested locked keys", async () => {
+      setupFileMocks();
+
+      const input = {
+        level1: {
+          level2: {
+            level3: {
+              locked: "This is locked deep",
+              unlocked: "This can change",
+            },
+          },
+        },
+      };
+      const payload = {
+        "level1/level2/level3/locked": "This should not be applied",
+        "level1/level2/level3/unlocked": "This should change",
+      };
+
+      mockFileOperations(JSON.stringify(input));
+
+      const jsonLoader = createBucketLoader(
+        "json",
+        "i18n/[locale].json",
+        { isCacheRestore: false, defaultLocale: "en" },
+        ["level1/level2/level3/locked"],
+      );
+
+      jsonLoader.setDefaultLocale("en");
+      await jsonLoader.pull("en");
+
+      await jsonLoader.push("es", payload);
+
+      expect(fs.writeFile).toHaveBeenCalled();
+      const writeFileCall = (fs.writeFile as any).mock.calls[0];
+      const writtenContent = JSON.parse(writeFileCall[1]);
+
+      // Check that deeply nested locked key retains its original value
+      expect(writtenContent.level1.level2.level3.locked).toBe("This is locked deep");
+
+      // Check that unlocked key is updated
+      expect(writtenContent.level1.level2.level3.unlocked).toBe("This should change");
+    });
+
+    it("should lock keys that are arrays", async () => {
+      setupFileMocks();
+
+      const input = {
+        messages: ["first", "second", "third"],
+        unlocked: ["can", "be", "changed"],
+      };
+      const payload = {
+        "messages/0": "should not change",
+        "messages/1": "should not change either",
+        "messages/2": "should definitely not change",
+        "unlocked/0": "should",
+        "unlocked/1": "definitely",
+        "unlocked/2": "change",
+      };
+
+      mockFileOperations(JSON.stringify(input));
+
+      const jsonLoader = createBucketLoader(
+        "json",
+        "i18n/[locale].json",
+        { isCacheRestore: false, defaultLocale: "en" },
+        ["messages/0", "messages/1", "messages/2"],
+      );
+
+      jsonLoader.setDefaultLocale("en");
+      await jsonLoader.pull("en");
+
+      await jsonLoader.push("es", payload);
+
+      expect(fs.writeFile).toHaveBeenCalled();
+      const writeFileCall = (fs.writeFile as any).mock.calls[0];
+      const writtenContent = JSON.parse(writeFileCall[1]);
+
+      // Check that locked array elements retain their original values
+      expect(writtenContent.messages[0]).toBe("first");
+      expect(writtenContent.messages[1]).toBe("second");
+      expect(writtenContent.messages[2]).toBe("third");
+
+      // Check that unlocked array elements are updated
+      expect(writtenContent.unlocked[0]).toBe("should");
+      expect(writtenContent.unlocked[1]).toBe("definitely");
+      expect(writtenContent.unlocked[2]).toBe("change");
+    });
+  });
+
   describe("markdown bucket loader", () => {
     it("should load markdown data", async () => {
       setupFileMocks();

packages/cli/src/cli/loaders/index.ts

@@ -30,6 +30,7 @@ import createPlutilJsonTextLoader from "./plutil-json-loader";
 import createPhpLoader from "./php";
 import createVueJsonLoader from "./vue-json";
 import createInjectLocaleLoader from "./inject-locale";
+import createLockedKeysLoader from "./locked-keys";
 
 type BucketLoaderOptions = {
   isCacheRestore: boolean;
@@ -42,6 +43,7 @@ export default function createBucketLoader(
   bucketType: Z.infer<typeof bucketTypeSchema>,
   bucketPathPattern: string,
   options: BucketLoaderOptions,
+  lockedKeys?: string[],
 ): ILoader<void, Record<string, string>> {
   switch (bucketType) {
     default:
@@ -77,6 +79,7 @@ export default function createBucketLoader(
         createJsonLoader(),
         createInjectLocaleLoader(options.injectLocale),
         createFlatLoader(),
+        createLockedKeysLoader(lockedKeys || [], options.isCacheRestore),
         createSyncLoader(),
         createUnlocalizableLoader(options.isCacheRestore, options.returnUnlocalizedKeys),
       );
@@ -136,6 +139,7 @@ export default function createBucketLoader(
         createPrettierLoader({ parser: "yaml", bucketPathPattern }),
         createYamlLoader(),
         createFlatLoader(),
+        createLockedKeysLoader(lockedKeys || [], options.isCacheRestore),
         createSyncLoader(),
         createUnlocalizableLoader(options.isCacheRestore, options.returnUnlocalizedKeys),
       );