@inlang/paraglide-js 2.4.0 → 2.6.0

package/dist/compiler/emit-ts-declarations.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generates `.d.ts` files for the compiled Paraglide output using the TypeScript compiler.
+ *
+ * @param output - The generated compiler output keyed by relative file path.
+ * @returns The generated declaration files keyed by relative path.
+ *
+ * @example
+ * const declarations = await emitTsDeclarations(output);
+ * // Merge them into the compiler output before writing to disk
+ */
+export declare function emitTsDeclarations(output: Record<string, string>): Promise<Record<string, string>>;
+//# sourceMappingURL=emit-ts-declarations.d.ts.map

package/dist/compiler/emit-ts-declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-ts-declarations.d.ts","sourceRoot":"","sources":["../../src/compiler/emit-ts-declarations.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA6HjC"}

package/dist/compiler/emit-ts-declarations.js

@@ -0,0 +1,99 @@
+import path from "node:path";
+/**
+ * Generates `.d.ts` files for the compiled Paraglide output using the TypeScript compiler.
+ *
+ * @param output - The generated compiler output keyed by relative file path.
+ * @returns The generated declaration files keyed by relative path.
+ *
+ * @example
+ * const declarations = await emitTsDeclarations(output);
+ * // Merge them into the compiler output before writing to disk
+ */
+export async function emitTsDeclarations(output) {
+    const ts = await import("typescript");
+    const jsEntries = Object.entries(output).filter(([fileName]) => fileName.endsWith(".js"));
+    if (jsEntries.length === 0) {
+        return {};
+    }
+    const virtualRoot = path.join(process.cwd(), "__paraglide_virtual_output");
+    const normalizeFileName = (fileName) => path.normalize(path.isAbsolute(fileName) ? fileName : path.join(virtualRoot, fileName));
+    const files = new Map(jsEntries.map(([fileName, content]) => [
+        normalizeFileName(fileName),
+        content,
+    ]));
+    const virtualDirectories = new Set(Array.from(files.keys()).flatMap((filePath) => {
+        const directories = [];
+        let current = path.dirname(filePath);
+        while (current.startsWith(virtualRoot) && current !== virtualRoot) {
+            directories.push(current);
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        return directories;
+    }));
+    // Ensure the virtual root itself is treated as existing
+    virtualDirectories.add(virtualRoot);
+    const compilerOptions = {
+        allowJs: true,
+        checkJs: true,
+        declaration: true,
+        emitDeclarationOnly: true,
+        esModuleInterop: true,
+        lib: ["ESNext", "DOM"],
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        noEmitOnError: false,
+        outDir: virtualRoot,
+        rootDir: virtualRoot,
+        skipLibCheck: true,
+        target: ts.ScriptTarget.ESNext,
+    };
+    const defaultHost = ts.createCompilerHost(compilerOptions, true);
+    const declarations = {};
+    const host = {
+        ...defaultHost,
+        fileExists: (fileName) => {
+            const normalized = normalizeFileName(fileName);
+            return files.has(normalized) || defaultHost.fileExists(fileName);
+        },
+        directoryExists: (directoryName) => {
+            const normalized = normalizeFileName(directoryName);
+            return (virtualDirectories.has(normalized) ||
+                defaultHost.directoryExists?.(directoryName) === true);
+        },
+        getDirectories: (directoryName) => {
+            const normalized = normalizeFileName(directoryName);
+            const children = Array.from(virtualDirectories).filter((dir) => path.dirname(dir) === normalized);
+            return [
+                ...(defaultHost.getDirectories?.(directoryName) ?? []),
+                ...children.map((dir) => path.basename(dir)),
+            ];
+        },
+        readFile: (fileName) => {
+            const normalized = normalizeFileName(fileName);
+            return files.get(normalized) ?? defaultHost.readFile(fileName);
+        },
+        getSourceFile: (fileName, languageVersion, onError, shouldCreateNewFile) => {
+            const normalized = normalizeFileName(fileName);
+            const sourceText = files.get(normalized);
+            if (sourceText !== undefined) {
+                return ts.createSourceFile(fileName, sourceText, languageVersion, true);
+            }
+            return defaultHost.getSourceFile(fileName, languageVersion, onError, shouldCreateNewFile);
+        },
+        writeFile: (fileName, text) => {
+            const relativePath = path
+                .relative(virtualRoot, fileName)
+                .split(path.sep)
+                .join(path.posix.sep);
+            if (!relativePath.startsWith("..")) {
+                declarations[relativePath] = text;
+            }
+        },
+    };
+    const program = ts.createProgram(Array.from(files.keys()), compilerOptions, host);
+    program.emit(undefined, undefined, undefined, true);
+    return declarations;
+}

package/dist/compiler/index.d.ts

@@ -1,5 +1,5 @@
 export { defaultCompilerOptions, type CompilerOptions, } from "./compiler-options.js";
-export type { MessageBundleFunction, MessageFunction } from "./types.js";
+export type { LocalizedString, MessageBundleFunction, MessageFunction, } from "./types.js";
 export type { Runtime } from "./runtime/type.js";
 export type { ServerRuntime } from "./server/type.js";
 export { compile } from "./compile.js";

package/dist/compiler/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,sBAAsB,EACtB,KAAK,eAAe,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACzE,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,sBAAsB,EACtB,KAAK,eAAe,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACX,eAAe,EACf,qBAAqB,EACrB,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/compiler/jsdoc-types.js

@@ -3,7 +3,7 @@ export function jsDocBundleFunctionTypes(args) {
     return `
 * @param {${inputsType(args.inputs)}} inputs
 * @param {{ locale?: ${localesUnion} }} options
-* @returns {string}`;
+* @returns {LocalizedString}`;
 }
 /**
  * Returns the types for the input variables.

package/dist/compiler/jsdoc-types.test.js

@@ -24,3 +24,12 @@ test("jsDocBundleFunctionTypes correctly handles messages with duplicate inputs"
     // It should not contain duplicated parameters
     expect(result).not.toContain("@param {{ days: NonNullable<unknown>, days: NonNullable<unknown> }} inputs");
 });
+test("jsDocBundleFunctionTypes returns LocalizedString type", () => {
+    const inputs = [];
+    const locales = ["en", "de"];
+    const result = jsDocBundleFunctionTypes({ inputs, locales });
+    // The JSDoc should specify LocalizedString as the return type
+    expect(result).toContain("@returns {LocalizedString}");
+    // It should not return plain string
+    expect(result).not.toContain("@returns {string}");
+});

package/dist/compiler/output-structure/locale-modules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale-modules.d.ts","sourceRoot":"","sources":["../../../src/compiler/output-structure/locale-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAIvE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAE1E;AAED,wBAAgB,cAAc,CAC7B,eAAe,EAAE,0BAA0B,EAAE,EAC7C,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,YAAY,CAAC,EACzD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoDxB"}
+{"version":3,"file":"locale-modules.d.ts","sourceRoot":"","sources":["../../../src/compiler/output-structure/locale-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAIvE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAE1E;AAED,wBAAgB,cAAc,CAC7B,eAAe,EAAE,0BAA0B,EAAE,EAC7C,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,YAAY,CAAC,EACzD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4DxB"}

package/dist/compiler/output-structure/locale-modules.js

@@ -6,6 +6,7 @@ export function messageReferenceExpression(locale, bundleId) {
 export function generateOutput(compiledBundles, settings, fallbackMap) {
     const indexFile = [
         `import { getLocale, trackMessageCall, experimentalMiddlewareLocaleSplitting, isServer } from "../runtime.js"`,
+        `/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */`,
         settings.locales
             .map((locale) => `import * as ${toSafeModuleId(locale)} from "./${locale}.js"`)
             .join("\n"),
@@ -31,7 +32,7 @@ export function generateOutput(compiledBundles, settings, fallbackMap) {
                 }
                 else {
                     // no fallback exists, render the bundleId
-                    file += `\n/** @type {(inputs: ${inputsType(inputs)}) => string} */\nexport const ${bundleModuleId} = () => '${bundleId}'`;
+                    file += `\n/** @type {(inputs: ${inputsType(inputs)}) => LocalizedString} */\nexport const ${bundleModuleId} = () => /** @type {LocalizedString} */ ('${bundleId}')`;
                 }
                 continue;
             }
@@ -41,6 +42,12 @@ export function generateOutput(compiledBundles, settings, fallbackMap) {
         if (file.includes("registry.")) {
             file = `import * as registry from "../registry.js"\n` + file;
         }
+        // add LocalizedString typedef reference if used
+        if (file.includes("LocalizedString")) {
+            file =
+                `/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */\n` +
+                    file;
+        }
         output[filename] = file;
     }
     return output;

package/dist/compiler/output-structure/message-modules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-modules.d.ts","sourceRoot":"","sources":["../../../src/compiler/output-structure/message-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAKvE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAE1E;AAED,wBAAgB,cAAc,CAC7B,eAAe,EAAE,0BAA0B,EAAE,EAC7C,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,YAAY,CAAC,EACzD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkFxB"}
+{"version":3,"file":"message-modules.d.ts","sourceRoot":"","sources":["../../../src/compiler/output-structure/message-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAKvE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAE1E;AAED,wBAAgB,cAAc,CAC7B,eAAe,EAAE,0BAA0B,EAAE,EAC7C,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,YAAY,CAAC,EACzD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC7C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkHxB"}

package/dist/compiler/output-structure/message-modules.js

@@ -31,24 +31,47 @@ export function generateOutput(compiledBundles, settings, fallbackMap) {
         }
         // add the fallbacks (needs to be done after the messages to avoid referencing
         // the message before they are defined)
-        for (const locale of needsFallback) {
-            // add fallback
+        const needsFallbackSet = new Set(needsFallback);
+        const emittedFallbacks = new Set();
+        const emittingFallbacks = new Set();
+        /**
+         * Emits the fallback definition for a locale ensuring that dependent fallbacks
+         * are declared beforehand.
+         *
+         * @example
+         * emitFallback("fr-ca");
+         */
+        const emitFallback = (locale) => {
+            if (emittedFallbacks.has(locale))
+                return;
+            if (emittingFallbacks.has(locale))
+                return;
+            emittingFallbacks.add(locale);
             const safeLocale = toSafeModuleId(locale);
             const fallbackLocale = fallbackMap[locale];
+            if (fallbackLocale &&
+                needsFallbackSet.has(fallbackLocale) &&
+                !compiledBundle.messages[fallbackLocale]) {
+                emitFallback(fallbackLocale);
+            }
             if (fallbackLocale) {
                 const safeFallbackLocale = toSafeModuleId(fallbackLocale);
-                // take the fallback locale
-                messages.push(`/** @type {(inputs: ${inputsType(inputs)}) => string} */\nconst ${safeLocale}_${safeModuleId} = ${safeFallbackLocale}_${safeModuleId};`);
+                messages.push(`/** @type {(inputs: ${inputsType(inputs)}) => LocalizedString} */\nconst ${safeLocale}_${safeModuleId} = ${safeFallbackLocale}_${safeModuleId};`);
             }
             else {
-                // fallback to just the bundle id
-                messages.push(`/** @type {(inputs: ${inputsType(inputs)}) => string} */\nconst ${safeLocale}_${safeModuleId} = () => '${escapeForSingleQuoteString(bundleId)}'`);
+                messages.push(`/** @type {(inputs: ${inputsType(inputs)}) => LocalizedString} */\nconst ${safeLocale}_${safeModuleId} = () => /** @type {LocalizedString} */ ('${escapeForSingleQuoteString(bundleId)}')`);
             }
+            emittingFallbacks.delete(locale);
+            emittedFallbacks.add(locale);
+        };
+        for (const locale of needsFallback) {
+            emitFallback(locale);
         }
         output[filename] = messages.join("\n\n") + "\n\n" + output[filename];
-        // add the imports
+        // add the imports and type reference (LocalizedString is defined in runtime.js)
         output[filename] =
-            `import { getLocale, trackMessageCall, experimentalMiddlewareLocaleSplitting, isServer } from '../runtime.js';\n\n` +
+            `import { getLocale, trackMessageCall, experimentalMiddlewareLocaleSplitting, isServer } from '../runtime.js';\n` +
+                `/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */\n\n` +
                 output[filename];
         // Add the registry import to the message file
         // if registry is used
@@ -58,8 +81,10 @@ export function generateOutput(compiledBundles, settings, fallbackMap) {
         }
     }
     // all messages index file
-    output["messages/_index.js"] = Array.from(moduleFilenames)
-        .map((filename) => `export * from './${filename}'`)
-        .join("\n");
+    output["messages/_index.js"] =
+        `/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */\n` +
+            Array.from(moduleFilenames)
+                .map((filename) => `export * from './${filename}'`)
+                .join("\n");
     return output;
 }

package/dist/compiler/output-structure/message-modules.test.js

@@ -75,3 +75,45 @@ test("handles case senstivity by creating directories and files only in lowercas
     expect(output).toHaveProperty("messages/happyelephant2.js");
     expect(output).not.toHaveProperty("messages/HappyElephant.js");
 });
+// Regression test for https://github.com/opral/inlang-paraglide-js/issues/507
+test("emits fallback definitions after their dependencies", () => {
+    const resources = [
+        {
+            bundle: {
+                code: "export const admin_tasks = (inputs) => inputs;",
+                node: {
+                    id: "admin_tasks",
+                    declarations: [],
+                },
+            },
+            messages: {
+                en: {
+                    code: '/** @type {(inputs: {}) => string} */ () => "admin"',
+                    node: {},
+                },
+            },
+        },
+    ];
+    const settings = {
+        locales: ["fr-ca", "fr", "en"],
+        baseLocale: "en",
+    };
+    const fallbackMap = {
+        "fr-ca": "fr",
+        fr: "en",
+        en: undefined,
+    };
+    const output = generateOutput(resources, settings, fallbackMap);
+    const file = output["messages/admin_tasks.js"];
+    expect(file).toBeDefined();
+    if (!file) {
+        throw new Error("messages/admin_tasks.js should have been generated");
+    }
+    expect(file).toContain("const fr_admin_tasks = en_admin_tasks;");
+    expect(file).toContain("const fr_ca_admin_tasks = fr_admin_tasks;");
+    const frIndex = file.indexOf("const fr_admin_tasks");
+    const frCaIndex = file.indexOf("const fr_ca_admin_tasks");
+    expect(frIndex).toBeGreaterThan(-1);
+    expect(frCaIndex).toBeGreaterThan(-1);
+    expect(frIndex).toBeLessThan(frCaIndex);
+});

package/dist/compiler/runtime/assert-is-locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert-is-locale.d.ts","sourceRoot":"","sources":["../../../src/compiler/runtime/assert-is-locale.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,sCAJW,GAAG,GACD,MAAM,CAUlB"}
+{"version":3,"file":"assert-is-locale.d.ts","sourceRoot":"","sources":["../../../src/compiler/runtime/assert-is-locale.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,sCAJW,GAAG,GACD,MAAM,CAiBlB"}

package/dist/compiler/runtime/assert-is-locale.js

@@ -1,4 +1,3 @@
-import { isLocale } from "./is-locale.js";
 import { locales } from "./variables.js";
 /**
  * Asserts that the input is a locale.
@@ -8,8 +7,13 @@ import { locales } from "./variables.js";
  * @throws {Error} If the input is not a locale.
  */
 export function assertIsLocale(input) {
-    if (isLocale(input) === false) {
+    if (typeof input !== "string") {
+        throw new Error(`Invalid locale: ${input}. Expected a string.`);
+    }
+    const lowerInput = input.toLowerCase();
+    const matchedLocale = locales.find((item) => item.toLowerCase() === lowerInput);
+    if (!matchedLocale) {
         throw new Error(`Invalid locale: ${input}. Expected one of: ${locales.join(", ")}`);
     }
-    return input;
+    return matchedLocale;
 }

package/dist/compiler/runtime/assert-is-locale.test.js

@@ -1,6 +1,6 @@
-import { test, expect } from "vitest";
-import { createParaglide } from "../create-paraglide.js";
 import { newProject } from "@inlang/sdk";
+import { expect, test } from "vitest";
+import { createParaglide } from "../create-paraglide.js";
 test("throws if the locale is not available", async () => {
     const runtime = await createParaglide({
         blob: await newProject({
@@ -12,6 +12,21 @@ test("throws if the locale is not available", async () => {
     });
     expect(() => runtime.assertIsLocale("es")).toThrow();
 });
+test("throws for non-string inputs", async () => {
+    const runtime = await createParaglide({
+        blob: await newProject({
+            settings: {
+                baseLocale: "en",
+                locales: ["en", "de"],
+            },
+        }),
+    });
+    expect(() => runtime.assertIsLocale(null)).toThrow();
+    expect(() => runtime.assertIsLocale(undefined)).toThrow();
+    expect(() => runtime.assertIsLocale(123)).toThrow();
+    expect(() => runtime.assertIsLocale({})).toThrow();
+    expect(() => runtime.assertIsLocale([])).toThrow();
+});
 test("passes if the locale is available", async () => {
     const runtime = await createParaglide({
         blob: await newProject({
@@ -37,3 +52,19 @@ test("the return value is a Locale", async () => {
     // in the ambient type definition
     locale;
 });
+test("is case-insensitive", async () => {
+    const runtime = await createParaglide({
+        blob: await newProject({
+            settings: {
+                baseLocale: "en",
+                locales: ["en", "pt-BR", "de-ch"],
+            },
+        }),
+    });
+    expect(() => runtime.assertIsLocale("EN")).not.toThrow();
+    expect(() => runtime.assertIsLocale("pt-br")).not.toThrow();
+    expect(() => runtime.assertIsLocale("de-CH")).not.toThrow();
+    expect(runtime.assertIsLocale("EN")).toBe("en");
+    expect(runtime.assertIsLocale("pT-bR")).toBe("pt-BR");
+    expect(runtime.assertIsLocale("de-CH")).toBe("de-ch");
+});

package/dist/compiler/runtime/create-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-runtime.d.ts","sourceRoot":"","sources":["../../../src/compiler/runtime/create-runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE;QAChB,QAAQ,EAAE,WAAW,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;QACnD,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC;QACvD,YAAY,EAAE,WAAW,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC;QAC3D,YAAY,EAAE,eAAe,CAAC,cAAc,CAAC,CAAC;QAC9C,WAAW,CAAC,EAAE,eAAe,CAAC,aAAa,CAAC,CAAC;QAC7C,qCAAqC,EAAE,eAAe,CAAC,uCAAuC,CAAC,CAAC;QAChG,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;QACtC,eAAe,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;QACpD,wBAAwB,EAAE,WAAW,CACpC,eAAe,CAAC,0BAA0B,CAAC,CAC3C,CAAC;KACF,CAAC;CACF,GAAG,MAAM,CA4IT"}
+{"version":3,"file":"create-runtime.d.ts","sourceRoot":"","sources":["../../../src/compiler/runtime/create-runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE;QAChB,QAAQ,EAAE,WAAW,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;QACnD,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC;QACvD,YAAY,EAAE,WAAW,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC;QAC3D,YAAY,EAAE,eAAe,CAAC,cAAc,CAAC,CAAC;QAC9C,WAAW,CAAC,EAAE,eAAe,CAAC,aAAa,CAAC,CAAC;QAC7C,qCAAqC,EAAE,eAAe,CAAC,uCAAuC,CAAC,CAAC;QAChG,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;QACtC,eAAe,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;QACpD,wBAAwB,EAAE,WAAW,CACpC,eAAe,CAAC,0BAA0B,CAAC,CAC3C,CAAC;KACF,CAAC;CACF,GAAG,MAAM,CAsLT"}

package/dist/compiler/runtime/create-runtime.js

@@ -95,6 +95,48 @@ ${injectCode("./strategy.js")}
  * @typedef {(typeof locales)[number]} Locale
  */
 
+/**
+ * A branded type representing a localized string.
+ *
+ * Message functions return this type instead of \`string\`, enabling TypeScript
+ * to distinguish translated strings from regular strings at compile time.
+ * This allows you to enforce that only properly localized content is used
+ * in your UI components.
+ *
+ * Since \`LocalizedString\` is a branded subtype of \`string\`, it remains fully
+ * backward compatible—you can pass it anywhere a \`string\` is expected.
+ *
+ * @example
+ *   // Enforce localized strings in your components
+ *   function PageTitle(props: { title: LocalizedString }) {
+ *     return <h1>{props.title}</h1>
+ *   }
+ *
+ *   // ✅ Correct: using a message function
+ *   <PageTitle title={m.welcome_title()} />
+ *
+ *   // ❌ Type error: raw strings are not LocalizedString
+ *   <PageTitle title="Welcome" />
+ *
+ * @example
+ *   // LocalizedString is assignable to string (backward compatible)
+ *   const localized: LocalizedString = m.greeting()
+ *   const str: string = localized  // ✅ works fine
+ *
+ *   // But string is not assignable to LocalizedString
+ *   const raw: LocalizedString = "Hello"  // ❌ Type error
+ *
+ * @example
+ *   // Catches accidental string concatenation
+ *   function showMessage(msg: LocalizedString) { ... }
+ *
+ *   showMessage(m.hello())                    // ✅
+ *   showMessage("Hello " + userName)          // ❌ Type error
+ *   showMessage(m.hello_user({ name: userName }))  // ✅ use params instead
+ *
+ * @typedef {string & { readonly __brand: 'LocalizedString' }} LocalizedString
+ */
+
 `;
     return code;
 }

package/dist/compiler/runtime/is-locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-locale.d.ts","sourceRoot":"","sources":["../../../src/compiler/runtime/is-locale.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,iCAHW,GAAG,GACD,MAAM,IAAI,MAAM,CAI5B"}
+{"version":3,"file":"is-locale.d.ts","sourceRoot":"","sources":["../../../src/compiler/runtime/is-locale.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,iCAHW,GAAG,GACD,MAAM,IAAI,MAAM,CAO5B"}

package/dist/compiler/runtime/is-locale.js

@@ -13,5 +13,9 @@ import { locales } from "./variables.js";
  * @returns {locale is Locale}
  */
 export function isLocale(locale) {
-    return !locale ? false : locales.includes(locale);
+    if (typeof locale !== "string")
+        return false;
+    return !locale
+        ? false
+        : locales.some((item) => item.toLowerCase() === locale.toLowerCase());
 }

package/dist/compiler/runtime/is-locale.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=is-locale.test.d.ts.map

package/dist/compiler/runtime/is-locale.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-locale.test.d.ts","sourceRoot":"","sources":["../../../src/compiler/runtime/is-locale.test.ts"],"names":[],"mappings":""}

package/dist/compiler/runtime/is-locale.test.js

@@ -0,0 +1,31 @@
+import { newProject } from "@inlang/sdk";
+import { expect, test } from "vitest";
+import { createParaglide } from "../create-paraglide.js";
+const runtime = await createParaglide({
+    blob: await newProject({
+        settings: {
+            baseLocale: "en",
+            locales: ["en", "pt-BR", "de-ch"],
+        },
+    }),
+});
+test("returns true for exact matches", () => {
+    expect(runtime.isLocale("pt-BR")).toBe(true);
+});
+test("is case-insensitive", () => {
+    expect(runtime.isLocale("EN")).toBe(true);
+    expect(runtime.isLocale("pt-br")).toBe(true);
+    expect(runtime.isLocale("de-CH")).toBe(true);
+});
+test("returns false for non-existent locales", () => {
+    expect(runtime.isLocale("es")).toBe(false);
+    expect(runtime.isLocale("xx")).toBe(false);
+    expect(runtime.isLocale("")).toBe(false);
+});
+test("returns false for non-string inputs", () => {
+    expect(runtime.isLocale(null)).toBe(false);
+    expect(runtime.isLocale(undefined)).toBe(false);
+    expect(runtime.isLocale(123)).toBe(false);
+    expect(runtime.isLocale({})).toBe(false);
+    expect(runtime.isLocale([])).toBe(false);
+});

package/dist/compiler/types.d.ts

@@ -4,13 +4,29 @@ export type Compiled<Node> = {
     /** The code generated to implement the AST node */
     code: string;
 };
+/**
+ * A branded type representing a localized string.
+ * Provides compile-time safety to distinguish translated from untranslated strings.
+ *
+ * @example
+ * ```typescript
+ * import { m } from './paraglide/messages.js'
+ * import type { LocalizedString } from '@inlang/paraglide-js'
+ *
+ * const greeting: LocalizedString = m.hello() // ✓ Type-safe
+ * const raw: LocalizedString = "Hello"        // ✗ Type error
+ * ```
+ */
+export type LocalizedString = string & {
+    readonly __brand: "LocalizedString";
+};
 /**
  * A message function is a message for a specific locale.
  *
  * @example
  *   m.hello({ name: 'world' })
  */
-export type MessageFunction = (inputs?: Record<string, never>) => string;
+export type MessageFunction = (inputs?: Record<string, never>) => LocalizedString;
 /**
  * A message bundle function that selects the message to be returned.
  *
@@ -22,5 +38,5 @@ export type MessageFunction = (inputs?: Record<string, never>) => string;
  */
 export type MessageBundleFunction<T extends string> = (params: Record<string, never>, options: {
     locale: T;
-}) => string;
+}) => LocalizedString;
 //# sourceMappingURL=types.d.ts.map

