@better-translate/core 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/core
+
+`@better-translate/core` is the framework-agnostic translation engine for Better Translate. Use it in plain TypeScript, servers, APIs, scripts, or as the base package for every adapter.
+
+Full docs: [better-translate-placeholder.com/en/docs/adapters/core](https://better-translate-placeholder.com/en/docs/adapters/core)

package/dist/chunk-PE2HFT6R.js

@@ -0,0 +1,397 @@
+// src/validation.ts
+function isTranslationConfigOptions(value) {
+  return "availableLocales" in value && "defaultLocale" in value && "messages" in value;
+}
+function isTranslationMessages(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.values(value).every((entry) => {
+    if (entry === void 0 || typeof entry === "string") {
+      return true;
+    }
+    return isTranslationMessages(entry);
+  });
+}
+
+// src/create-translation-json-schema.ts
+function createSchemaNode(messages) {
+  const properties = {};
+  for (const [key, value] of Object.entries(messages)) {
+    properties[key] = typeof value === "string" ? { type: "string" } : createSchemaNode(value);
+  }
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: Object.keys(messages),
+    properties
+  };
+}
+function createTranslationJsonSchema(sourceMessages) {
+  if (!isTranslationMessages(sourceMessages)) {
+    throw new Error(
+      "createTranslationJsonSchema(...) requires a valid translation object."
+    );
+  }
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    ...createSchemaNode(sourceMessages)
+  };
+}
+
+// src/interpolate-message.ts
+var PLACEHOLDER_PATTERN = /\{([^{}]+)\}/g;
+function interpolateMessage(message, key, params) {
+  const missingParams = /* @__PURE__ */ new Set();
+  const interpolatedMessage = message.replace(
+    PLACEHOLDER_PATTERN,
+    (match, placeholderName) => {
+      if (params && Object.prototype.hasOwnProperty.call(params, placeholderName)) {
+        return String(params[placeholderName]);
+      }
+      missingParams.add(placeholderName);
+      return "";
+    }
+  );
+  for (const placeholderName of missingParams) {
+    console.warn(
+      `Missing translation param "{${placeholderName}}" for key "${key}".`
+    );
+  }
+  return interpolatedMessage;
+}
+
+// src/resolve-message-value.ts
+function resolveMessageValue(messages, key) {
+  if (!messages) {
+    return void 0;
+  }
+  const parts = key.split(".");
+  let current = messages;
+  for (const part of parts) {
+    if (typeof current !== "object" || current === null) {
+      return void 0;
+    }
+    current = current[part];
+  }
+  return typeof current === "string" ? current : void 0;
+}
+
+// src/snapshot-languages.ts
+function snapshotLanguages(languages) {
+  return Object.freeze(
+    languages.map(
+      (language) => Object.freeze({
+        ...language
+      })
+    )
+  );
+}
+
+// src/snapshot-messages.ts
+function cloneTranslationNode(node) {
+  if (typeof node === "string" || node === void 0) {
+    return node;
+  }
+  const clonedEntries = Object.entries(node).map(([key, value]) => [
+    key,
+    cloneTranslationNode(value)
+  ]);
+  return Object.freeze(Object.fromEntries(clonedEntries));
+}
+function snapshotMessages(messages) {
+  const snapshotEntries = Object.entries(messages).map(([locale, value]) => [
+    locale,
+    cloneTranslationNode(value)
+  ]);
+  return Object.freeze(
+    Object.fromEntries(snapshotEntries)
+  );
+}
+
+// src/create-configured-translator.ts
+function createConfiguredTranslator(config) {
+  const messageCache = {
+    ...config.messages
+  };
+  const loaders = config.loaders;
+  const availableLanguages = config.languages;
+  const loadPromises = /* @__PURE__ */ new Map();
+  function resolveLocale(options) {
+    return options?.config?.locale ?? options?.locale ?? config.defaultLocale;
+  }
+  function resolveDirection(options) {
+    if (typeof options?.config?.rtl === "boolean") {
+      return options.config.rtl ? "rtl" : "ltr";
+    }
+    return config.directions[resolveLocale(options)] ?? "ltr";
+  }
+  const loadLocale2 = async (locale) => {
+    const cachedMessages = messageCache[locale];
+    if (cachedMessages) {
+      return cachedMessages;
+    }
+    const existingPromise = loadPromises.get(locale);
+    if (existingPromise) {
+      return existingPromise;
+    }
+    const loader = loaders[locale];
+    if (!loader) {
+      return void 0;
+    }
+    const pendingLoad = Promise.resolve(loader()).then((loadedMessages) => {
+      if (!isTranslationMessages(loadedMessages)) {
+        throw new Error(
+          `Locale "${locale}" did not resolve to a valid translation object.`
+        );
+      }
+      messageCache[locale] = loadedMessages;
+      return loadedMessages;
+    });
+    loadPromises.set(locale, pendingLoad);
+    try {
+      return await pendingLoad;
+    } finally {
+      loadPromises.delete(locale);
+    }
+  };
+  const translate = ((...args) => {
+    const [key, options] = args;
+    const locale = resolveLocale(options);
+    const activeValue = resolveMessageValue(messageCache[locale], key);
+    if (typeof activeValue === "string") {
+      return interpolateMessage(activeValue, key, options?.params);
+    }
+    const fallbackValue = resolveMessageValue(
+      messageCache[config.fallbackLocale],
+      key
+    );
+    if (typeof fallbackValue === "string") {
+      return interpolateMessage(fallbackValue, key, options?.params);
+    }
+    return key;
+  });
+  return {
+    defaultLocale: config.defaultLocale,
+    fallbackLocale: config.fallbackLocale,
+    supportedLocales: [
+      ...config.supportedLocales
+    ],
+    getDirection(options) {
+      return resolveDirection(options);
+    },
+    isRtl(options) {
+      return resolveDirection(options) === "rtl";
+    },
+    t: translate,
+    loadLocale: loadLocale2,
+    getSupportedLocales() {
+      return [...config.supportedLocales];
+    },
+    getAvailableLanguages() {
+      return snapshotLanguages(availableLanguages);
+    },
+    getMessages() {
+      return snapshotMessages(messageCache);
+    }
+  };
+}
+
+// src/global-store.ts
+var GLOBAL_STORE_KEY = "__better_translate_core__";
+function getGlobalStore() {
+  const globalScope = globalThis;
+  if (!globalScope[GLOBAL_STORE_KEY]) {
+    globalScope[GLOBAL_STORE_KEY] = {};
+  }
+  return globalScope[GLOBAL_STORE_KEY];
+}
+
+// src/normalize-config.ts
+function createNormalizedDirections(locales, directions) {
+  return Object.fromEntries(
+    locales.map((locale) => [locale, directions?.[locale] ?? "ltr"])
+  );
+}
+function createDefaultLanguageMetadata(locale) {
+  return {
+    locale,
+    nativeLabel: locale,
+    shortLabel: locale.toUpperCase()
+  };
+}
+function createNormalizedLanguages(locales, languages) {
+  const supportedLocaleSet = new Set(locales);
+  const seenLocales = /* @__PURE__ */ new Set();
+  const normalizedLanguages = [];
+  for (const language of languages ?? []) {
+    if (!supportedLocaleSet.has(language.locale)) {
+      throw new Error(
+        `The locale "${language.locale}" is present in languages but not in availableLocales.`
+      );
+    }
+    if (seenLocales.has(language.locale)) {
+      throw new Error(
+        `Duplicate locale "${language.locale}" found in languages config.`
+      );
+    }
+    seenLocales.add(language.locale);
+    normalizedLanguages.push({
+      ...language
+    });
+  }
+  for (const locale of locales) {
+    if (seenLocales.has(locale)) {
+      continue;
+    }
+    normalizedLanguages.push(createDefaultLanguageMetadata(locale));
+  }
+  return normalizedLanguages;
+}
+function normalizeConfig(input) {
+  if (!isTranslationConfigOptions(input)) {
+    const locales = Object.keys(input);
+    if (locales.length === 0) {
+      throw new Error(
+        "configureTranslations(...) requires at least one locale."
+      );
+    }
+    const defaultLocale = locales[0];
+    return {
+      defaultLocale,
+      fallbackLocale: defaultLocale,
+      supportedLocales: locales,
+      directions: createNormalizedDirections(locales),
+      languages: createNormalizedLanguages(locales),
+      messages: input,
+      loaders: {}
+    };
+  }
+  const supportedLocales = [...input.availableLocales];
+  if (supportedLocales.length === 0) {
+    throw new Error("configureTranslations(...) requires at least one locale.");
+  }
+  if (!supportedLocales.includes(input.defaultLocale)) {
+    throw new Error(
+      `The default locale "${input.defaultLocale}" is not included in availableLocales.`
+    );
+  }
+  if (input.fallbackLocale && !supportedLocales.includes(input.fallbackLocale)) {
+    throw new Error(
+      `The fallback locale "${input.fallbackLocale}" is not included in availableLocales.`
+    );
+  }
+  if (!input.messages[input.defaultLocale]) {
+    throw new Error(
+      `Missing source messages for default locale "${input.defaultLocale}".`
+    );
+  }
+  for (const locale of Object.keys(input.messages)) {
+    if (!supportedLocales.includes(locale)) {
+      throw new Error(
+        `The locale "${locale}" is present in messages but not in availableLocales.`
+      );
+    }
+  }
+  for (const locale of Object.keys(input.loaders ?? {})) {
+    if (!supportedLocales.includes(locale)) {
+      throw new Error(
+        `The locale "${locale}" is present in loaders but not in availableLocales.`
+      );
+    }
+  }
+  for (const locale of Object.keys(input.directions ?? {})) {
+    if (!supportedLocales.includes(locale)) {
+      throw new Error(
+        `The locale "${locale}" is present in directions but not in availableLocales.`
+      );
+    }
+  }
+  return {
+    defaultLocale: input.defaultLocale,
+    fallbackLocale: input.fallbackLocale ?? input.defaultLocale,
+    supportedLocales,
+    directions: createNormalizedDirections(supportedLocales, input.directions),
+    languages: createNormalizedLanguages(supportedLocales, input.languages),
+    messages: input.messages,
+    loaders: input.loaders ?? {}
+  };
+}
+
+// src/core.ts
+async function configureTranslations(config) {
+  const normalizedConfig = normalizeConfig(config);
+  const translator = createConfiguredTranslator(normalizedConfig);
+  getGlobalStore().translator = translator;
+  return translator;
+}
+function createTranslationHelpers(input) {
+  if ("t" in input && "getMessages" in input && "getSupportedLocales" in input) {
+    const translator = input;
+    return {
+      translator,
+      t: translator.t,
+      loadLocale(locale) {
+        return translator.loadLocale(locale);
+      },
+      getSupportedLocales() {
+        return translator.getSupportedLocales();
+      },
+      getAvailableLanguages() {
+        return translator.getAvailableLanguages();
+      },
+      getDirection(options) {
+        return translator.getDirection(options);
+      },
+      isRtl(options) {
+        return translator.isRtl(options);
+      },
+      getMessages() {
+        return translator.getMessages();
+      }
+    };
+  }
+  return configureTranslations(input).then(
+    (translator) => createTranslationHelpers(translator)
+  );
+}
+function getTranslator() {
+  const translator = getGlobalStore().translator;
+  if (!translator) {
+    throw new Error(
+      'Translations have not been configured. Call configureTranslations(...) before using "t(...)".'
+    );
+  }
+  return translator;
+}
+function t(key, options) {
+  return getTranslator().t(key, options);
+}
+async function loadLocale(locale) {
+  return getTranslator().loadLocale(locale);
+}
+function getSupportedLocales() {
+  return getTranslator().getSupportedLocales();
+}
+function getAvailableLanguages() {
+  return getTranslator().getAvailableLanguages();
+}
+function getMessages() {
+  return getTranslator().getMessages();
+}
+function resetTranslationsForTests() {
+  getGlobalStore().translator = void 0;
+}
+
+export {
+  createTranslationJsonSchema,
+  configureTranslations,
+  createTranslationHelpers,
+  getTranslator,
+  t,
+  loadLocale,
+  getSupportedLocales,
+  getAvailableLanguages,
+  getMessages,
+  resetTranslationsForTests
+};

