feat: add support for plain TXT files (#981)

* feat: add support for plain TXT files

- Add 'txt' to bucketTypes array in formats.ts
- Add 'txt' case to loader factory switch statement
- Use simple loader composition: textFileLoader + syncLoader + unlocalizableLoader
- Enables translation of fastlane App Store metadata and other plain text files

Fixes #980

Co-Authored-By: [email protected] <[email protected]>

* chore: add changeset for TXT file support feature

Co-Authored-By: [email protected] <[email protected]>

* test: add comprehensive tests for TXT file loader

- Add tests for loading TXT files as single translatable content
- Add tests for saving translated TXT content
- Add test for handling empty TXT files
- Follow established test patterns with setupFileMocks and mockFileOperations
- Tests verify TXT files use 'content' key for entire file content
- All tests pass successfully

Co-Authored-By: [email protected] <[email protected]>

* fix: apply Prettier formatting to TXT loader files

- Fix code style issues in txt.ts and index.spec.ts
- Resolve CI formatting check failure

Co-Authored-By: [email protected] <[email protected]>

* feat: implement line-by-line splitting for TXT loader

- Split TXT file content by lines into numeric keys (1, 2, 3, etc.)
- Use single space placeholder for empty lines to avoid unlocalizable filter
- Add comprehensive tests for empty line preservation and file reconstruction
- Enables better chunking for large TXT files since each line becomes separate translatable unit
- Follows established patterns from SRT, CSV, and PO loaders

Co-Authored-By: [email protected] <[email protected]>

* refactor: remove space placeholder workaround from TXT loader

- Remove space placeholder logic for empty lines in pull/push methods
- Let unlocalizable loader handle empty strings automatically via filtering/restoration
- Update tests to expect empty strings to be filtered out during pull
- Simplifies implementation while maintaining correct empty line behavior
- User feedback: unlocalizable loader already handles this properly

Co-Authored-By: [email protected] <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: [email protected] <[email protected]>

Author: devin-ai-integration[bot]

.changeset/curly-bats-tell.md

@@ -0,0 +1,6 @@
+---
+"@lingo.dev/_spec": minor
+"lingo.dev": minor
+---
+
+Add support for plain TXT files to enable translation of fastlane App Store metadata and other plain text content

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

@@ -2621,6 +2621,158 @@ ${script}`;
       );
     });
   });
+
+  describe("txt bucket loader", () => {
+    it("should load txt", async () => {
+      setupFileMocks();
+
+      const input = `Welcome to our application!
+This is a sample text file for fastlane metadata.
+It contains app description that needs to be translated.`;
+
+      const expectedOutput = {
+        "1": "Welcome to our application!",
+        "2": "This is a sample text file for fastlane metadata.",
+        "3": "It contains app description that needs to be translated.",
+      };
+
+      mockFileOperations(input);
+
+      const txtLoader = createBucketLoader(
+        "txt",
+        "fastlane/metadata/[locale]/description.txt",
+        {
+          defaultLocale: "en",
+        },
+      );
+      txtLoader.setDefaultLocale("en");
+      const data = await txtLoader.pull("en");
+
+      expect(data).toEqual(expectedOutput);
+    });
+
+    it("should save txt", async () => {
+      setupFileMocks();
+
+      const input = `Welcome to our application!
+This is a sample text file for fastlane metadata.
+It contains app description that needs to be translated.`;
+
+      const payload = {
+        "1": "¡Bienvenido a nuestra aplicación!",
+        "2": "Este es un archivo de texto de muestra para metadatos de fastlane.",
+        "3": "Contiene la descripción de la aplicación que necesita ser traducida.",
+      };
+
+      const expectedOutput = `¡Bienvenido a nuestra aplicación!
+Este es un archivo de texto de muestra para metadatos de fastlane.
+Contiene la descripción de la aplicación que necesita ser traducida.`;
+
+      mockFileOperations(input);
+
+      const txtLoader = createBucketLoader(
+        "txt",
+        "fastlane/metadata/[locale]/description.txt",
+        {
+          defaultLocale: "en",
+        },
+      );
+      txtLoader.setDefaultLocale("en");
+      await txtLoader.pull("en");
+
+      await txtLoader.push("es", payload);
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        "fastlane/metadata/es/description.txt",
+        expectedOutput,
+        { encoding: "utf-8", flag: "w" },
+      );
+    });
+
+    it("should handle empty txt files", async () => {
+      setupFileMocks();
+
+      const input = "";
+      const expectedOutput = {};
+
+      mockFileOperations(input);
+
+      const txtLoader = createBucketLoader(
+        "txt",
+        "fastlane/metadata/[locale]/description.txt",
+        {
+          defaultLocale: "en",
+        },
+      );
+      txtLoader.setDefaultLocale("en");
+      const data = await txtLoader.pull("en");
+
+      expect(data).toEqual(expectedOutput);
+    });
+
+    it("should filter out empty lines during pull", async () => {
+      setupFileMocks();
+
+      const input = `Line 1
+
+Line 3`;
+      const expectedOutput = {
+        "1": "Line 1",
+        "3": "Line 3",
+      };
+
+      mockFileOperations(input);
+
+      const txtLoader = createBucketLoader(
+        "txt",
+        "fastlane/metadata/[locale]/description.txt",
+        {
+          defaultLocale: "en",
+        },
+      );
+      txtLoader.setDefaultLocale("en");
+      const data = await txtLoader.pull("en");
+
+      expect(data).toEqual(expectedOutput);
+    });
+
+    it("should reconstruct file with empty lines restored", async () => {
+      setupFileMocks();
+
+      const input = `Line 1
+
+Line 3`;
+
+      const payload = {
+        "1": "Línea 1",
+        "3": "Línea 3",
+      };
+
+      const expectedOutput = `Línea 1
+
+Línea 3`;
+
+      mockFileOperations(input);
+
+      const txtLoader = createBucketLoader(
+        "txt",
+        "fastlane/metadata/[locale]/description.txt",
+        {
+          defaultLocale: "en",
+        },
+      );
+      txtLoader.setDefaultLocale("en");
+      await txtLoader.pull("en");
+
+      await txtLoader.push("es", payload);
+
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        "fastlane/metadata/es/description.txt",
+        expectedOutput,
+        { encoding: "utf-8", flag: "w" },
+      );
+    });
+  });
 });
 
 function setupFileMocks() {

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

@@ -41,6 +41,7 @@ import createMdxLockedPatternsLoader from "./mdx2/locked-patterns";
 import createIgnoredKeysLoader from "./ignored-keys";
 import createEjsLoader from "./ejs";
 import createEnsureKeyOrderLoader from "./ensure-key-order";
+import createTxtLoader from "./txt";
 
 type BucketLoaderOptions = {
   returnUnlocalizedKeys?: boolean;
@@ -278,5 +279,12 @@ export default function createBucketLoader(
         createIgnoredKeysLoader(ignoredKeys || []),
         createUnlocalizableLoader(options.returnUnlocalizedKeys),
       );
+    case "txt":
+      return composeLoaders(
+        createTextFileLoader(bucketPathPattern),
+        createTxtLoader(),
+        createSyncLoader(),
+        createUnlocalizableLoader(options.returnUnlocalizedKeys),
+      );
   }
 }

packages/cli/src/cli/loaders/txt.ts

@@ -0,0 +1,29 @@
+import { ILoader } from "./_types";
+import { createLoader } from "./_utils";
+
+export default function createTxtLoader(): ILoader<
+  string,
+  Record<string, string>
+> {
+  return createLoader({
+    async pull(locale, input) {
+      const result: Record<string, string> = {};
+
+      if (input !== undefined && input !== null && input !== "") {
+        const lines = input.split("\n");
+        lines.forEach((line, index) => {
+          result[String(index + 1)] = line;
+        });
+      }
+
+      return result;
+    },
+
+    async push(locale, payload) {
+      const sortedEntries = Object.entries(payload).sort(
+        ([a], [b]) => parseInt(a) - parseInt(b),
+      );
+      return sortedEntries.map(([_, value]) => value).join("\n");
+    },
+  });
+}

packages/spec/src/formats.ts

@@ -26,6 +26,7 @@ export const bucketTypes = [
   "po",
   "vue-json",
   "typescript",
+  "txt",
 ] as const;
 
 export const bucketTypeSchema = Z.enum(bucketTypes);