@inlang/paraglide-js 2.5.0 → 2.7.0

package/dist/cli/commands/compile/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/compile/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,eAAO,MAAM,cAAc,SAmDzB,CAAC"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/compile/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,eAAO,MAAM,cAAc,SA4DzB,CAAC"}

package/dist/cli/commands/compile/command.js

@@ -16,6 +16,7 @@ export const compileCommand = new Command()
     "Read more on https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy",
 ].join("\n"))
     .requiredOption("--silent", "Only log errors to the console", false)
+    .option("--emit-ts-declarations", "Emit .d.ts files for the generated output (requires the typescript package)", defaultCompilerOptions.emitTsDeclarations)
     .action(async (options) => {
     const logger = new Logger({ silent: options.silent, prefix: true });
     const path = resolve(process.cwd(), options.project);
@@ -25,6 +26,8 @@ export const compileCommand = new Command()
             project: path,
             outdir: options.outdir,
             strategy: options.strategy ?? defaultCompilerOptions.strategy,
+            emitTsDeclarations: options.emitTsDeclarations ??
+                defaultCompilerOptions.emitTsDeclarations,
         });
     }
     catch (e) {

package/dist/compiler/compile-bundle.js

@@ -49,7 +49,7 @@ ${isSafeBundleId ? "export " : ""}const ${safeBundleId} = (inputs${hasInputs ? "
 	trackMessageCall("${safeBundleId}", locale)
 	${args.availableLocales
         .map((locale, index) => `${index > 0 ? "	" : ""}${!isFullyTranslated || index < args.availableLocales.length - 1 ? `if (locale === "${locale}") ` : ""}return ${args.messageReferenceExpression(locale, args.bundle.id)}(inputs)`)
-        .join("\n")}${!isFullyTranslated ? `\n	return "${args.bundle.id}"` : ""}
+        .join("\n")}${!isFullyTranslated ? `\n	return /** @type {LocalizedString} */ ("${args.bundle.id}")` : ""}
 };`;
     if (isSafeBundleId === false) {
         code += `\nexport { ${safeBundleId} as "${escapeForDoubleQuoteString(args.bundle.id)}" }`;

package/dist/compiler/compile-bundle.test.js

@@ -49,7 +49,7 @@ test("compiles to jsdoc", async () => {
 * 
 * @param {{ age: NonNullable<unknown> }} inputs
 * @param {{ locale?: "en" | "en-US" }} options
-* @returns {string}
+* @returns {LocalizedString}
 */
 /* @__NO_SIDE_EFFECTS__ */
 export const blue_moon_bottle = (inputs, options = {}) => {
@@ -100,29 +100,31 @@ test("compiles to jsdoc with missing translation", async () => {
             locales: ["en", "en-US", "fr"],
         },
     });
-    expect(result.bundle.code).toMatchInlineSnapshot(`"/**
-* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
-*
-* - Changing this function will be over-written by the next build.
-*
-* - If you want to change the translations, you can either edit the source files e.g. \`en.json\`, or
-* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
-* 
-* @param {{ age: NonNullable<unknown> }} inputs
-* @param {{ locale?: "en" | "en-US" }} options
-* @returns {string}
-*/
-/* @__NO_SIDE_EFFECTS__ */
-export const blue_moon_bottle = (inputs, options = {}) => {
-	if (experimentalMiddlewareLocaleSplitting && isServer === false) {
-		return /** @type {any} */ (globalThis).__paraglide_ssr.blue_moon_bottle(inputs) 
-	}
-	const locale = options.locale ?? getLocale()
-	trackMessageCall("blue_moon_bottle", locale)
-	if (locale === "en") return en.blue_moon_bottle(inputs)
-	if (locale === "en-US") return en_us2.blue_moon_bottle(inputs)
-	return "blue_moon_bottle"
-};"`);
+    expect(result.bundle.code).toMatchInlineSnapshot(`
+		"/**
+		* This function has been compiled by [Paraglide JS](https://inlang.com/m/gerre34r).
+		*
+		* - Changing this function will be over-written by the next build.
+		*
+		* - If you want to change the translations, you can either edit the source files e.g. \`en.json\`, or
+		* use another inlang app like [Fink](https://inlang.com/m/tdozzpar) or the [VSCode extension Sherlock](https://inlang.com/m/r7kp499g).
+		* 
+		* @param {{ age: NonNullable<unknown> }} inputs
+		* @param {{ locale?: "en" | "en-US" }} options
+		* @returns {LocalizedString}
+		*/
+		/* @__NO_SIDE_EFFECTS__ */
+		export const blue_moon_bottle = (inputs, options = {}) => {
+			if (experimentalMiddlewareLocaleSplitting && isServer === false) {
+				return /** @type {any} */ (globalThis).__paraglide_ssr.blue_moon_bottle(inputs) 
+			}
+			const locale = options.locale ?? getLocale()
+			trackMessageCall("blue_moon_bottle", locale)
+			if (locale === "en") return en.blue_moon_bottle(inputs)
+			if (locale === "en-US") return en_us2.blue_moon_bottle(inputs)
+			return /** @type {LocalizedString} */ ("blue_moon_bottle")
+		};"
+	`);
 });
 // https://github.com/opral/inlang-paraglide-js/issues/285
 test("compiles bundles with arbitrary module identifiers", async () => {
@@ -208,5 +210,5 @@ test("handles message pattern with duplicate variable references", async () => {
     // Check that the pattern is compiled correctly
     const enMessage = result.messages?.en;
     expect(enMessage).toBeDefined();
-    expect(enMessage?.code).toContain("Last ${i.days} days, showing ${i.days} items");
+    expect(enMessage?.code).toContain("Last ${i?.days} days, showing ${i?.days} items");
 });

package/dist/compiler/compile-local-variable.js

@@ -33,6 +33,6 @@ function compileLiteralOrVarRef(value) {
         case "literal":
             return `"${value.value}"`;
         case "variable-reference":
-            return `i.${value.name}`;
+            return `i?.${value.name}`;
     }
 }

package/dist/compiler/compile-local-variable.test.js

@@ -23,7 +23,7 @@ test("compiles a variable reference local variable", () => {
             },
         },
     });