package/dist/core.d.ts

@@ -0,0 +1,161 @@
+import type {
+  AnyConfiguredTranslator,
+  AnyTranslationHelpers,
+  CachedMessages,
+  ConfiguredTranslator,
+  DeepPartialMessages,
+  OptionsFormTranslator,
+  ShortFormTranslator,
+  StrictTranslationLocaleMap,
+  TranslateOptions,
+  TranslationConfigOptions,
+  TranslationHelpers,
+  TranslationLanguageMetadata,
+  TranslationJsonSchema,
+  TranslationLoader,
+  TranslationMessages,
+} from "./types.js";
+
+export type {
+  AnyTranslationHelpers,
+  CachedMessages,
+  ConfiguredTranslator,
+  DeepPartialMessages,
+  DeepStringify,
+  DotKeys,
+  TranslateCall,
+  TranslateFunction,
+  TranslationHelpers,
+  TranslationKey,
+  TranslationConfig,
+  TranslationParamValue,
+  TranslationParams,
+  TranslationParamsForKey,
+  TranslationPlaceholderNames,
+  TranslationDirection,
+  TranslationDirectionOptions,
+  TranslationLanguageMetadata,
+  TranslationValueAtKey,
+  TranslateOptions,
+  StrictTranslationLocaleMap,
+  TranslationJsonSchema,
+  TranslationJsonSchemaNode,
+  TranslationJsonObjectSchema,
+  TranslationJsonStringSchema,
+  TranslationKeysWithOptionalParams,
+  TranslationKeysWithRequiredParams,
+  TranslationLocaleMap,
+  TranslationConfigOptions,
+  TranslationLeaf,
+  TranslationLoader,
+  TranslationMessages,
+} from "./types.js";
+
+export declare function configureTranslations<
+  const TMessages extends Record<string, TranslationMessages>,
+>(
+  messages: StrictTranslationLocaleMap<TMessages>,
+): Promise<ShortFormTranslator<TMessages>>;
+
+export declare function configureTranslations<
+  const TLocales extends readonly string[],
+  const TMessages extends Partial<
+    Record<TLocales[number], TranslationMessages>
+  >,
+  const TLoaders extends
+    | Partial<Record<TLocales[number], TranslationLoader<unknown>>>
+    | undefined = undefined,
+  const TDefaultLocale extends TLocales[number] = TLocales[number],
+>(
+  config: TranslationConfigOptions<
+    TLocales,
+    TMessages,
+    TLoaders,
+    TDefaultLocale
+  >,
+): Promise<OptionsFormTranslator<TLocales, TMessages, TDefaultLocale>>;
+
+export declare function configureTranslations(
+  config:
+    | Record<string, TranslationMessages>
+    | TranslationConfigOptions<
+        readonly string[],
+        Partial<Record<string, TranslationMessages>>,
+        Partial<Record<string, TranslationLoader<unknown>>> | undefined,
+        string
+      >,
+): Promise<AnyConfiguredTranslator>;
+
+export declare function createTranslationHelpers<
+  TLocale extends string,
+  TSourceMessages extends TranslationMessages,
+>(
+  translator: ConfiguredTranslator<TLocale, TSourceMessages>,
+): TranslationHelpers<TLocale, TSourceMessages>;
+
+export declare function createTranslationHelpers<
+  const TMessages extends Record<string, TranslationMessages>,
+>(
+  messages: StrictTranslationLocaleMap<TMessages>,
+): Promise<
+  TranslationHelpers<
+    Extract<keyof TMessages, string>,
+    ShortFormTranslator<TMessages> extends ConfiguredTranslator<
+      any,
+      infer TSourceMessages
+    >
+      ? TSourceMessages
+      : TranslationMessages
+  >
+>;
+
+export declare function createTranslationHelpers<
+  const TLocales extends readonly string[],
+  const TMessages extends Partial<
+    Record<TLocales[number], TranslationMessages>
+  >,
+  const TLoaders extends
+    | Partial<Record<TLocales[number], TranslationLoader<unknown>>>
+    | undefined = undefined,
+  const TDefaultLocale extends TLocales[number] = TLocales[number],
+>(
+  config: TranslationConfigOptions<
+    TLocales,
+    TMessages,
+    TLoaders,
+    TDefaultLocale
+  >,
+): Promise<
+  TranslationHelpers<
+    TLocales[number],
+    Extract<TMessages[TDefaultLocale], TranslationMessages>
+  >
+>;
+
+export declare function createTranslationJsonSchema(
+  messages: TranslationMessages,
+): TranslationJsonSchema;
+
+export declare function getTranslator(): AnyConfiguredTranslator;
+
+export declare function t(
+  key: string,
+  options?: TranslateOptions<string>,
+): string;
+
+export declare function loadLocale(
+  locale: string,
+): Promise<
+  DeepPartialMessages<TranslationMessages> | TranslationMessages | undefined
+>;
+
+export declare function getSupportedLocales(): readonly string[];
+
+export declare function getAvailableLanguages(): readonly TranslationLanguageMetadata<string>[];
+
+export declare function getMessages(): CachedMessages<
+  string,
+  TranslationMessages
+>;
+
+export declare function resetTranslationsForTests(): void;

