@better-translate/react 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/react
+
+`@better-translate/react` adds a provider and hooks on top of `@better-translate/core`. Use it in React web apps and Expo apps when components need access to translations and locale switching.
+
+Full docs: [better-translate-placeholder.com/en/docs/adapters/react](https://better-translate-placeholder.com/en/docs/adapters/react)

package/dist/context.d.ts

@@ -0,0 +1,3 @@
+import type { AnyUseTranslationsValue } from "./types.js";
+export declare const BetterTranslateContext: import("react").Context<AnyUseTranslationsValue | null>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,eAAO,MAAM,sBAAsB,yDACkB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BetterTranslateProvider } from "./provider.js";
+export { useTranslations } from "./use-translations.js";
+export type { AnyBetterTranslateTranslator, BetterTranslateProviderProps, InferLocale, InferMessages, UseTranslationsValue, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,YAAY,EACV,4BAA4B,EAC5B,4BAA4B,EAC5B,WAAW,EACX,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,130 @@
+// src/provider.tsx
+import { useEffect, useReducer, useRef, useState, useTransition } from "react";
+
+// src/context.ts
+import { createContext } from "react";
+var BetterTranslateContext = createContext(null);
+
+// src/provider.tsx
+import { jsx } from "react/jsx-runtime";
+function BetterTranslateProvider({
+  children,
+  initialLocale,
+  translator
+}) {
+  const [locale, setLocaleState] = useState(
+    initialLocale ?? translator.defaultLocale
+  );
+  const [localeError, setLocaleError] = useState(null);
+  const [loadingLocale, setLoadingLocale] = useState(null);
+  const [, refreshMessages] = useReducer((count) => count + 1, 0);
+  const [isPending, startTransition] = useTransition();
+  const requestIdRef = useRef(0);
+  useEffect(() => {
+    requestIdRef.current += 1;
+    setLocaleState(
+      initialLocale ?? translator.defaultLocale
+    );
+    setLocaleError(null);
+    setLoadingLocale(null);
+    refreshMessages();
+  }, [initialLocale, translator]);
+  async function loadLocale(nextLocale) {
+    setLocaleError(null);
+    setLoadingLocale(nextLocale);
+    try {
+      const loadedLocale = await translator.loadLocale(nextLocale);
+      startTransition(() => {
+        refreshMessages();
+      });
+      return loadedLocale;
+    } catch (error) {
+      setLocaleError(error);
+      throw error;
+    } finally {
+      setLoadingLocale(
+        (currentLocale) => currentLocale === nextLocale ? null : currentLocale
+      );
+    }
+  }
+  async function setLocale(nextLocale) {
+    if (locale === nextLocale) {
+      return;
+    }
+    const requestId = ++requestIdRef.current;
+    setLocaleError(null);
+    const hasCachedMessages = Object.prototype.hasOwnProperty.call(
+      translator.getMessages(),
+      nextLocale
+    );
+    if (!hasCachedMessages) {
+      setLoadingLocale(nextLocale);
+      try {
+        await translator.loadLocale(nextLocale);
+      } catch (error) {
+        if (requestId === requestIdRef.current) {
+          setLocaleError(error);
+          setLoadingLocale(null);
+        }
+        return;
+      }
+    }
+    if (requestId !== requestIdRef.current) {
+      return;
+    }
+    startTransition(() => {
+      setLocaleState(nextLocale);
+      setLocaleError(null);
+      setLoadingLocale(null);
+      refreshMessages();
+    });
+  }
+  const translate = ((...args) => {
+    const [key, options] = args;
+    return translator.t(
+      key,
+      {
+        ...options,
+        locale: options?.locale ?? locale
+      }
+    );
+  });
+  const value = {
+    availableLanguages: translator.getAvailableLanguages(),
+    defaultLocale: translator.defaultLocale,
+    direction: translator.getDirection({
+      locale
+    }),
+    fallbackLocale: translator.fallbackLocale,
+    isLoadingLocale: loadingLocale !== null || isPending,
+    loadLocale,
+    loadingLocale,
+    locale,
+    localeError,
+    messages: translator.getMessages(),
+    rtl: translator.isRtl({
+      locale
+    }),
+    setLocale,
+    supportedLocales: translator.getSupportedLocales(),
+    t: translate,
+    translator
+  };
+  return /* @__PURE__ */ jsx(BetterTranslateContext.Provider, { value, children });
+}
+
+// src/use-translations.ts
+import { useContext } from "react";
+function useTranslations() {
+  const context = useContext(BetterTranslateContext);
+  if (!context) {
+    throw new Error(
+      "useTranslations() must be used inside <BetterTranslateProvider />."
+    );
+  }
+  return context;
+}
+export {
+  BetterTranslateProvider,
+  useTranslations
+};

package/dist/provider.d.ts

@@ -0,0 +1,9 @@
+import type { AnyBetterTranslateTranslator, BetterTranslateProviderProps } from "./types.js";
+/**
+ * Provides a configured Better Translate translator to a React subtree.
+ *
+ * The provider owns the active locale state and exposes locale-bound helpers
+ * through `useTranslations()`.
+ */
+export declare function BetterTranslateProvider<TTranslator extends AnyBetterTranslateTranslator>({ children, initialLocale, translator, }: BetterTranslateProviderProps<TTranslator>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,4BAA4B,EAC5B,4BAA4B,EAI7B,MAAM,YAAY,CAAC;AAOpB;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,SAAS,4BAA4B,EAChD,EACA,QAAQ,EACR,aAAa,EACb,UAAU,GACX,EAAE,4BAA4B,CAAC,WAAW,CAAC,2CAsI3C"}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+import type { CachedMessages, ConfiguredTranslator, DeepPartialMessages, TranslationDirection, TranslationLanguageMetadata, TranslateFunction, TranslationMessages } from "@better-translate/core";
+import type { ReactNode } from "react";
+export type AnyBetterTranslateTranslator = ConfiguredTranslator<any, TranslationMessages>;
+export type InferLocale<TTranslator extends AnyBetterTranslateTranslator> = TTranslator extends ConfiguredTranslator<infer TLocale, TranslationMessages> ? TLocale : never;
+export type InferMessages<TTranslator extends AnyBetterTranslateTranslator> = TTranslator extends ConfiguredTranslator<any, infer TSourceMessages> ? TSourceMessages : TranslationMessages;
+export interface BetterTranslateProviderProps<TTranslator extends AnyBetterTranslateTranslator> {
+    children: ReactNode;
+    initialLocale?: InferLocale<TTranslator>;
+    translator: TTranslator;
+}
+export interface UseTranslationsValue<TTranslator extends AnyBetterTranslateTranslator> {
+    availableLanguages: readonly TranslationLanguageMetadata<InferLocale<TTranslator>>[];
+    defaultLocale: InferLocale<TTranslator>;
+    direction: TranslationDirection;
+    fallbackLocale: InferLocale<TTranslator>;
+    isLoadingLocale: boolean;
+    loadLocale(locale: InferLocale<TTranslator>): Promise<DeepPartialMessages<InferMessages<TTranslator>> | InferMessages<TTranslator> | undefined>;
+    loadingLocale: InferLocale<TTranslator> | null;
+    locale: InferLocale<TTranslator>;
+    localeError: unknown;
+    messages: CachedMessages<InferLocale<TTranslator>, InferMessages<TTranslator>>;
+    rtl: boolean;
+    setLocale(locale: InferLocale<TTranslator>): Promise<void>;
+    supportedLocales: readonly InferLocale<TTranslator>[];
+    t: TranslateFunction<InferLocale<TTranslator>, InferMessages<TTranslator>>;
+    translator: TTranslator;
+}
+export type AnyUseTranslationsValue = UseTranslationsValue<AnyBetterTranslateTranslator>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC7D,GAAG,EACH,mBAAmB,CACpB,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,WAAW,SAAS,4BAA4B,IACtE,WAAW,SAAS,oBAAoB,CAAC,MAAM,OAAO,EAAE,mBAAmB,CAAC,GACxE,OAAO,GACP,KAAK,CAAC;AAEZ,MAAM,MAAM,aAAa,CAAC,WAAW,SAAS,4BAA4B,IACxE,WAAW,SAAS,oBAAoB,CAAC,GAAG,EAAE,MAAM,eAAe,CAAC,GAChE,eAAe,GACf,mBAAmB,CAAC;AAE1B,MAAM,WAAW,4BAA4B,CAC3C,WAAW,SAAS,4BAA4B;IAEhD,QAAQ,EAAE,SAAS,CAAC;IACpB,aAAa,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACzC,UAAU,EAAE,WAAW,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB,CACnC,WAAW,SAAS,4BAA4B;IAEhD,kBAAkB,EAAE,SAAS,2BAA2B,CACtD,WAAW,CAAC,WAAW,CAAC,CACzB,EAAE,CAAC;IACJ,aAAa,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACxC,SAAS,EAAE,oBAAoB,CAAC;IAChC,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACzC,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,CACR,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,GAC/B,OAAO,CACN,mBAAmB,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,GAC/C,aAAa,CAAC,WAAW,CAAC,GAC1B,SAAS,CACZ,CAAC;IACF,aAAa,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IAC/C,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,cAAc,CACtB,WAAW,CAAC,WAAW,CAAC,EACxB,aAAa,CAAC,WAAW,CAAC,CAC3B,CAAC;IACF,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,gBAAgB,EAAE,SAAS,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;IACtD,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3E,UAAU,EAAE,WAAW,CAAC;CACzB;AAED,MAAM,MAAM,uBAAuB,GACjC,oBAAoB,CAAC,4BAA4B,CAAC,CAAC"}

package/dist/use-translations.d.ts

@@ -0,0 +1,8 @@
+import type { AnyBetterTranslateTranslator, UseTranslationsValue } from "./types.js";
+/**
+ * Returns the Better Translate React context for the current subtree.
+ *
+ * Throws when used outside `BetterTranslateProvider`.
+ */
+export declare function useTranslations<TTranslator extends AnyBetterTranslateTranslator = AnyBetterTranslateTranslator>(): UseTranslationsValue<TTranslator>;
+//# sourceMappingURL=use-translations.d.ts.map

package/dist/use-translations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-translations.d.ts","sourceRoot":"","sources":["../src/use-translations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,SACT,4BAA4B,GAAG,4BAA4B,KAC1D,oBAAoB,CAAC,WAAW,CAAC,CAUrC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@better-translate/react",
+  "version": "1.0.0",
+  "description": "React context and hooks for Better Translate in web and native React apps.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean && tsc -p tsconfig.build.json",
+    "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/react"
+  },
+  "homepage": "https://github.com/jralvarenga/better-translate/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/jralvarenga/better-translate/issues"
+  },
+  "dependencies": {
+    "@better-translate/core": "workspace:^"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@repo/typescript-config": "*",
+    "react-test-renderer": "^19.2.0"
+  },
+  "keywords": [
+    "expo",
+    "i18n",
+    "l10n",
+    "react",
+    "react-native",
+    "translations",
+    "typescript"
+  ]
+}