-    expect(code).toEqual("const myVar = i.name;");
+    expect(code).toEqual("const myVar = i?.name;");
 });
 test("compiles a local variable with an annotation and empty options", () => {
     const code = compileLocalVariable({
@@ -67,5 +67,5 @@ test("compiles a local variable with an annotation and options", () => {
             },
         },
     });
-    expect(code).toEqual('const myVar = registry.myFunction("en", "Hello", { option1: "value1", option2: i.varRef });');
+    expect(code).toEqual('const myVar = registry.myFunction("en", "Hello", { option1: "value1", option2: i?.varRef });');
 });

package/dist/compiler/compile-message.js

@@ -33,8 +33,8 @@ function compileMessageWithOneVariant(declarations, message, variants) {
             compiledLocalVariables.push(compileLocalVariable({ declaration, locale: message.locale }));
         }
     }
-    const code = `/** @type {(inputs: ${inputsType(inputs)}) => string} */ (${hasInputs ? "i" : ""}) => {
-	${compiledLocalVariables.join("\n\t")}return ${compiledPattern.code}
+    const code = `/** @type {(inputs: ${inputsType(inputs)}) => LocalizedString} */ (${hasInputs ? "i" : ""}) => {
+	${compiledLocalVariables.join("\n\t")}return /** @type {LocalizedString} */ (${compiledPattern.code})
 };`;
     return { code, node: message };
 }
@@ -54,7 +54,7 @@ function compileMessageWithMultipleVariants(declarations, message, variants) {
         });
         const isCatchAll = variant.matches.every((match) => match.type === "catchall-match");
         if (isCatchAll) {
-            compiledVariants.push(`return ${compiledPattern.code}`);
+            compiledVariants.push(`return /** @type {LocalizedString} */ (${compiledPattern.code})`);
             hasCatchAll = true;
         }
         const conditions = [];
@@ -65,7 +65,7 @@ function compileMessageWithMultipleVariants(declarations, message, variants) {
             }
             const variableType = declarations.find((decl) => decl.name === match.key)?.type;
             if (variableType === "input-variable") {
-                conditions.push(`i.${match.key} == ${doubleQuote(match.value)}`);
+                conditions.push(`i?.${match.key} == ${doubleQuote(match.value)}`);
             }
             else if (variableType === "local-variable") {
                 conditions.push(`${match.key} == ${doubleQuote(match.value)}`);
@@ -73,7 +73,7 @@ function compileMessageWithMultipleVariants(declarations, message, variants) {
         }
         if (conditions.length === 0)
             continue;
-        compiledVariants.push(`if (${conditions.join(" && ")}) return ${compiledPattern.code};`);
+        compiledVariants.push(`if (${conditions.join(" && ")}) return /** @type {LocalizedString} */ (${compiledPattern.code});`);
     }
     const compiledLocalVariables = [];
     for (const declaration of declarations) {
@@ -81,9 +81,9 @@ function compileMessageWithMultipleVariants(declarations, message, variants) {
             compiledLocalVariables.push(compileLocalVariable({ declaration, locale: message.locale }));
         }
     }
-    const code = `/** @type {(inputs: ${inputsType(inputs)}) => string} */ (${hasInputs ? "i" : ""}) => {${compiledLocalVariables.join("\n\t")}
+    const code = `/** @type {(inputs: ${inputsType(inputs)}) => LocalizedString} */ (${hasInputs ? "i" : ""}) => {${compiledLocalVariables.join("\n\t")}
 	${compiledVariants.join("\n\t")}
-	${hasCatchAll ? "" : `return "${message.bundleId}";`}
+	${hasCatchAll ? "" : `return /** @type {LocalizedString} */ ("${message.bundleId}");`}
 };`;
     return { code, node: message };
 }

