@inlang/paraglide-js 1.5.0 → 1.6.0

package/README.md

@@ -85,7 +85,33 @@ m.hello() // Hello world!
 m.loginHeader({ name: "Samuel" }) // Hello Samuel, please login to continue.
 ```
 
-To choose between messages at runtime create a map of messages and index into it.
+## Working with the Inlang Message Format
+
+Paraglide is part of the highly modular Inlang Ecosystem which supports many different Message Formats. By default, the [Inlang Message Format](https://inlang.com/m/reootnfj/plugin-inlang-messageFormat) is used. 
+
+It expects messages to be in `messages/{lang}.json` relative to your repo root.
+
+```json
+//messages/en.json
+{
+	//the $schema key is automatically ignored 
+	"$schema": "https://inlang.com/schema/inlang-message-format",
+	"hello_world: "Hello World!",
+	"greeting": "Hello {name}!"
+}
+```
+
+The `messages/{lang}.json` file contains a flat map of message IDs and their translations. You can use curly braces to insert `{parameters}` into translations
+
+**Nesting purposely isn't supported and likely won't be**. Nested messages are way harder to interact with from complementary tools like the [Sherlock IDE Extension](https://inlang.com/m/r7kp499g/app-inlang-ideExtension), the [Parrot Figma Plugin](https://inlang.com/m/gkrpgoir/app-parrot-figmaPlugin), or the [Fink Localization editor](https://inlang.com/m/tdozzpar/app-inlang-finkLocalizationEditor). Intellisense also becomes less helpful since it only shows the messages at the current level, not all messages. Additionally enforcing an organization-style side-steps organization discussions with other contributors. 
+
+### Complex Formatting
+
+The Message Format is still quite young, so advanced formats like plurals, param-formatting, and markup interpolation are currently not supported but are all on our roadmap.
+
+If you need complex formatting, like plurals, dates, currency, or markup interpolation you can achieve them like so:
+
+For a message with multiple cases, aka a _select message_, you can define a message for each case & then use a Map in JS to index into it.
 
 ```ts
 import * as m from "./paraglide/messages.js"