package/dist/core.js

@@ -0,0 +1,24 @@
+import {
+  configureTranslations,
+  createTranslationHelpers,
+  createTranslationJsonSchema,
+  getAvailableLanguages,
+  getMessages,
+  getSupportedLocales,
+  getTranslator,
+  loadLocale,
+  resetTranslationsForTests,
+  t
+} from "./chunk-PE2HFT6R.js";
+export {
+  configureTranslations,
+  createTranslationHelpers,
+  createTranslationJsonSchema,
+  getAvailableLanguages,
+  getMessages,
+  getSupportedLocales,
+  getTranslator,
+  loadLocale,
+  resetTranslationsForTests,
+  t
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./core.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+import {
+  configureTranslations,
+  createTranslationHelpers,
+  createTranslationJsonSchema,
+  getAvailableLanguages,
+  getMessages,
+  getSupportedLocales,
+  getTranslator,
+  loadLocale,
+  resetTranslationsForTests,
+  t
+} from "./chunk-PE2HFT6R.js";
+export {
+  configureTranslations,
+  createTranslationHelpers,
+  createTranslationJsonSchema,
+  getAvailableLanguages,
+  getMessages,
+  getSupportedLocales,
+  getTranslator,
+  loadLocale,
+  resetTranslationsForTests,
+  t
+};

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+import type { ConfiguredTranslator, TranslationMessages } from "./types.js";
+
+export declare function setRequestLocale(locale: string | undefined): void;
+
+export declare function getRequestLocale(): string | undefined;
+
+export declare function resolveRequestLocale<
+  TLocale extends string,
+  TMessages extends TranslationMessages,
+>(
+  translator: ConfiguredTranslator<TLocale, TMessages>,
+  options?: {
+    locale?: TLocale;
+    requestLocale?: string;
+    configLocale?: TLocale;
+  },
+): TLocale;

package/dist/server.js

@@ -0,0 +1,53 @@
+// src/server.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { createRequire } from "module";
+var requestLocaleStorage = new AsyncLocalStorage();
+var require2 = createRequire(import.meta.url);
+function createRequestLocaleStore() {
+  return {
+    locale: void 0
+  };
+}
+function createAsyncLocalRequestLocaleStore() {
+  return () => {
+    const existingStore = requestLocaleStorage.getStore();
+    if (existingStore) {
+      return existingStore;
+    }
+    const nextStore = createRequestLocaleStore();
+    requestLocaleStorage.enterWith(nextStore);
+    return nextStore;
+  };
+}
+var getOrCreateAsyncLocalRequestLocaleStore = createAsyncLocalRequestLocaleStore();
+function createReactRequestLocaleStore() {
+  try {
+    const react = require2("react");
+    if (typeof react.cache === "function") {
+      return react.cache(() => getOrCreateAsyncLocalRequestLocaleStore());
+    }
+  } catch {
+  }
+  return null;
+}
+var getOrCreateRequestLocaleStore = createReactRequestLocaleStore() ?? getOrCreateAsyncLocalRequestLocaleStore;
+function setRequestLocale(locale) {
+  getOrCreateRequestLocaleStore().locale = locale;
+}
+function getRequestLocale() {
+  return getOrCreateRequestLocaleStore().locale;
+}
+function resolveRequestLocale(translator, options) {
+  const locale = options?.locale ?? options?.requestLocale ?? options?.configLocale ?? translator.defaultLocale;
+  if (!translator.getSupportedLocales().includes(locale)) {
+    throw new Error(
+      `The locale "${locale}" is not included in the translator's supported locales.`
+    );
+  }
+  return locale;
+}
+export {
+  getRequestLocale,
+  resolveRequestLocale,
+  setRequestLocale
+};

package/dist/types.d.ts

@@ -0,0 +1,232 @@
+export type TranslationLeaf = string;
+export type TranslationMessages = {
+    readonly [key: string]: TranslationLeaf | TranslationMessages;
+};
+export type TranslationLoader<TMessages = TranslationMessages> = () => TMessages | Promise<TMessages>;
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer I) => void ? I : never;
+type AllTrue<T> = false extends T ? false : true;
+type MergeUnion<T> = T extends Primitive ? T : T extends ReadonlyArray<unknown> ? never : T extends Record<string, unknown> ? Simplify<{
+    [K in keyof UnionToIntersection<T>]: MergeUnion<T extends unknown ? (K extends keyof T ? T[K] : never) : never>;
+}> : never;
+type AsTranslationMessages<TMessages> = TMessages extends TranslationMessages ? TMessages : never;
+export type DeepPartialMessages<TMessages> = {
+    [K in keyof TMessages]?: TMessages[K] extends string ? string : TMessages[K] extends TranslationMessages ? DeepPartialMessages<TMessages[K]> : never;
+};
+export type DeepStringify<TMessages> = {
+    [K in keyof TMessages]: TMessages[K] extends string ? string : TMessages[K] extends TranslationMessages ? DeepStringify<TMessages[K]> : never;
+};
+export type DotKeys<TMessages, TPrefix extends string = ""> = {
+    [K in keyof TMessages & string]: TMessages[K] extends string ? `${TPrefix}${K}` : TMessages[K] extends TranslationMessages ? DotKeys<TMessages[K], `${TPrefix}${K}.`> : never;
+}[keyof TMessages & string];
+type IsExactMessageShape<TReference, TCandidate> = [TReference] extends [string] ? [TCandidate] extends [string] ? true : false : [TReference] extends [TranslationMessages] ? [TCandidate] extends [TranslationMessages] ? Exclude<keyof TReference, keyof TCandidate> extends never ? Exclude<keyof TCandidate, keyof TReference> extends never ? AllTrue<{
+    [K in keyof TReference]: IsExactMessageShape<TReference[K], K extends keyof TCandidate ? TCandidate[K] : never>;
+}[keyof TReference]> : false : false : false : false;
+type ExactMessageShape<TReference, TCandidate extends TranslationMessages> = IsExactMessageShape<TReference, TCandidate> extends true ? TCandidate : never;
+type EnforceLocaleMapShapeParity<TMessages extends Record<string, TranslationMessages>> = {
+    [TLocale in keyof TMessages]: AllTrue<{
+        [TOtherLocale in keyof TMessages]: IsExactMessageShape<TMessages[TOtherLocale], TMessages[TLocale]>;
+    }[keyof TMessages]> extends true ? TMessages[TLocale] : never;
+};
+type EnforceReferenceMessageShape<TMessages extends Partial<Record<string, TranslationMessages>>, TReference extends TranslationMessages> = {
+    [TLocale in keyof TMessages]: TMessages[TLocale] extends TranslationMessages ? ExactMessageShape<DeepStringify<TReference>, TMessages[TLocale]> : never;
+};
+type StrictOptionsMessages<TMessages extends Partial<Record<string, TranslationMessages>>, TDefaultLocale extends string> = TMessages[TDefaultLocale] extends TranslationMessages ? Simplify<TMessages & EnforceReferenceMessageShape<TMessages, Extract<TMessages[TDefaultLocale], TranslationMessages>>> : never;
+export type TranslationKey<TMessages extends TranslationMessages> = string extends keyof TMessages ? string : DotKeys<TMessages>;
+export type TranslationLocaleMap<TLocale extends string, TSourceMessages extends TranslationMessages> = Record<TLocale, DeepStringify<TSourceMessages>>;
+export type TranslationParamValue = string | number | boolean;
+export type TranslationParams = Record<string, TranslationParamValue>;
+export type TranslationDirection = "ltr" | "rtl";
+export interface TranslationLanguageMetadata<TLocale extends string> {
+    icon?: string;
+    locale: TLocale;
+    nativeLabel: string;
+    shortLabel: string;
+}
+export type TranslationValueAtKey<TMessages extends TranslationMessages, TKey extends string> = TKey extends `${infer THead}.${infer TRest}` ? THead extends keyof TMessages ? TMessages[THead] extends TranslationMessages ? TranslationValueAtKey<TMessages[THead], TRest> : never : never : TKey extends keyof TMessages ? TMessages[TKey] : never;
+type ExtractPlaceholderNames<TMessage extends string> = string extends TMessage ? string : TMessage extends `${string}{${infer TParam}}${infer TRest}` ? TParam | ExtractPlaceholderNames<TRest> : never;
+type TranslationParamsObject<TParamNames extends string> = Simplify<{
+    [TName in TParamNames]: TranslationParamValue;
+}>;
+export type TranslationPlaceholderNames<TMessages extends TranslationMessages, TKey extends string> = ExtractPlaceholderNames<Extract<TranslationValueAtKey<TMessages, TKey>, string>>;
+export type TranslationParamsForKey<TMessages extends TranslationMessages, TKey extends string> = string extends TranslationPlaceholderNames<TMessages, TKey> ? TranslationParams : TranslationParamsObject<TranslationPlaceholderNames<TMessages, TKey>>;
+export type TranslationKeysWithRequiredParams<TMessages extends TranslationMessages> = TranslationKey<TMessages> extends infer TKey ? TKey extends string ? [TranslationPlaceholderNames<TMessages, TKey>] extends [never] ? never : string extends TranslationPlaceholderNames<TMessages, TKey> ? never : TKey : never : never;
+export type TranslationKeysWithOptionalParams<TMessages extends TranslationMessages> = Exclude<TranslationKey<TMessages>, TranslationKeysWithRequiredParams<TMessages>>;
+export type TranslateOptionsForKey<TLocale extends string, TMessages extends TranslationMessages, TKey extends string> = [TranslationPlaceholderNames<TMessages, TKey>] extends [never] ? Simplify<TranslateOptions<TLocale> & {
+    params?: never;
+}> : string extends TranslationPlaceholderNames<TMessages, TKey> ? Simplify<TranslateOptions<TLocale> & {
+    params?: TranslationParams;
+}> : Simplify<Omit<TranslateOptions<TLocale>, "params"> & {
+    params: TranslationParamsForKey<TMessages, TKey>;
+}>;
+export type TranslateArgs<TLocale extends string, TMessages extends TranslationMessages, TKey extends string> = [TranslationPlaceholderNames<TMessages, TKey>] extends [never] ? [options?: TranslateOptionsForKey<TLocale, TMessages, TKey>] : string extends TranslationPlaceholderNames<TMessages, TKey> ? [options?: TranslateOptionsForKey<TLocale, TMessages, TKey>] : [options: TranslateOptionsForKey<TLocale, TMessages, TKey>];
+export type TranslateCall<TLocale extends string, TMessages extends TranslationMessages, TKey extends TranslationKey<TMessages> = TranslationKey<TMessages>> = [key: TKey, ...args: TranslateArgs<TLocale, TMessages, TKey>];
+export type TranslateFunction<TLocale extends string, TMessages extends TranslationMessages> = <TKey extends TranslationKey<TMessages>>(...args: TranslateCall<TLocale, TMessages, TKey>) => string;
+export interface TranslationJsonStringSchema {
+    type: "string";
+}
+export interface TranslationJsonObjectSchema {
+    type: "object";
+    additionalProperties: false;
+    required: string[];
+    properties: Record<string, TranslationJsonSchemaNode>;
+}
+export interface TranslationJsonSchema extends TranslationJsonObjectSchema {
+    $schema: "https://json-schema.org/draft/2020-12/schema";
+}
+export type TranslationJsonSchemaNode = TranslationJsonObjectSchema | TranslationJsonStringSchema;
+export interface TranslationConfig<TLocale extends string> {
+    /**
+     * Uses a specific locale for this call instead of the configured default locale.
+     */
+    locale?: TLocale;
+    /**
+     * Overrides the resolved text direction for this call.
+     */
+    rtl?: boolean;
+}
+/**
+ * Optional overrides for a single translation lookup.
+ */
+export interface TranslateOptions<TLocale extends string> {
+    /**
+     * Uses a specific locale for this call instead of the configured default locale.
+     */
+    locale?: TLocale;
+    /**
+     * Replaces `{token}` placeholders found in the translation string.
+     */
+    params?: TranslationParams;
+    /**
+     * Per-call configuration options for the translation method.
+     */
+    config?: TranslationConfig<TLocale>;
+}
+export interface TranslationDirectionOptions<TLocale extends string> {
+    /**
+     * Uses a specific locale for this call instead of the configured default locale.
+     */
+    locale?: TLocale;
+    /**
+     * Per-call configuration options used to resolve direction metadata.
+     */
+    config?: TranslationConfig<TLocale>;
+}
+/**
+ * Translator returned by `configureTranslations(...)`.
+ *
+ * It keeps the configured locale metadata, resolves keys with fallback behavior,
+ * and can lazily load locales registered through async loaders.
+ */
+export interface ConfiguredTranslator<TLocale extends string, TSourceMessages extends TranslationMessages> {
+    /**
+     * Source locale used for key inference and default translation lookups.
+     */
+    readonly defaultLocale: TLocale;
+    /**
+     * Locale used when a key is missing in the requested locale.
+     */
+    readonly fallbackLocale: TLocale;
+    /**
+     * All locales declared for this translator.
+     */
+    readonly supportedLocales: readonly TLocale[];
+    /**
+     * Resolves a translation key using the provided locale override or the default locale.
+     *
+     * If a key is missing in the active locale, it falls back to the configured
+     * fallback locale. If the key is still missing, the key itself is returned.
+     */
+    t: TranslateFunction<TLocale, TSourceMessages>;
+    /**
+     * Loads a locale through its registered async loader and caches the result.
+     *
+     * Returns the cached or loaded locale messages, or `undefined` when the locale
+     * does not have a loader or preloaded messages.
+     */
+    loadLocale(locale: TLocale): Promise<DeepPartialMessages<TSourceMessages> | TSourceMessages | undefined>;
+    /**
+     * Returns the list of configured locales for this translator.
+     */
+    getSupportedLocales(): readonly TLocale[];
+    /**
+     * Returns the configured or synthesized language metadata for each locale.
+     */
+    getAvailableLanguages(): readonly TranslationLanguageMetadata<TLocale>[];
+    /**
+     * Returns the resolved direction metadata for the requested locale or override.
+     */
+    getDirection(options?: TranslationDirectionOptions<TLocale>): TranslationDirection;
+    /**
+     * Returns whether the resolved direction metadata is right-to-left.
+     */
+    isRtl(options?: TranslationDirectionOptions<TLocale>): boolean;
+    /**
+     * Returns the cached messages currently known by this translator.
+     *
+     * This includes messages passed during configuration and any locales loaded
+     * later through async loaders.
+     */
+    getMessages(): CachedMessages<TLocale, TSourceMessages>;
+}
+/**
+ * Typed helper surface bound to one configured translator.
+ *
+ * This is useful for app-level setup modules that want to export typed
+ * `t(...)`, `getMessages()`, and related helpers without relying on ambient
+ * module augmentation.
+ */
+export interface TranslationHelpers<TLocale extends string, TSourceMessages extends TranslationMessages> {
+    readonly translator: ConfiguredTranslator<TLocale, TSourceMessages>;
+    readonly t: TranslateFunction<TLocale, TSourceMessages>;
+    loadLocale(locale: TLocale): Promise<DeepPartialMessages<TSourceMessages> | TSourceMessages | undefined>;
+    getSupportedLocales(): readonly TLocale[];
+    getAvailableLanguages(): readonly TranslationLanguageMetadata<TLocale>[];
+    getDirection(options?: TranslationDirectionOptions<TLocale>): TranslationDirection;
+    isRtl(options?: TranslationDirectionOptions<TLocale>): boolean;
+    getMessages(): CachedMessages<TLocale, TSourceMessages>;
+}
+/**
+ * Main configuration shape for the framework-agnostic translation runtime.
+ *
+ * `availableLocales` defines the locale contract first. `defaultLocale`,
+ * `fallbackLocale`, `messages`, and `loaders` are validated against that list.
+ */
+export type TranslationConfigOptions<TLocales extends readonly string[], TMessages extends Partial<Record<TLocales[number], TranslationMessages>>, TLoaders extends Partial<Record<TLocales[number], TranslationLoader<unknown>>> | undefined = undefined, TDefaultLocale extends TLocales[number] = TLocales[number]> = {
+    availableLocales: TLocales;
+    defaultLocale: TDefaultLocale;
+    fallbackLocale?: TLocales[number];
+    directions?: Partial<Record<TLocales[number], TranslationDirection>>;
+    languages?: readonly TranslationLanguageMetadata<TLocales[number]>[];
+    messages: StrictOptionsMessages<TMessages, TDefaultLocale>;
+    loaders?: TLoaders;
+};
+export type AnyConfiguredTranslator = ConfiguredTranslator<string, TranslationMessages>;
+export type AnyTranslationHelpers = TranslationHelpers<string, TranslationMessages>;
+export type InternalTranslationNode = string | undefined | {
+    readonly [key: string]: InternalTranslationNode;
+};
+export type InternalTranslationMessages = {
+    readonly [key: string]: InternalTranslationNode;
+};
+export type RuntimeConfigInput = Record<string, TranslationMessages> | TranslationConfigOptions<readonly string[], Partial<Record<string, TranslationMessages>>, Partial<Record<string, TranslationLoader<unknown>>> | undefined, string>;
+export interface InternalNormalizedConfig {
+    defaultLocale: string;
+    fallbackLocale: string;
+    supportedLocales: readonly string[];
+    directions: Readonly<Record<string, TranslationDirection>>;
+    languages: readonly TranslationLanguageMetadata<string>[];
+    messages: Partial<Record<string, InternalTranslationMessages>>;
+    loaders: Partial<Record<string, TranslationLoader<unknown>>>;
+}
+export interface GlobalStore {
+    translator?: AnyConfiguredTranslator;
+}
+export type CachedMessages<TLocale extends string, TSourceMessages extends TranslationMessages> = Readonly<Partial<Record<TLocale, DeepPartialMessages<TSourceMessages> | TSourceMessages>>>;
+export type ShortFormTranslator<TMessages extends Record<string, TranslationMessages>> = ConfiguredTranslator<Extract<keyof TMessages, string>, AsTranslationMessages<MergeUnion<TMessages[keyof TMessages & string]>>>;
+export type StrictTranslationLocaleMap<TMessages extends Record<string, TranslationMessages>> = Simplify<TMessages & EnforceLocaleMapShapeParity<TMessages>>;
+export type OptionsFormTranslator<TLocales extends readonly string[], TMessages extends Partial<Record<TLocales[number], TranslationMessages>>, TDefaultLocale extends TLocales[number]> = ConfiguredTranslator<TLocales[number], Extract<TMessages[TDefaultLocale], TranslationMessages>>;
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@better-translate/core",
+  "version": "1.0.0",
+  "description": "Framework-agnostic translation configuration runtime for TypeScript projects.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "core": ["./dist/core.d.ts"],
+      "server": ["./dist/server.d.ts"]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts src/core.ts src/server.ts --format esm --clean && bun x tsc --declaration --emitDeclarationOnly --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist src/types.ts && cp src/core.d.ts src/index.d.ts src/server.d.ts dist/",
+    "check-types": "tsc --noEmit",
+    "test": "bun test tests/runtime",
+    "test:types": "tsc -p tests/types/tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jralvarenga/better-translate.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/jralvarenga/better-translate/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/jralvarenga/better-translate/issues"
+  },
+  "devDependencies": {
+    "@repo/typescript-config": "*"
+  },
+  "keywords": ["i18n", "l10n", "translations", "typescript"]
+}