package/dist/compiler/compile-message.test.js

@@ -142,7 +142,7 @@ test("only emits input arguments when inputs exist", async () => {
         },
     ];
     const compiled = compileMessage(declarations, message, variants);
-    expect(compiled.code).toBe("/** @type {(inputs: {}) => string} */ () => {\n\treturn `Hello`\n};");
+    expect(compiled.code).toBe("/** @type {(inputs: {}) => LocalizedString} */ () => {\n\treturn /** @type {LocalizedString} */ (`Hello`)\n};");
 });
 // https://github.com/opral/inlang-paraglide-js/issues/379
 test("compiles messages that use plural()", async () => {
@@ -198,6 +198,90 @@ test("compiles messages that use plural()", async () => {
     // INTL.plural will match "other" for undefined
     expect(plural_test({ count: undefined })).toBe("There are many cats.");
 });
+test("compiles messages that use plural() with ordinal type", async () => {
+    const declarations = [
+        { type: "input-variable", name: "count" },
+        {
+            type: "local-variable",
+            name: "countOrdinal",
+            value: {
+                arg: { type: "variable-reference", name: "count" },
+                annotation: {
+                    type: "function-reference",
+                    name: "plural",
+                    options: [
+                        { name: "type", value: { type: "literal", value: "ordinal" } },
+                    ],
+                },
+                type: "expression",
+            },
+        },
+    ];
+    const message = {
+        locale: "en",
+        bundleId: "ordinal_test",
+        id: "message_id",
+        selectors: [{ type: "variable-reference", name: "countOrdinal" }],
+    };
+    const variants = [
+        {
+            id: "1",
+            messageId: "message_id",
+            matches: [{ type: "literal-match", value: "one", key: "countOrdinal" }],
+            pattern: [
+                {
+                    type: "expression",
+                    arg: { type: "variable-reference", name: "count" },
+                },
+                { type: "text", value: "st place" },
+            ],
+        },
+        {
+            id: "2",
+            messageId: "message_id",
+            matches: [{ type: "literal-match", value: "two", key: "countOrdinal" }],
+            pattern: [
+                {
+                    type: "expression",
+                    arg: { type: "variable-reference", name: "count" },
+                },
+                { type: "text", value: "nd place" },
+            ],
+        },
+        {
+            id: "3",
+            messageId: "message_id",
+            matches: [{ type: "literal-match", value: "few", key: "countOrdinal" }],
+            pattern: [
+                {
+                    type: "expression",
+                    arg: { type: "variable-reference", name: "count" },
+                },
+                { type: "text", value: "rd place" },
+            ],
+        },
+        {
+            id: "4",
+            messageId: "message_id",
+            matches: [{ type: "literal-match", value: "other", key: "countOrdinal" }],
+            pattern: [
+                {
+                    type: "expression",
+                    arg: { type: "variable-reference", name: "count" },
+                },
+                { type: "text", value: "th place" },
+            ],
+        },
+    ];
+    const compiled = compileMessage(declarations, message, variants);
+    const { ordinal_test } = await import("data:text/javascript;base64," +
+        btoa(createRegistry()) +
+        btoa("export const ordinal_test = " + compiled.code.replace("registry.", "")));
+    expect(ordinal_test({ count: 1 })).toBe("1st place");
+    expect(ordinal_test({ count: 2 })).toBe("2nd place");
+    expect(ordinal_test({ count: 3 })).toBe("3rd place");
+    expect(ordinal_test({ count: 4 })).toBe("4th place");
+});
 test("compiles messages that use datetime()", async () => {
     const createMessage = async (locale) => {
         const declarations = [
@@ -306,3 +390,65 @@ test("compiles messages that use datetime a function with options", async () =>
     expect(enMessage({ date: "2022-03-31" })).toMatch(/Today is March \d{1,2}\./);
     expect(deMessage({ date: "2022-03-31" })).toMatch(/Today is \d{1,2}\. März\./);
 });
+test("does not throw when input is omitted for a single-variant message", async () => {
+    const declarations = [
+        { type: "input-variable", name: "name" },
+    ];
+    const message = {
+        locale: "en",
+        bundleId: "greeting",
+        id: "greeting",
+        selectors: [{ type: "variable-reference", name: "name" }],
+    };
+    const variants = [
+        {
+            id: "1",
+            messageId: "greeting",
+            matches: [{ type: "catchall-match", key: "name" }],
+            pattern: [
+                { type: "text", value: "Hello " },
+                {
+                    type: "expression",
+                    arg: { type: "variable-reference", name: "name" },
+                },
+                { type: "text", value: "!" },
+            ],
+        },
+    ];
+    const compiled = compileMessage(declarations, message, variants);
+    const { greeting } = await import("data:text/javascript;base64," +
+        btoa("export const greeting = " + compiled.code));
+    expect(() => greeting()).not.toThrow();
+    expect(greeting()).toBe("Hello undefined!");
+});
+test("does not throw when input is omitted for multi-variant message", async () => {
+    const declarations = [
+        { type: "input-variable", name: "status" },
+    ];
+    const message = {
+        locale: "en",
+        bundleId: "status_message",
+        id: "status_message",
+        selectors: [{ type: "variable-reference", name: "status" }],
+    };
+    const variants = [
+        {
+            id: "1",
+            messageId: "status_message",
+            matches: [{ type: "literal-match", key: "status", value: "ready" }],
+            pattern: [{ type: "text", value: "Ready to go" }],
+        },
+        {
+            id: "2",
+            messageId: "status_message",
+            matches: [{ type: "catchall-match", key: "status" }],
+            pattern: [{ type: "text", value: "Unknown status" }],
+        },
+    ];
+    const compiled = compileMessage(declarations, message, variants);
+    const { status_message } = await import("data:text/javascript;base64," +
+        btoa("export const status_message = " + compiled.code));
+    expect(status_message({ status: "ready" })).toBe("Ready to go");
+    expect(() => status_message()).not.toThrow();
+    expect(status_message()).toBe("Unknown status");
+});

package/dist/compiler/compile-pattern.d.ts

@@ -11,7 +11,7 @@ import type { Compiled } from "./types.js";
  *
  *   const { code } = compilePattern({ pattern, declarations: [{ type: "input-variable", name: "age" }] });
  *
- *   // code will be: `Your age is ${i.age}`
+ *   // code will be: `Your age is ${i?.age}`
  */
 export declare const compilePattern: (args: {
     pattern: Pattern;

package/dist/compiler/compile-pattern.js

@@ -10,7 +10,7 @@ import { escapeForTemplateLiteral } from "../services/codegen/escape.js";
  *
  *   const { code } = compilePattern({ pattern, declarations: [{ type: "input-variable", name: "age" }] });
  *
- *   // code will be: `Your age is ${i.age}`
+ *   // code will be: `Your age is ${i?.age}`
  */
 export const compilePattern = (args) => {
     let result = "";
@@ -22,7 +22,7 @@ export const compilePattern = (args) => {
             if (part.arg.type === "variable-reference") {
                 const declaration = args.declarations.find((decl) => decl.name === part.arg.name);
                 if (declaration?.type === "input-variable") {
-                    result += `\${i.${part.arg.name}}`;
+                    result += `\${i?.${part.arg.name}}`;
                 }
                 else if (declaration?.type === "local-variable") {
                     result += `\${${part.arg.name}}`;

package/dist/compiler/compile-pattern.test.js

@@ -26,7 +26,7 @@ test("should compile a pattern with multiple VariableReference's", () => {
             { type: "input-variable", name: "count" },
         ],
     });
-    expect(code).toBe("`Hello ${i.name}! You have ${i.count} messages.`");
+    expect(code).toBe("`Hello ${i?.name}! You have ${i?.count} messages.`");
 });
 test("should escape backticks", () => {
     const pattern = [{ type: "text", value: "`Hello world`" }];

package/dist/compiler/compile-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-project.d.ts","sourceRoot":"","sources":["../../src/compiler/compile-project.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAIrE,OAAO,EAEN,KAAK,eAAe,EACpB,MAAM,uBAAuB,CAAC;AAU/B;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAU,MAAM;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;CACrE,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuEjC,CAAC;AAEF,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC9C,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,GACpB,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAY1B"}
+{"version":3,"file":"compile-project.d.ts","sourceRoot":"","sources":["../../src/compiler/compile-project.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAIrE,OAAO,EAEN,KAAK,eAAe,EACpB,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAU,MAAM;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAC,CAAC;CACrE,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4EjC,CAAC;AAEF,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC9C,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,GACpB,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAY1B"}

package/dist/compiler/compile-project.js

@@ -7,6 +7,7 @@ import { defaultCompilerOptions, } from "./compiler-options.js";
 import { createRuntimeFile } from "./runtime/create-runtime.js";
 import { createServerFile } from "./server/create-server-file.js";
 import { createRegistry } from "./registry.js";
+import { emitTsDeclarations } from "./emit-ts-declarations.js";
 const outputStructures = {
     "locale-modules": localeModules,
     "message-modules": messageModules,
@@ -73,6 +74,10 @@ export const compileProject = async (args) => {
             }
         }
     }
+    if (optionsWithDefaults.emitTsDeclarations) {
+        const declarations = await emitTsDeclarations(output);
+        Object.assign(output, declarations);
+    }
     return output;
 };
 export function getFallbackMap(locales, baseLocale) {

package/dist/compiler/compile-project.test.js

@@ -61,6 +61,18 @@ test("emitPrettierIgnore", async () => {
     expect(_true).toHaveProperty(".prettierignore");
     expect(_false).not.toHaveProperty(".prettierignore");
 });
+test("emitTsDeclarations generates declaration files", async () => {
+    const output = await compileProject({
+        project,
+        compilerOptions: {
+            emitTsDeclarations: true,
+            outputStructure: "locale-modules",
+        },
+    });
+    expect(output).toHaveProperty("messages/_index.d.ts");
+    expect(output).toHaveProperty("messages.d.ts");
+    expect(output["messages/_index.d.ts"]).toContain("sad_penguin_bundle");
+});
 test("handles message bundles with a : in the id", async () => {
     const project = await loadProjectInMemory({
         blob: await newProject({

package/dist/compiler/compiler-options.d.ts

@@ -4,6 +4,7 @@ export declare const defaultCompilerOptions: {
     readonly emitGitIgnore: true;
     readonly includeEslintDisableComment: true;
     readonly emitPrettierIgnore: true;
+    readonly emitTsDeclarations: false;
     readonly cleanOutdir: true;
     readonly disableAsyncLocalStorage: false;
     readonly experimentalMiddlewareLocaleSplitting: false;
@@ -164,6 +165,29 @@ export type CompilerOptions = {
      * @default true
      */
     emitPrettierIgnore?: boolean;
+    /**
+     * Emit `.d.ts` files for the generated output using the TypeScript compiler.
+     *
+     * Useful when `allowJs: true` cannot be set in your `tsconfig.json`
+     * (e.g., due to project constraints or conflicting compiler options).
+     *
+     * Requires `typescript` to be resolvable in your toolchain.
+     *
+     * **Note:** Enabling this option reduces compiler speed because TypeScript
+     * needs to generate declaration files for all output modules.
+     *
+     * @example
+     * ```ts
+     * await compile({
+     *   project: "./project.inlang",
+     *   outdir: "./src/paraglide",
+     *   emitTsDeclarations: true,
+     * });
+     * ```
+     *
+     * @default false
+     */
+    emitTsDeclarations?: boolean;
     /**
      * https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#url
      */

package/dist/compiler/compiler-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler-options.d.ts","sourceRoot":"","sources":["../../src/compiler/compiler-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;CAcU,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC7B;;;;;;;;;;OAUG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/B;;;;;;;;;;;;;;OAcG;IACH,qCAAqC,CAAC,EAAE,OAAO,CAAC;IAChD;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACrC;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,eAAe,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACvD;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;OAIG;IACH,EAAE,CAAC,EAAE,GAAG,CAAC;CACT,CAAC"}
+{"version":3,"file":"compiler-options.d.ts","sourceRoot":"","sources":["../../src/compiler/compiler-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;CAeU,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC7B;;;;;;;;;;OAUG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/B;;;;;;;;;;;;;;OAcG;IACH,qCAAqC,CAAC,EAAE,OAAO,CAAC;IAChD;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACrC;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,eAAe,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACvD;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;OAIG;IACH,EAAE,CAAC,EAAE,GAAG,CAAC;CACT,CAAC"}

package/dist/compiler/compiler-options.js

@@ -3,6 +3,7 @@ export const defaultCompilerOptions = {
     emitGitIgnore: true,
     includeEslintDisableComment: true,
     emitPrettierIgnore: true,
+    emitTsDeclarations: false,
     cleanOutdir: true,
     disableAsyncLocalStorage: false,
     experimentalMiddlewareLocaleSplitting: false,

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,CA8HjC"}

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

@@ -0,0 +1,100 @@
+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,
+        isolatedDeclarations: 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,CA+GxB"}
+{"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

@@ -56,10 +56,10 @@ export function generateOutput(compiledBundles, settings, fallbackMap) {
             }
             if (fallbackLocale) {
                 const safeFallbackLocale = toSafeModuleId(fallbackLocale);
-                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 {
-                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);
@@ -68,9 +68,10 @@ export function generateOutput(compiledBundles, settings, fallbackMap) {
             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
@@ -80,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/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/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.5.0",
+    PARJS_PACKAGE_VERSION: "2.7.0",
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inlang/paraglide-js",
   "type": "module",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -31,8 +31,8 @@
     "json5": "2.2.3",
     "unplugin": "^2.1.2",
     "urlpattern-polyfill": "^10.0.0",
-    "@inlang/recommend-sherlock": "0.2.1",
-    "@inlang/sdk": "2.4.9"
+    "@inlang/sdk": "2.4.9",
+    "@inlang/recommend-sherlock": "0.2.1"
   },
   "devDependencies": {
     "@rollup/plugin-virtual": "3.0.2",