@@ -100,9 +126,46 @@ const season = {
 const msg = season["spring"]() // Hello spring!
 ```
 
+For date & currency formatting use the `.toLocaleString` method on the `Date` or `Number`.
+
+```ts
+import * as m from "./paraglide/messages.js"
+import { languageTag } from "./paraglide/runtime.js"
+
+const todaysDate = new Date();
+m.today_is_the({ 
+	date: todaysDate.toLocaleString(languageTag()) 
+})
+
+const price = 100;
+m.the_price_is({
+	price: price.toLocaleString(languageTag(), {
+		style: "currency",
+		currency: "EUR",
+	})
+})
+```
+
+You can put HTML into the messages. This is useful for links and images. 
+
+```json
+// messages/en.json
+{
+	"you_must_agree_to_the_tos": "You must agree to the <a href='/en/tos'>Terms of Service</a>."
+}
+```
+```json
+// messages/de.json
+{
+	you_must_agree_to_the_tos": "Sie müssen den <a href='/de/agb'>Nutzungsbedingungen</a> zustimmen."
+}
+```
+
+There is currently no way to interpolate full-blown components into the messages. If you require components mid-message you will need to create a one-off component for that bit of text.
+
 ## Setting the language
 
-You can set the [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) by calling `setLanguageTag()`. Any subsequent calls to either `languageTag()` or a message function will use the new language tag.
+You can set the [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) by calling `setLanguageTag()` with the desired language, or a getter function. Any subsequent calls to either `languageTag()` or a message function will use the new language tag.
 
 ```js
 import { setLanguageTag } from "./paraglide/runtime.js"
@@ -111,11 +174,11 @@ import * as m from "./paraglide/messages.js"
 setLanguageTag("de")
 m.hello() // Hallo Welt!
 
-setLanguageTag("en")
+setLanguageTag(()=>document.documentElement.lang /* en */ )
 m.hello() // Hello world!
 ```
 
-The [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) is global, so you need to be careful with it on the server to make sure multiple requests don't interfere with each other.
+The [language tag](https://www.inlang.com/m/8y8sxj09/library-inlang-languageTag) is global, so you need to be careful with it on the server to make sure multiple requests don't interfere with each other. Always use a getter-function that returns the current language tag _for the current request_.
 
 You will need to call `setLanguageTag` on both the server and the client since they run in separate processes.
 
@@ -137,7 +200,7 @@ setLanguageTag("de") // The language changed to de
 setLanguageTag("en") // The language changed to en
 ```
 
-A few things to know about `onSetLanguageTag()`:
+Things to know about `onSetLanguageTag()`:
 
 - You can only register one listener. If you register a second listener it will throw an error.
 - `onSetLanguageTag` shouldn't be used on the server.
@@ -160,10 +223,9 @@ const msg = m.hello({ name: "Samuel" }, { languageTag: "de" }) // Hallo Samuel!
 
 ## Lazy-Loading
 
-Paraglide consciously discourages lazy-loading translations since it seriously hurts
-your Web Vitals. Learn more about why lazy-loading is bad & what to do instead in [our blog post on lazy-loading](https://inlang.com/g/mqlyfa7l/guide-lorissigrist-dontlazyload). 
+Paraglide consciously discourages lazy-loading translations since it causes a render-fetch waterfall which seriously hurts your Web Vitals. Learn more about why lazy-loading is bad & what to do instead in [our blog post on lazy-loading](https://inlang.com/g/mqlyfa7l/guide-lorissigrist-dontlazyload). 
 
-If you want to do it anyway, lazily import the language-specific message files. Be careful with this.
+If you want to do it anyway, lazily import the language-specific message files. 
 
 ```ts
 const lazyGerman = await import("./paraglide/messages/de.js")
@@ -203,18 +265,14 @@ If you want your language files to be in a different location you can change the
 
 ```diff
 // project.inlang/settings.json
-"plugin.inlang.messageFormat": {
--	"pathPattern": "./messages/{languageTag}.json"
-+	"pathPattern": "./i18n/{languageTag}.json"
-},
+{
+	"plugin.inlang.messageFormat": {
+-		"pathPattern": "./messages/{languageTag}.json"
++		"pathPattern": "./i18n/{languageTag}.json"
+	}
+}
 ```
 
-### Lint Rules
-
-If you're using the [Sherlock VS Code extension](https://inlang.com/m/r7kp499g/app-inlang-ideExtension) you might see warnings about certain messages. Perhaps they're duplicates, perhaps they're missing in one language. 
-
-You can configure which lint-rules are active in `./project.inlang/settings.json`. Simply add or remove them from the `modules` array.
-
 # Playground
 
 Find examples of how to use Paraglide on CodeSandbox or in [our GitHub repository](https://github.com/opral/monorepo/tree/main/inlang/source-code/paraglide).
@@ -227,11 +285,11 @@ Find examples of how to use Paraglide on CodeSandbox or in [our GitHub repositor
 
 # Architecture
 
-ParaglideJS leverages a compiler to generate vanilla JavaScript functions from your messages. We call these "message functions".
+Paraglide uses a compiler to generate JS functions from your messages. We call these "message functions". 
 
-Message Functions are fully typed using JSDoc. They are exported individually from the `messages.js` file making them tree-shakable. They aren't reactive, they just return a string.
+Message Functions are fully typed using JSDoc. They are exported individually from the `messages.js` file making them tree-shakable. When called, they return a translated string. Message functions aren't reactive in any way, if you want a translation in another language you will need to re-call them.
 
-This avoids many edge cases associated with reactivity, lazy-loading, and namespacing that other i18n libraries have to work around.
+This design avoids many edge cases with reactivity, lazy-loading, and namespacing that other i18n libraries have to work around.
 
 In addition to the message functions, ParaglideJS also emits a runtime. The runtime is used to set the language tag. It contains less than 50 LOC (lines of code) and is less than 300 bytes minified & gzipped.
 
@@ -271,16 +329,6 @@ The compiler loads an Inlang project and compiles the messages into tree-shakabl
 export const hello = (params) => `Hello ${params.name}!`
 ```
 
-## Messages
-
-By convention, we import the compiled functions with a wildcard import.
-
-```js
-import * as m from "../paraglide/messages.js"
-```
-
-Bundlers like Rollup, Webpack, or Turbopack tree-shake the messages that are not used, so using a wildcard import is perfectly fine.
-
 # Writing an Adapter
 
 An "Adapter" is a library that integrates with a framework's lifecycle and does two things:
@@ -288,7 +336,9 @@ An "Adapter" is a library that integrates with a framework's lifecycle and does
 1. Calls `setLanguageTag()` at appropriate times to set the language
 2. Reacts to `onSetLanguageTag()`, usually by navigating or relading the page.
 
-This example adapts Paraglide to a fictitious full-stack framework.
+Many popular frameworks already have adapters available, check out the [list of available adapters](#use-it-with-your-favorite-framework).
+
+If there isn't one for your framework, you can write your own. This example adapts Paraglide to a fictitious full-stack framework.
 
 ```tsx
 import {
@@ -316,7 +366,7 @@ if (isClient) {
 
 	// When the language changes we want to re-render the page in the new language
 	// Here we just navigate to the new route
-	//
+
 	// Make sure to call `onSetLanguageTag` after `setLanguageTag` to avoid an infinite loop.
 	onSetLanguageTag((newLanguageTag) => {
 		window.location.pathname = `/${newLanguageTag}${window.location.pathname}`
@@ -338,6 +388,8 @@ Of course, we're not done yet! We plan on adding the following features to Parag
 - [ ] Pluralization ([Join the Discussion](https://github.com/opral/monorepo/discussions/2025))
 - [ ] Formatting of numbers and dates ([Join the Discussion](https://github.com/opral/monorepo/discussions/992))
 - [ ] Markup Placeholders ([Join the Discussion](https://github.com/opral/monorepo/discussions/913))
+- [ ] Component Interpolation
+- [ ] Per-Language Splitting without Lazy-Loading 
 - [ ] Even Smaller Output
 
 # Talks
@@ -347,7 +399,7 @@ Of course, we're not done yet! We plan on adding the following features to Parag
 - Web Zurich December 2023
 - [Svelte London January 2024](https://www.youtube.com/watch?v=eswNQiq4T2w&t=646s)
 
-# Tooling
+# Complementary Tooling
 
 Paraglide JS is part of the Inlang ecosystem and integrates nicely with all the other Inlang-compatible tools.
 

package/dist/adapter-utils/index.d.ts

@@ -0,0 +1,4 @@
+export { negotiateLanguagePreferences } from './negotiation/language.js';
+export { detectLanguageFromPath } from './routing/detectLanguage.js';
+export { bestMatch, resolveRoute, parseRouteDefinition, exec, type PathDefinitionTranslations, type ParamMatcher, type RouteParam, } from './routing/routeDefinitions.js';
+export { validatePathTranslations, prettyPrintIssues } from './routing/validatePathTranslations.js';

package/dist/adapter-utils/index.js

@@ -0,0 +1,375 @@
+function negotiateLanguagePreferences(accept, availableLanguageTags) {
+  if (availableLanguageTags.length === 0)
+    return [];
+  accept ||= "*";
+  const acceptLanguageSpecs = parseAcceptLanguageHeader(accept);
+  const priorities = availableLanguageTags.map(
+    (languageTag, index) => getHighestLanguagePriority(languageTag, acceptLanguageSpecs, index)
+  );
+  return priorities.filter((prio) => prio.quality > 0).sort(comparePriorities).map((priority) => priority.languageTag);
+}
+function parseAcceptLanguageHeader(acceptLanguage) {
+  const acceptableLanguageDefinitions = acceptLanguage.split(",");
+  const specs = acceptableLanguageDefinitions.map((dfn) => dfn.trim()).map((dfn, index) => parseLanguage(dfn, index)).filter((maybeSpec) => Boolean(maybeSpec));
+  return specs;
+}
+function parseLanguage(str, index) {
+  const LANGUAGE_REGEXP = /^\s*([^\s\-;]+)(?:-([^\s;]+))?\s*(?:;(.*))?$/;
+  const match = LANGUAGE_REGEXP.exec(str);
+  if (!match)
+    return void 0;
+  const [, prefix, suffix, qualityMatch] = match;
+  if (!prefix)
+    throw new Error(`Invalid language tag: ${str}`);
+  const full = suffix ? `${prefix}-${suffix}` : prefix;
+  const quality = qualityMatch ? parseQuality(qualityMatch) ?? 1 : 1;
+  return {
+    prefix,
+    suffix,
+    quality,
+    index,
+    full
+  };
+}
+function parseQuality(qualityMatch) {
+  const params = qualityMatch.split(";");
+  for (const param of params) {
+    const [key, value] = param.split("=");
+    if (key === "q" && value)
+      return parseFloat(value);
+  }
+  return void 0;
+}
+function getHighestLanguagePriority(availableLanguageTag, acceptableLanguages, index) {
+  let highestPriority = {
+    languageTag: availableLanguageTag,
+    index: 0,
+    order: -1,
+    quality: 0,
+    specificity: 0
+  };
+  for (const acceptableLanguage of acceptableLanguages) {
+    const priority = calculatePriority(availableLanguageTag, acceptableLanguage, index);
+    if (!priority)
+      continue;
+    if (
+      //compare the calculated priority to the highest priority ignoring quality.
+      (highestPriority.specificity - priority.specificity || highestPriority.quality - priority.quality || highestPriority.order - priority.order) < 0
+    ) {
+      highestPriority = priority;
+    }
+  }
+  return highestPriority;
+}
+function calculatePriority(language, spec, index) {
+  const parsed = parseLanguage(language, 0);
+  if (!parsed)
+    return void 0;
+  let specificity = 0;
+  if (spec.full.toLowerCase() === parsed.full.toLowerCase()) {
+    specificity |= 4;
+  } else if (spec.prefix.toLowerCase() === parsed.full.toLowerCase()) {
+    specificity |= 2;
+  } else if (spec.full.toLowerCase() === parsed.prefix.toLowerCase()) {
+    specificity |= 1;
+  }
+  if (specificity === 0 && spec.full !== "*") {
+    return void 0;
+  }
+  return {
+    languageTag: language,
+    index,
+    order: spec.index,
+    quality: spec.quality,
+    specificity
+  };
+}
+function comparePriorities(a, b) {
+  return b.quality - a.quality || b.specificity - a.specificity || a.order - b.order || a.index - b.index || 0;
+}
+function detectLanguageFromPath({
+  path,
+  availableLanguageTags,
+  base
+}) {
+  base ??= "";
+  if (base === "/")
+    base = "";
+  if (!path.startsWith(base)) {
+    return void 0;
+  }
+  const pathWithoutBase = path.replace(base, "");
+  const maybeLang = pathWithoutBase.split("/").at(1);
+  if (!maybeLang)
+    return void 0;
+  for (const lang of availableLanguageTags) {
+    if (lang.toLowerCase() === maybeLang.toLowerCase()) {
+      return lang;
+    }
+  }
+  return void 0;
+}
+const param_pattern = /^(\[)?(\.\.\.)?(\w+)(?:=(\w+))?(\])?$/;
+function parseRouteDefinition(id) {
+  const params = [];
+  const pattern = id === "/" ? /^\/$/ : new RegExp(
+    `^${get_route_segments(id).map((segment) => {
+      const rest_match = /^\[\.\.\.(\w+)(?:=(\w+))?\]$/.exec(segment);
+      if (rest_match) {
+        params.push({
+          name: rest_match[1],
+          matcher: rest_match[2],
+          optional: false,
+          rest: true,
+          chained: true
+        });
+        return "(?:/(.*))?";
+      }
+      const optional_match = /^\[\[(\w+)(?:=(\w+))?\]\]$/.exec(segment);
+      if (optional_match) {
+        params.push({
+          name: optional_match[1],
+          matcher: optional_match[2],
+          optional: true,
+          rest: false,
+          chained: true
+        });
+        return "(?:/([^/]+))?";
+      }
+      if (!segment) {
+        return;
+      }
+      const parts = segment.split(/\[(.+?)\](?!\])/);
+      const result = parts.map((content, i) => {
+        if (i % 2) {
+          if (content.startsWith("x+")) {
+            return escape(String.fromCharCode(parseInt(content.slice(2), 16)));
+          }
+          if (content.startsWith("u+")) {
+            return escape(
+              String.fromCharCode(
+                ...content.slice(2).split("-").map((code) => parseInt(code, 16))
+              )
+            );
+          }
+          const match = (
+            /** @type {RegExpExecArray} */
+            param_pattern.exec(content)
+          );
+          if (!match) {
+            throw new Error(
+              `Invalid param: ${content}. Params and matcher names can only have underscores and alphanumeric characters.`
+            );
+          }
+          const [, is_optional, is_rest, name, matcher] = match;
+          params.push({
+            name,
+            matcher,
+            optional: !!is_optional,
+            rest: !!is_rest,
+            chained: is_rest ? i === 1 && parts[0] === "" : false
+          });
+          return is_rest ? "(.*?)" : is_optional ? "([^/]*)?" : "([^/]+?)";
+        }
+        return escape(content);
+      }).join("");
+      return "/" + result;
+    }).join("")}/?$`
+  );
+  return { pattern, params };
+}
+function exec(match, params, matchers) {
+  const result = {};
+  const values = match.slice(1);
+  const values_needing_match = values.filter((value) => value !== void 0);
+  let buffered = 0;
+  for (const [i, param] of params.entries()) {
+    let value = values[i - buffered];
+    if (param.chained && param.rest && buffered) {
+      value = values.slice(i - buffered, i + 1).filter((s) => s).join("/");
+      buffered = 0;
+    }
+    if (value === void 0) {
+      if (param.rest)
+        result[param.name] = "";
+      continue;
+    }
+    if (param.matcher && !matchers[param.matcher]) {
+      return void 0;
+    }
+    const matcher = matchers[param.matcher] ?? (() => true);
+    if (matcher(value)) {
+      result[param.name] = value;
+      const next_param = params[i + 1];
+      const next_value = values[i + 1];
+      if (next_param && !next_param.rest && next_param.optional && next_value && param.chained) {
+        buffered = 0;
+      }
+      if (!next_param && !next_value && Object.keys(result).length === values_needing_match.length) {
+        buffered = 0;
+      }
+      continue;
+    }
+    if (param.optional && param.chained) {
+      buffered++;
+      continue;
+    }
+    return;
+  }
+  if (buffered)
+    return;
+  return result;
+}
+function escape(str) {
+  return str.normalize().replace(/[[\]]/g, "\\$&").replace(/%/g, "%25").replace(/\//g, "%2[Ff]").replace(/\?/g, "%3[Ff]").replace(/#/g, "%23").replace(/[.*+?^${}()|\\]/g, "\\$&");
+}
+const basic_param_pattern = /\[(\[)?(\.\.\.)?(\w+?)(?:=(\w+))?\]\]?/g;
+function resolveRoute(id, params) {
+  const segments = get_route_segments(id);
+  return "/" + segments.map(
+    (segment) => segment.replace(basic_param_pattern, (_, optional, rest, name) => {
+      const param_value = params[name];
+      if (!param_value) {
+        if (optional)
+          return "";
+        if (rest && param_value !== void 0)
+          return "";
+        throw new Error(`Missing parameter '${name}' in route ${id}`);
+      }
+      if (param_value.startsWith("/") || param_value.endsWith("/"))
+        throw new Error(
+          `Parameter '${name}' in route ${id} cannot start or end with a slash -- this would cause an invalid route like foo//bar`
+        );
+      return param_value;
+    })
+  ).filter(Boolean).join("/");
+}
+function bestMatch(canonicalPath, pathDefinitions, matchers) {
+  let bestMatch2 = void 0;
+  for (const pathDefinition of pathDefinitions) {
+    const route = parseRouteDefinition(pathDefinition);
+    const match = route.pattern.exec(removeTrailingSlash(canonicalPath));
+    if (!match)
+      continue;
+    const params = exec(match, route.params, matchers);
+    if (!params)
+      continue;
+    if (!bestMatch2) {
+      bestMatch2 = { params, route, id: pathDefinition };
+      continue;
+    }
+    const bestMatchNumParams = Object.keys(bestMatch2.route.params).length;
+    const currentMatchNumParams = Object.keys(route.params).length;
+    if (bestMatchNumParams < currentMatchNumParams) {
+      continue;
+    }
+    if (bestMatchNumParams > currentMatchNumParams) {
+      bestMatch2 = { params, route, id: pathDefinition };
+      continue;
+    }
+    if (bestMatchNumParams === currentMatchNumParams && route.pattern.source.length < bestMatch2.route.pattern.source.length) {
+      bestMatch2 = { params, route, id: pathDefinition };
+    }
+  }
+  return bestMatch2 ? {
+    id: bestMatch2.id,
+    params: bestMatch2.params
+  } : void 0;
+}
+function removeTrailingSlash(path) {
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+function get_route_segments(route) {
+  return route.slice(1).split("/");
+}
+function validatePathTranslations(pathTranslations, availableLanguageTags, matchers) {
+  const issues = [];
+  const expectedLanguages = new Set(availableLanguageTags);
+  const availableMatchers = new Set(Object.keys(matchers));
+  for (const path in pathTranslations) {
+    if (!isValidPath(path)) {
+      issues.push({
+        path,
+        message: "Path must start with a slash."
+      });
+      continue;
+    }
+    const { params: expectedParams } = parseRouteDefinition(path);
+    const expectedMatchers = expectedParams.map((param) => param.matcher).filter(Boolean);
+    for (const matcher of expectedMatchers) {
+      if (!availableMatchers.has(matcher)) {
+        issues.push({
+          path,
+          message: `Matcher ${matcher} is used but not available. Did you forget to pass it to createI18n?`
+        });
+      }
+    }
+    const translations = pathTranslations[path];
+    if (!translations)
+      continue;
+    for (const [lang, translatedPath] of Object.entries(translations)) {
+      if (!isValidPath(translatedPath)) {
+        issues.push({
+          path,
+          message: `The translation for language ${lang} must start with a slash.`
+        });
+      }
+      const { params: actualParams } = parseRouteDefinition(translatedPath);
+      let paramsDontMatch = false;
+      for (const param of expectedParams) {
+        if (!actualParams.some((actualParam) => paramsAreEqual(param, actualParam))) {
+          paramsDontMatch = true;
+        }
+      }
+      if (expectedParams.length !== actualParams.length) {
+        paramsDontMatch = true;
+      }
+      if (paramsDontMatch) {
+        issues.push({
+          path,
+          message: `The translation for language ${lang} must have the same parameters as the canonical path.`
+        });
+      }
+    }
+    const translatedLanguages = new Set(Object.keys(translations));
+    if (!isSubset(expectedLanguages, translatedLanguages)) {
+      const missingLanguages = new Set(expectedLanguages);
+      for (const lang of translatedLanguages) {
+        missingLanguages.delete(lang);
+      }
+      issues.push({
+        path,
+        message: `The following languages are missing translations: ${[...missingLanguages].join(
+          ", "
+        )}`
+      });
+    }
+  }
+  return issues;
+}
+function paramsAreEqual(param1, param2) {
+  return param1.chained == param2.chained && param1.matcher == param2.matcher && param1.name == param2.name && param1.optional == param2.optional && param1.rest == param2.rest;
+}
+function isValidPath(maybePath) {
+  return maybePath.startsWith("/");
+}
+function isSubset(a, b) {
+  for (const value of a) {
+    if (!b.has(value))
+      return false;
+  }
+  return true;
+}
+function prettyPrintIssues(issues) {
+  return issues.map((issue) => `${issue.path}: ${issue.message}`).join("\n");
+}
+export {
+  bestMatch,
+  detectLanguageFromPath,
+  exec,
+  negotiateLanguagePreferences,
+  parseRouteDefinition,
+  prettyPrintIssues,
+  resolveRoute,
+  validatePathTranslations
+};

package/dist/adapter-utils/negotiation/language.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Negotiates which of the provided language tags is preferred from an Accept-Language header
+ *
+ * @param accept The value of the Accept-Language header. If it's missing, it defaults to "*" as per RFC 2616 sec 14.4
+ * @param availableLanguageTags The BCP 47 language tags that are available
+ *
+ * @returns The acceptable available language tags in descending order of preference
+ */
+export declare function negotiateLanguagePreferences<T extends string = string>(accept: string | undefined | null, availableLanguageTags: readonly T[]): T[];

package/dist/adapter-utils/negotiation/language.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter-utils/routing/detectLanguage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Detects the language tag from the path if present
+ *
+ * If the path is not in the base path, no language will be detected
+ * If the language is not available, no language will be detected
+ *
+ * The language is not case sensitive, eg /de-ch/ and /DE_CH/ will both return "de-CH" if present
+ *
+ * @example
+ * /base/de/ueber-uns -> de
+ * @returns the language tag if present
+ *
+ */
+export declare function detectLanguageFromPath<T extends string>({ path, availableLanguageTags, base, }: {
+    /** The absolute path including the base */
+    path: string;
+    availableLanguageTags: readonly T[];
+    /** The base path */
+    base?: string;
+}): T | undefined;

package/dist/adapter-utils/routing/detectLanguage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter-utils/routing/routeDefinitions.d.ts

@@ -0,0 +1,45 @@
+export type PathDefinitionTranslations<T extends string = string> = {
+    [canonicalPath: `/${string}`]: Record<T, `/${string}`>;
+};
+export type RouteParam = {
+    name: string;
+    matcher: string;
+    optional: boolean;
+    rest: boolean;
+    chained: boolean;
+};
+export type ParamMatcher = (segment: string) => boolean;
+/**
+ * Creates the regex pattern, extracts parameter names, and generates types for a route
+ */
+export declare function parseRouteDefinition(id: string): {
+    params: RouteParam[];
+    pattern: RegExp;
+};
+export declare function exec(match: RegExpMatchArray, params: RouteParam[], matchers: Record<string, ParamMatcher>): Record<string, string> | undefined;
+/**
+ * Populate a route ID with params to resolve a pathname.
+ * @example
+ * ```js
+ * resolveRoute(
+ *   `/blog/[slug]/[...somethingElse]`,
+ *   {
+ *     slug: 'hello-world',
+ *     somethingElse: 'something/else'
+ *   }
+ * ); // `/blog/hello-world/something/else`
+ * ```
+ */
+export declare function resolveRoute(id: string, params: Record<string, string | undefined>): string;
+/**
+ * Returns the id and params for the route that best matches the given path.
+ * @param canonicalPath Canonical pathname excluding the base and language e.g. /foo/bar
+ * @param pathDefinitions An array of pathDefinitions
+ * @param matchers A map of param matcher functions
+ *
+ * @returns undefined if no route matches.
+ */
+export declare function bestMatch(canonicalPath: string, pathDefinitions: string[], matchers: Record<string, ParamMatcher>): {
+    params: Record<string, string>;
+    id: string;
+} | undefined;

package/dist/adapter-utils/routing/routeDefinitions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapter-utils/routing/validatePathTranslations.d.ts

@@ -0,0 +1,15 @@
+import { ParamMatcher, PathDefinitionTranslations } from './routeDefinitions.js';
+
+export type PathTranslationIssue = {
+    path: string;
+    message: string;
+};
+/**
+ * Check that the path translations are valid.
+ * Should only be called in development, this is a waste of time in production.
+ */
+export declare function validatePathTranslations<T extends string>(pathTranslations: PathDefinitionTranslations<T>, availableLanguageTags: readonly T[], matchers: Record<string, ParamMatcher>): PathTranslationIssue[];
+/**
+ * Formats the issues into a nice-looking string that can be logged
+ */
+export declare function prettyPrintIssues(issues: PathTranslationIssue[]): string;

package/dist/adapter-utils/routing/validatePathTranslations.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/compiler/compilePattern.d.ts

@@ -6,11 +6,11 @@
  *  >> compiled === "`Hello ${params.name}`"
  */
 export declare const compilePattern: (pattern: ({
-    type: "Text";
     value: string;
+    type: "Text";
 } | {
-    type: "VariableReference";
     name: string;
+    type: "VariableReference";
 })[]) => {
     params: Record<string, "NonNullable<unknown>">;
     compiled: string;

package/dist/index.d.ts

@@ -2,3 +2,7 @@ export { cli } from './cli/main.js';
 export { compile } from './compiler/compile.js';
 export { writeOutput } from './services/file-handling/write-output.js';
 export { Logger, type LoggerOptions } from './services/logger/index.js';
+export type MessageIndexFunction<T extends string> = (params?: Record<string, never>, options?: {
+    languageTag: T;
+}) => string;
+export type MessageFunction = (params?: Record<string, never>) => string;

package/dist/index.js

@@ -10051,7 +10051,7 @@ function withDefaults$2(oldDefaults, newDefaults) {
   });
 }
 const endpoint = withDefaults$2(null, DEFAULTS);
