feat(cli): add preservedKeys (#1960)

Author: AndreyHirsa

.changeset/crisp-signs-itch.md

@@ -0,0 +1,6 @@
+---
+"@lingo.dev/_spec": patch
+"lingo.dev": patch
+---
+
+Add `preservedKeys` configuration option to buckets. Preserved keys are added to targets using source values as placeholders, but once present in the target file, they are never overwritten by the CLI. This is useful for values like URLs or emails that should be copied initially but then customized per locale.

packages/cli/demo/json/en/example.json

@@ -10,14 +10,8 @@
   "author": {
     "name": "John Doe"
   },
-  "contributors": [
-    { "name": "Alice" },
-    { "name": "Bob" }
-  ],
-  "messages": [
-    "Welcome to MyApp",
-    "Hello, world!"
-  ],
+  "contributors": [{ "name": "Alice" }, { "name": "Bob" }],
+  "messages": ["Welcome to MyApp", "Hello, world!"],
   "config": {
     "theme": {
       "primary": "Blue theme"
@@ -32,6 +26,9 @@
     }
   ],
   "locked_key_1": "This value is locked and should not be changed",
-  "ignored_key_1": "This value is ignored and should not appear in target locales"
-
-}
+  "ignored_key_1": "This value is ignored and should not appear in target locales",
+  "preserved_key_1": "this value is preserved and should not be overwritten",
+  "legal": {
+    "preserved_nested": "this value is preserved and should not be overwritten"
+  }
+}

packages/cli/demo/json/es/example.json

@@ -32,5 +32,9 @@
       "nested_message": "Texto anidado"
     }
   ],
-  "locked_key_1": "This value is locked and should not be changed"
-}
+  "locked_key_1": "This value is locked and should not be changed",
+  "preserved_key_1": "this value is preserved and should not be overwritten",
+  "legal": {
+    "preserved_nested": "this value is preserved and should not be overwritten"
+  }
+}

packages/cli/demo/json/i18n.json

@@ -1,18 +1,15 @@
 {
-  "version": "1.10",
+  "version": "1.12",
   "locale": {
     "source": "en",
-    "targets": [
-      "es"
-    ]
+    "targets": ["es"]
   },
   "buckets": {
     "json": {
-      "include": [
-        "./[locale]/example.json"
-      ],
-      "lockedKeys": ["locked_key_1"]
+      "include": ["./[locale]/example.json"],
+      "lockedKeys": ["locked_key_1"],
+      "preservedKeys": ["preserved_key_1", "legal/preserved_nested"]
     }
   },
   "$schema": "https://lingo.dev/schema/i18n.json"
-}
+}

packages/cli/demo/json/i18n.lock

@@ -14,3 +14,5 @@ checksums:
     config/theme/primary: 7535a3779d6934ea8ecf18f5cb5b93fd
     mixed_array/0: 001b5b003d96c133534f5907abffdf77
     mixed_array/3/nested_message: 5f0782dfc5993e99890c0475bc295a30
+    ignored_key_1: 386cb6c3c496982b059671768905d66e
+    legal/preserved_nested: 1f22d279b6be8d261e125e54c5a6cb64

packages/cli/i18n.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.10",
+  "version": "1.12",
   "locale": {
     "source": "en",
     "targets": ["es"]
@@ -34,7 +34,8 @@
     "json": {
       "include": ["demo/json/[locale]/example.json"],
       "lockedKeys": ["locked_key_1"],
-      "ignoredKeys": ["ignored_key_1"]
+      "ignoredKeys": ["ignored_key_1"],
+      "preservedKeys": ["preserved_key_1", "legal/preserved_nested"]
     },
     "jsonc": {
       "include": ["demo/jsonc/[locale]/example.jsonc"],

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

@@ -32,6 +32,7 @@ export type CmdRunTask = {
   lockedKeys: string[];
   lockedPatterns: string[];
   ignoredKeys: string[];
+  preservedKeys: string[];
   onlyKeys: string[];
   formatter?: "prettier" | "biome";
 };

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

@@ -163,6 +163,7 @@ function createLoaderForTask(assignedTask: CmdRunTask) {
     assignedTask.lockedKeys,
     assignedTask.lockedPatterns,
     assignedTask.ignoredKeys,
+    assignedTask.preservedKeys,
   );
   bucketLoader.setDefaultLocale(assignedTask.sourceLocale);
 

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

@@ -64,6 +64,7 @@ export default async function frozen(input: CmdRunContext) {
                   bucket.lockedKeys,
                   bucket.lockedPatterns,
                   bucket.ignoredKeys,
+                  bucket.preservedKeys,
                 );
                 loader.setDefaultLocale(resolvedSourceLocale);
                 await loader.init();
@@ -103,6 +104,7 @@ export default async function frozen(input: CmdRunContext) {
                 bucket.lockedKeys,
                 bucket.lockedPatterns,
                 bucket.ignoredKeys,
+                bucket.preservedKeys,
               );
               loader.setDefaultLocale(resolvedSourceLocale);
               await loader.init();

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

@@ -133,6 +133,7 @@ export default async function plan(
                   lockedKeys: bucket.lockedKeys || [],
                   lockedPatterns: bucket.lockedPatterns || [],
                   ignoredKeys: bucket.ignoredKeys || [],
+                  preservedKeys: bucket.preservedKeys || [],
                   onlyKeys: input.flags.key || [],
                   formatter: input.config!.formatter,
                 });