package/dist/compiler/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/compiler/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,CAAC,IAAI,IAAI;IAC5B,4BAA4B;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,MAAM,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,IAAI,CACrD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC7B,OAAO,EAAE;IAAE,MAAM,EAAE,CAAC,CAAA;CAAE,KAClB,MAAM,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/compiler/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,CAAC,IAAI,IAAI;IAC5B,4BAA4B;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KAC1B,eAAe,CAAC;AAErB;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,IAAI,CACrD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC7B,OAAO,EAAE;IAAE,MAAM,EAAE,CAAC,CAAA;CAAE,KAClB,eAAe,CAAC"}

package/dist/services/env-variables/index.js

@@ -1,5 +1,5 @@
 export const ENV_VARIABLES = {
     PARJS_APP_ID: "library.inlang.paraglideJs",
     PARJS_POSTHOG_TOKEN: undefined,
-    PARJS_PACKAGE_VERSION: "2.4.0",
+    PARJS_PACKAGE_VERSION: "2.6.0",
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inlang/paraglide-js",
   "type": "module",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -26,13 +26,13 @@
     "./urlpattern-polyfill": "./dist/urlpattern-polyfill/index.js"
   },
   "dependencies": {
-    "@inlang/sdk": "2.4.9",
     "commander": "11.1.0",
     "consola": "3.4.0",
     "json5": "2.2.3",
     "unplugin": "^2.1.2",
     "urlpattern-polyfill": "^10.0.0",
-    "@inlang/recommend-sherlock": "0.2.1"
+    "@inlang/recommend-sherlock": "0.2.1",
+    "@inlang/sdk": "2.4.9"
   },
   "devDependencies": {
     "@rollup/plugin-virtual": "3.0.2",