-const VERSION$c = "8.3.1";
+const VERSION$c = "8.4.0";
 function isPlainObject(value2) {
   if (typeof value2 !== "object" || value2 === null)
     return false;
@@ -10194,7 +10194,7 @@ function getBufferResponse(response) {
   return response.arrayBuffer();
 }
 function fetchWrapper(requestOptions) {
-  var _a2, _b2, _c;
+  var _a2, _b2, _c, _d;
   const log2 = requestOptions.request && requestOptions.request.log ? requestOptions.request.log : console;
   const parseSuccessResponseBody = ((_a2 = requestOptions.request) == null ? void 0 : _a2.parseSuccessResponseBody) !== false;
   if (isPlainObject(requestOptions.body) || Array.isArray(requestOptions.body)) {
@@ -10215,8 +10215,9 @@ function fetchWrapper(requestOptions) {
   return fetch2(requestOptions.url, {
     method: requestOptions.method,
     body: requestOptions.body,
+    redirect: (_c = requestOptions.request) == null ? void 0 : _c.redirect,
     headers: requestOptions.headers,
-    signal: (_c = requestOptions.request) == null ? void 0 : _c.signal,
+    signal: (_d = requestOptions.request) == null ? void 0 : _d.signal,
     // duplex must be set if request.body is ReadableStream or Async Iterables.
     // See https://fetch.spec.whatwg.org/#dom-requestinit-duplex.
     ...requestOptions.body && { duplex: "half" }
@@ -47083,7 +47084,7 @@ const addParaglideJsToDevDependencies = async (ctx) => {
   if (pkg2.devDependencies === void 0) {
     pkg2.devDependencies = {};
   }
-  pkg2.devDependencies["@inlang/paraglide-js"] = "1.5.0";
+  pkg2.devDependencies["@inlang/paraglide-js"] = "1.6.0";
   await ctx.repo.nodeishFs.writeFile("./package.json", stringify2(pkg2));
   ctx.logger.success("Added @inlang/paraglide-js to the devDependencies in package.json.");
   return ctx;
@@ -47437,7 +47438,7 @@ const prompt = async (message, options) => {
   }
   return response;
 };
-const cli = new Command().name("paraglide-js").addCommand(compileCommand).addCommand(initCommand).showHelpAfterError().version("1.5.0");
+const cli = new Command().name("paraglide-js").addCommand(compileCommand).addCommand(initCommand).showHelpAfterError().version("1.6.0");
 export {
   Logger,
   getBasename as a,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inlang/paraglide-js",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -62,14 +62,14 @@
     "vite-plugin-dts": "^3.8.1",
     "vite-tsconfig-paths": "^4.3.2",
     "vitest": "0.34.3",
-    "@inlang/env-variables": "0.2.0",
     "@inlang/cross-sell-sherlock": "0.0.4",
+    "@inlang/env-variables": "0.2.0",
     "@inlang/language-tag": "1.5.1",
     "@inlang/plugin-message-format": "2.1.1",
-    "@inlang/sdk": "0.31.0",
-    "@inlang/telemetry": "0.3.21",
+    "@inlang/telemetry": "0.3.22",
     "@lix-js/client": "1.2.0",
-    "@lix-js/fs": "1.0.0"
+    "@lix-js/fs": "1.0.0",
+    "@inlang/sdk": "0.32.0"
   },
   "exports": {
     ".": {
@@ -79,6 +79,10 @@
     "./internal": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./internal/adapter-utils": {
+      "import": "./dist/adapter-utils/index.js",
+      "types": "./dist/adapter-utils/index.d.ts"
     }
   },
   "scripts": {