fix(sdk): normalize Android and underscore locales to BCP 47 before API calls

.changeset/blue-crews-shake.md

@@ -0,0 +1,5 @@
+---
+"@lingo.dev/_sdk": patch
+---
+
+Android-format (`pt-rPT`) and underscore (`pt_PT`) locales passed config validation but were sent to the API verbatim, which it rejects with a 400. Normalize `sourceLocale`, `targetLocale`, and `reference` keys to canonical BCP 47 on the wire via a schema transform. File paths are unaffected, so the CLI keeps the original code for Android resource directories (e.g. `values-pt-rPT/`)

packages/sdk/src/index.spec.ts

@@ -481,4 +481,70 @@ describe("LingoDotDevEngine", () => {
       expect(requestBody.hints).toBeUndefined();
     });
   });
+
+  describe("locale normalization", () => {
+    let mockFetch: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      mockFetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ data: { greeting: "Olá" } }),
+      });
+      global.fetch = mockFetch as any;
+    });
+
+    it("normalizes Android `-r` locales to BCP 47 in the request body", async () => {
+      const engine = new LingoDotDevEngine({ apiKey: "test-key" });
+
+      await engine.localizeObject(
+        { greeting: "Hello" },
+        { sourceLocale: "en", targetLocale: "pt-rPT" },
+      );
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.targetLocale).toBe("pt-PT");
+      expect(body.sourceLocale).toBe("en");
+    });
+
+    it("normalizes underscore locales to BCP 47 in the request body", async () => {
+      const engine = new LingoDotDevEngine({ apiKey: "test-key" });
+
+      await engine.localizeObject(
+        { greeting: "Hello" },
+        { sourceLocale: "en_US", targetLocale: "pt_PT" },
+      );
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.sourceLocale).toBe("en-US");
+      expect(body.targetLocale).toBe("pt-PT");
+    });
+
+    it("normalizes locale codes used as reference keys", async () => {
+      const engine = new LingoDotDevEngine({ apiKey: "test-key" });
+
+      await engine.localizeObject(
+        { greeting: "Hello" },
+        {
+          sourceLocale: "en",
+          targetLocale: "pt-rPT",
+          reference: { "pt-rPT": { greeting: "Olá" } },
+        },
+      );
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(Object.keys(body.reference)).toEqual(["pt-PT"]);
+    });
+
+    it("leaves already-canonical locales unchanged", async () => {
+      const engine = new LingoDotDevEngine({ apiKey: "test-key" });
+
+      await engine.localizeObject(
+        { greeting: "Hello" },
+        { sourceLocale: "en", targetLocale: "pt-PT" },
+      );
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.targetLocale).toBe("pt-PT");
+    });
+  });
 });

packages/sdk/src/index.ts

@@ -1,5 +1,9 @@
 import Z from "zod";
-import { LocaleCode, localeCodeSchema } from "@lingo.dev/_spec";
+import {
+  LocaleCode,
+  localeCodeSchema,
+  normalizeLocale,
+} from "@lingo.dev/_spec";
 import { createId } from "@paralleldrive/cuid2";
 import { trackEvent } from "./utils/observability";
 import { TRACKING_EVENTS } from "./utils/tracking-events";
@@ -12,13 +16,18 @@ const engineParamsSchema = Z.object({
   engineId: Z.string().optional(),
 }).passthrough();
 
+// Locale codes are validated leniently (Android `pt-rPT`, underscore `pt_PT`,
+// etc. all pass) but must reach the API in canonical BCP 47 form. Normalizing
+// here keeps the CLI free to use the original code for file paths.
+const normalizedLocaleCodeSchema = localeCodeSchema.transform(normalizeLocale);
+
 const payloadSchema = Z.record(Z.string(), Z.any());
-const referenceSchema = Z.record(localeCodeSchema, payloadSchema);
+const referenceSchema = Z.record(normalizedLocaleCodeSchema, payloadSchema);
 const hintsSchema = Z.record(Z.string(), Z.array(Z.string()));
 
 const localizationParamsSchema = Z.object({
-  sourceLocale: Z.union([localeCodeSchema, Z.null()]),
-  targetLocale: localeCodeSchema,
+  sourceLocale: Z.union([normalizedLocaleCodeSchema, Z.null()]),
+  targetLocale: normalizedLocaleCodeSchema,
   fast: Z.boolean().optional(),
   reference: referenceSchema.optional(),
   hints: hintsSchema.optional(),
@@ -118,7 +127,7 @@ export class LingoDotDevEngine {
       const processedPayloadChunk = await this.localizeChunk(
         finalParams.sourceLocale,
         finalParams.targetLocale,
-        { data: chunk, reference: params.reference, hints: params.hints },
+        { data: chunk, reference: finalParams.reference, hints: params.hints },
         params.fast || false,
         params.filePath,
         params.triggerType,