@better-translate/tanstack-router 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Alvarenga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @better-translate/tanstack-router
+
+`@better-translate/tanstack-router` adds locale-aware routing and navigation helpers for TanStack Router and TanStack Start. Use it with `@better-translate/core`, and pair it with `@better-translate/react` when your UI renders translations in React components.
+
+Full docs: [better-translate-placeholder.com/en/docs/adapters/tanstack-router](https://better-translate-placeholder.com/en/docs/adapters/tanstack-router)

package/dist/chunk-LRCKROLX.js

@@ -0,0 +1,194 @@
+// src/shared.ts
+var DEFAULT_ROUTE_TEMPLATE = "/{-$locale}";
+function hasLocale(locales, value) {
+  return locales.includes(value);
+}
+function defineRouting(config) {
+  const routeTemplate = config.routeTemplate ?? DEFAULT_ROUTE_TEMPLATE;
+  validateRouting({
+    ...config,
+    routeTemplate
+  });
+  return Object.freeze({
+    locales: [...config.locales],
+    defaultLocale: config.defaultLocale,
+    routeTemplate
+  });
+}
+function normalizePathname(pathname) {
+  if (!pathname) {
+    return "/";
+  }
+  return pathname.startsWith("/") ? pathname : `/${pathname}`;
+}
+function getPathnameLocale(pathname, routing) {
+  return analyzePathname(pathname, routing).explicitLocale;
+}
+function isPathnameInScope(pathname, routing) {
+  return analyzePathname(pathname, routing).inScope;
+}
+function stripLocaleFromPathname(pathname, routing) {
+  const analyzed = analyzePathname(pathname, routing);
+  return analyzed.inScope ? analyzed.deLocalizedPathname : normalizePathname(pathname);
+}
+function localizePathname(pathname, locale, routing) {
+  const normalizedPathname = normalizePathname(pathname);
+  const deLocalizedPathname = stripLocaleFromPathname(
+    normalizedPathname,
+    routing
+  );
+  if (!isPathnameInScope(deLocalizedPathname, routing)) {
+    return normalizedPathname;
+  }
+  const parsedTemplate = parseRouteTemplate(routing.routeTemplate);
+  if (!parsedTemplate.isRequired && locale === routing.defaultLocale) {
+    return deLocalizedPathname;
+  }
+  const pathnameSegments = splitPathname(deLocalizedPathname);
+  const localizedSegments = [...pathnameSegments];
+  localizedSegments.splice(parsedTemplate.localeSegmentIndex, 0, locale);
+  return joinPathname(localizedSegments);
+}
+function splitHrefString(href) {
+  const hashIndex = href.indexOf("#");
+  const searchIndex = href.indexOf("?");
+  const pathnameEnd = hashIndex === -1 ? searchIndex === -1 ? href.length : searchIndex : searchIndex === -1 ? hashIndex : Math.min(searchIndex, hashIndex);
+  const pathname = href.slice(0, pathnameEnd) || "/";
+  const search = searchIndex === -1 ? "" : href.slice(searchIndex, hashIndex === -1 ? href.length : hashIndex);
+  const hash = hashIndex === -1 ? "" : href.slice(hashIndex);
+  return {
+    hash,
+    pathname: normalizePathname(pathname),
+    search
+  };
+}
+function isAbsoluteHref(href) {
+  return /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(href) || href.startsWith("//");
+}
+function parseRouteTemplate(routeTemplate) {
+  const normalizedRouteTemplate = normalizePathname(
+    routeTemplate ?? DEFAULT_ROUTE_TEMPLATE
+  );
+  const localizedSegments = splitPathname(normalizedRouteTemplate);
+  let localeSegmentIndex = -1;
+  let localeParamName = "";
+  let isRequired = false;
+  for (let index = 0; index < localizedSegments.length; index += 1) {
+    const segment = localizedSegments[index];
+    const localeMatch = /^\{(-?)\$([a-zA-Z_$][a-zA-Z0-9_$]*)\}$/.exec(segment);
+    if (localeMatch) {
+      if (localeSegmentIndex !== -1) {
+        throw new Error(
+          `Route template "${normalizedRouteTemplate}" must contain exactly one locale segment.`
+        );
+      }
+      localeSegmentIndex = index;
+      localeParamName = localeMatch[2];
+      isRequired = localeMatch[1] !== "-";
+      continue;
+    }
+    if (looksDynamic(segment)) {
+      throw new Error(
+        `Route template "${normalizedRouteTemplate}" can only contain one locale segment like "{-$locale}" or "{$locale}" plus static path segments.`
+      );
+    }
+  }
+  if (localeSegmentIndex === -1) {
+    throw new Error(
+      `Route template "${normalizedRouteTemplate}" must contain one locale segment like "{-$locale}" or "{$locale}".`
+    );
+  }
+  const deLocalizedSegments = localizedSegments.filter(
+    (_, index) => index !== localeSegmentIndex
+  );
+  return {
+    deLocalizedSegments,
+    isRequired,
+    localeParamName,
+    localeSegment: localizedSegments[localeSegmentIndex],
+    localeSegmentIndex,
+    localizedSegments,
+    routeTemplate: normalizedRouteTemplate
+  };
+}
+function validateRouting(config) {
+  if (config.locales.length === 0) {
+    throw new Error("defineRouting(...) requires at least one locale.");
+  }
+  if (!config.locales.includes(config.defaultLocale)) {
+    throw new Error(
+      `Default locale "${config.defaultLocale}" must be included in locales.`
+    );
+  }
+  parseRouteTemplate(config.routeTemplate);
+  const localeSet = /* @__PURE__ */ new Set();
+  for (const locale of config.locales) {
+    if (localeSet.has(locale)) {
+      throw new Error(`Duplicate locale "${locale}" found in routing config.`);
+    }
+    localeSet.add(locale);
+  }
+}
+function analyzePathname(pathname, routing) {
+  const parsedTemplate = parseRouteTemplate(routing.routeTemplate);
+  const pathnameSegments = splitPathname(pathname);
+  let explicitLocale;
+  let localePathIndex = -1;
+  let pathnameIndex = 0;
+  for (let templateIndex = 0; templateIndex < parsedTemplate.localizedSegments.length; templateIndex += 1) {
+    if (templateIndex === parsedTemplate.localeSegmentIndex) {
+      const maybeLocale = pathnameSegments[pathnameIndex];
+      if (maybeLocale && hasLocale(routing.locales, maybeLocale)) {
+        explicitLocale = maybeLocale;
+        localePathIndex = pathnameIndex;
+        pathnameIndex += 1;
+      }
+      continue;
+    }
+    const templateSegment = parsedTemplate.localizedSegments[templateIndex];
+    const pathnameSegment = pathnameSegments[pathnameIndex];
+    if (pathnameSegment !== templateSegment) {
+      return {
+        deLocalizedPathname: normalizePathname(pathname),
+        explicitLocale: void 0,
+        inScope: false
+      };
+    }
+    pathnameIndex += 1;
+  }
+  if (localePathIndex === -1) {
+    return {
+      deLocalizedPathname: joinPathname(pathnameSegments),
+      explicitLocale: void 0,
+      inScope: true
+    };
+  }
+  const deLocalizedSegments = [...pathnameSegments];
+  deLocalizedSegments.splice(localePathIndex, 1);
+  return {
+    deLocalizedPathname: joinPathname(deLocalizedSegments),
+    explicitLocale,
+    inScope: true
+  };
+}
+function looksDynamic(segment) {
+  return segment.startsWith("[") || segment.startsWith("$") || segment.includes("{") || segment.includes("}");
+}
+function splitPathname(pathname) {
+  return normalizePathname(pathname).split("/").filter(Boolean);
+}
+function joinPathname(segments) {
+  return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+
+export {
+  hasLocale,
+  defineRouting,
+  getPathnameLocale,
+  isPathnameInScope,
+  stripLocaleFromPathname,
+  localizePathname,
+  splitHrefString,
+  isAbsoluteHref,
+  parseRouteTemplate
+};

package/dist/index.cjs

@@ -0,0 +1,206 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  defineRouting: () => defineRouting,
+  getPathnameLocale: () => getPathnameLocale,
+  hasLocale: () => hasLocale,
+  isPathnameInScope: () => isPathnameInScope,
+  localizePathname: () => localizePathname,
+  stripLocaleFromPathname: () => stripLocaleFromPathname
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/shared.ts
+var DEFAULT_ROUTE_TEMPLATE = "/{-$locale}";
+function hasLocale(locales, value) {
+  return locales.includes(value);
+}
+function defineRouting(config) {
+  const routeTemplate = config.routeTemplate ?? DEFAULT_ROUTE_TEMPLATE;
+  validateRouting({
+    ...config,
+    routeTemplate
+  });
+  return Object.freeze({
+    locales: [...config.locales],
+    defaultLocale: config.defaultLocale,
+    routeTemplate
+  });
+}
+function normalizePathname(pathname) {
+  if (!pathname) {
+    return "/";
+  }
+  return pathname.startsWith("/") ? pathname : `/${pathname}`;
+}
+function getPathnameLocale(pathname, routing) {
+  return analyzePathname(pathname, routing).explicitLocale;
+}
+function isPathnameInScope(pathname, routing) {
+  return analyzePathname(pathname, routing).inScope;
+}
+function stripLocaleFromPathname(pathname, routing) {
+  const analyzed = analyzePathname(pathname, routing);
+  return analyzed.inScope ? analyzed.deLocalizedPathname : normalizePathname(pathname);
+}
+function localizePathname(pathname, locale, routing) {
+  const normalizedPathname = normalizePathname(pathname);
+  const deLocalizedPathname = stripLocaleFromPathname(
+    normalizedPathname,
+    routing
+  );
+  if (!isPathnameInScope(deLocalizedPathname, routing)) {
+    return normalizedPathname;
+  }
+  const parsedTemplate = parseRouteTemplate(routing.routeTemplate);
+  if (!parsedTemplate.isRequired && locale === routing.defaultLocale) {
+    return deLocalizedPathname;
+  }
+  const pathnameSegments = splitPathname(deLocalizedPathname);
+  const localizedSegments = [...pathnameSegments];
+  localizedSegments.splice(parsedTemplate.localeSegmentIndex, 0, locale);
+  return joinPathname(localizedSegments);
+}
+function parseRouteTemplate(routeTemplate) {
+  const normalizedRouteTemplate = normalizePathname(
+    routeTemplate ?? DEFAULT_ROUTE_TEMPLATE
+  );
+  const localizedSegments = splitPathname(normalizedRouteTemplate);
+  let localeSegmentIndex = -1;
+  let localeParamName = "";
+  let isRequired = false;
+  for (let index = 0; index < localizedSegments.length; index += 1) {
+    const segment = localizedSegments[index];
+    const localeMatch = /^\{(-?)\$([a-zA-Z_$][a-zA-Z0-9_$]*)\}$/.exec(segment);
+    if (localeMatch) {
+      if (localeSegmentIndex !== -1) {
+        throw new Error(
+          `Route template "${normalizedRouteTemplate}" must contain exactly one locale segment.`
+        );
+      }
+      localeSegmentIndex = index;
+      localeParamName = localeMatch[2];
+      isRequired = localeMatch[1] !== "-";
+      continue;
+    }
+    if (looksDynamic(segment)) {
+      throw new Error(
+        `Route template "${normalizedRouteTemplate}" can only contain one locale segment like "{-$locale}" or "{$locale}" plus static path segments.`
+      );
+    }
+  }
+  if (localeSegmentIndex === -1) {
+    throw new Error(
+      `Route template "${normalizedRouteTemplate}" must contain one locale segment like "{-$locale}" or "{$locale}".`
+    );
+  }
+  const deLocalizedSegments = localizedSegments.filter(
+    (_, index) => index !== localeSegmentIndex
+  );
+  return {
+    deLocalizedSegments,
+    isRequired,
+    localeParamName,
+    localeSegment: localizedSegments[localeSegmentIndex],
+    localeSegmentIndex,
+    localizedSegments,
+    routeTemplate: normalizedRouteTemplate
+  };
+}
+function validateRouting(config) {
+  if (config.locales.length === 0) {
+    throw new Error("defineRouting(...) requires at least one locale.");
+  }
+  if (!config.locales.includes(config.defaultLocale)) {
+    throw new Error(
+      `Default locale "${config.defaultLocale}" must be included in locales.`
+    );
+  }
+  parseRouteTemplate(config.routeTemplate);
+  const localeSet = /* @__PURE__ */ new Set();
+  for (const locale of config.locales) {
+    if (localeSet.has(locale)) {
+      throw new Error(`Duplicate locale "${locale}" found in routing config.`);
+    }
+    localeSet.add(locale);
+  }
+}
+function analyzePathname(pathname, routing) {
+  const parsedTemplate = parseRouteTemplate(routing.routeTemplate);
+  const pathnameSegments = splitPathname(pathname);
+  let explicitLocale;
+  let localePathIndex = -1;
+  let pathnameIndex = 0;
+  for (let templateIndex = 0; templateIndex < parsedTemplate.localizedSegments.length; templateIndex += 1) {
+    if (templateIndex === parsedTemplate.localeSegmentIndex) {
+      const maybeLocale = pathnameSegments[pathnameIndex];
+      if (maybeLocale && hasLocale(routing.locales, maybeLocale)) {
+        explicitLocale = maybeLocale;
+        localePathIndex = pathnameIndex;
+        pathnameIndex += 1;
+      }
+      continue;
+    }
+    const templateSegment = parsedTemplate.localizedSegments[templateIndex];
+    const pathnameSegment = pathnameSegments[pathnameIndex];
+    if (pathnameSegment !== templateSegment) {
+      return {
+        deLocalizedPathname: normalizePathname(pathname),
+        explicitLocale: void 0,
+        inScope: false
+      };
+    }
+    pathnameIndex += 1;
+  }
+  if (localePathIndex === -1) {
+    return {
+      deLocalizedPathname: joinPathname(pathnameSegments),
+      explicitLocale: void 0,
+      inScope: true
+    };
+  }
+  const deLocalizedSegments = [...pathnameSegments];
+  deLocalizedSegments.splice(localePathIndex, 1);
+  return {
+    deLocalizedPathname: joinPathname(deLocalizedSegments),
+    explicitLocale,
+    inScope: true
+  };
+}
+function looksDynamic(segment) {
+  return segment.startsWith("[") || segment.startsWith("$") || segment.includes("{") || segment.includes("}");
+}
+function splitPathname(pathname) {
+  return normalizePathname(pathname).split("/").filter(Boolean);
+}
+function joinPathname(segments) {
+  return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineRouting,
+  getPathnameLocale,
+  hasLocale,
+  isPathnameInScope,
+  localizePathname,
+  stripLocaleFromPathname
+});

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+interface RoutingConfig<TLocale extends string> {
+    locales: readonly TLocale[];
+    defaultLocale: TLocale;
+    routeTemplate?: string;
+}
+type DefinedRouting<TLocale extends string, TDefaultLocale extends TLocale = TLocale> = Readonly<{
+    locales: readonly TLocale[];
+    defaultLocale: TDefaultLocale;
+    routeTemplate: string;
+}>;
+declare function hasLocale<TLocale extends string>(locales: readonly TLocale[], value: string): value is TLocale;
+declare function defineRouting<const TLocales extends readonly string[], const TDefaultLocale extends TLocales[number]>(config: {
+    locales: TLocales;
+    defaultLocale: TDefaultLocale;
+    routeTemplate?: string;
+}): DefinedRouting<TLocales[number], TDefaultLocale>;
+declare function getPathnameLocale<TLocale extends string>(pathname: string, routing: RoutingConfig<TLocale>): TLocale | undefined;
+declare function isPathnameInScope<TLocale extends string>(pathname: string, routing: RoutingConfig<TLocale>): boolean;
+declare function stripLocaleFromPathname<TLocale extends string>(pathname: string, routing: RoutingConfig<TLocale>): string;
+declare function localizePathname<TLocale extends string>(pathname: string, locale: TLocale, routing: RoutingConfig<TLocale>): string;
+
+export { type DefinedRouting, type RoutingConfig, defineRouting, getPathnameLocale, hasLocale, isPathnameInScope, localizePathname, stripLocaleFromPathname };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+interface RoutingConfig<TLocale extends string> {
+    locales: readonly TLocale[];
+    defaultLocale: TLocale;
+    routeTemplate?: string;
+}
+type DefinedRouting<TLocale extends string, TDefaultLocale extends TLocale = TLocale> = Readonly<{
+    locales: readonly TLocale[];
+    defaultLocale: TDefaultLocale;
+    routeTemplate: string;
+}>;
+declare function hasLocale<TLocale extends string>(locales: readonly TLocale[], value: string): value is TLocale;
+declare function defineRouting<const TLocales extends readonly string[], const TDefaultLocale extends TLocales[number]>(config: {
+    locales: TLocales;
+    defaultLocale: TDefaultLocale;
+    routeTemplate?: string;
+}): DefinedRouting<TLocales[number], TDefaultLocale>;
+declare function getPathnameLocale<TLocale extends string>(pathname: string, routing: RoutingConfig<TLocale>): TLocale | undefined;
+declare function isPathnameInScope<TLocale extends string>(pathname: string, routing: RoutingConfig<TLocale>): boolean;
+declare function stripLocaleFromPathname<TLocale extends string>(pathname: string, routing: RoutingConfig<TLocale>): string;
+declare function localizePathname<TLocale extends string>(pathname: string, locale: TLocale, routing: RoutingConfig<TLocale>): string;
+
+export { type DefinedRouting, type RoutingConfig, defineRouting, getPathnameLocale, hasLocale, isPathnameInScope, localizePathname, stripLocaleFromPathname };

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  defineRouting,
+  getPathnameLocale,
+  hasLocale,
+  isPathnameInScope,
+  localizePathname,
+  stripLocaleFromPathname
+} from "./chunk-LRCKROLX.js";
+export {
+  defineRouting,
+  getPathnameLocale,
+  hasLocale,
+  isPathnameInScope,
+  localizePathname,
+  stripLocaleFromPathname
+};