@better-translate/react 2.0.0 → 2.1.1

package/README.md

@@ -1,5 +1,108 @@
-# @better-translate/react
+# 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.
+Use `@better-translate/react` when React components need translations and locale switching.
 
-Full docs: [better-translate-placeholder.com/en/docs/adapters/react](https://better-translate-placeholder.com/en/docs/adapters/react)
+## 1. Install the packages
+
+```sh
+npm install @better-translate/core @better-translate/react
+```
+
+## 2. Create the shared translator
+
+Create `src/i18n.ts`:
+
+```ts
+import { configureTranslations } from "@better-translate/core";
+
+const en = {
+  home: {
+    title: "Hello",
+  },
+} as const;
+
+const es = {
+  home: {
+    title: "Hola",
+  },
+} as const;
+
+export const translator = await configureTranslations({
+  availableLocales: ["en", "es"] as const,
+  defaultLocale: "en",
+  fallbackLocale: "en",
+  messages: { en, es },
+});
+```
+
+## 3. Wrap your app
+
+Create or update `src/main.tsx`:
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+
+import { BetterTranslateProvider } from "@better-translate/react";
+
+import { App } from "./app";
+import { translator } from "./i18n";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <BetterTranslateProvider translator={translator}>
+      <App />
+    </BetterTranslateProvider>
+  </React.StrictMode>,
+);
+```
+
+## 4. Read translations inside a component
+
+Create `src/header.tsx`:
+
+```tsx
+import { useTranslations } from "@better-translate/react";
+
+import { translator } from "./i18n";
+
+export function Header() {
+  const { locale, setLocale, t } = useTranslations<typeof translator>();
+
+  return (
+    <header>
+      <h1>{t("home.title")}</h1>
+      <button onClick={() => setLocale("en")} disabled={locale === "en"}>
+        English
+      </button>
+      <button onClick={() => setLocale("es")} disabled={locale === "es"}>
+        Espanol
+      </button>
+    </header>
+  );
+}
+```
+
+## When to use React only
+
+Use only `@better-translate/core` + `@better-translate/react` when:
+
+- your app is a React SPA
+- your app is an Expo app
+- locale changes happen in client components
+
+If you are in Next.js App Router, keep this package for client hooks and add the Next.js adapter for routing and server helpers.
+
+## Generate locale files automatically
+
+Instead of writing every translation by hand, use the CLI to extract strings and generate locale files: [CLI guide](https://better-translate.com/en/docs/cli)
+
+## Continue with
+
+- [Expo setup](https://better-translate.com/en/docs/adapters/expo)
+- [Next.js setup](https://better-translate.com/en/docs/adapters/nextjs)
+
+## Examples
+
+- [react-vite-example](https://github.com/jralvarenga/better-translate/tree/main/examples/react-vite-example)
+- [expo-example](https://github.com/jralvarenga/better-translate/tree/main/examples/expo-example)

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,yBAAyB,EACzB,gCAAgC,EAChC,WAAW,EACX,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -1,6 +1,17 @@
 import type { CachedMessages, ConfiguredTranslator, DeepPartialMessages, TranslationDirection, TranslationLanguageMetadata, TranslateFunction, TranslationMessages } from "@better-translate/core";
 import type { ReactNode } from "react";
 export type AnyBetterTranslateTranslator = ConfiguredTranslator<any, TranslationMessages>;
+/**
+ * App-level type registry for `@better-translate/react`.
+ *
+ * Consumers can augment this interface once to make zero-argument
+ * `useTranslations()` return their configured translator type.
+ */
+export interface BetterTranslateReactTypes {
+}
+export type DefaultBetterTranslateTranslator = BetterTranslateReactTypes extends {
+    translator: infer TTranslator;
+} ? TTranslator extends AnyBetterTranslateTranslator ? TTranslator : AnyBetterTranslateTranslator : AnyBetterTranslateTranslator;
 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> {

package/dist/types.d.ts.map

@@ -1 +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"}
+{"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;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;CAAG;AAE7C,MAAM,MAAM,gCAAgC,GAC1C,yBAAyB,SAAS;IAAE,UAAU,EAAE,MAAM,WAAW,CAAA;CAAE,GAC/D,WAAW,SAAS,4BAA4B,GAC9C,WAAW,GACX,4BAA4B,GAC9B,4BAA4B,CAAC;AAEnC,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

@@ -1,8 +1,8 @@
-import type { AnyBetterTranslateTranslator, UseTranslationsValue } from "./types.js";
+import type { AnyBetterTranslateTranslator, DefaultBetterTranslateTranslator, 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>;
+export declare function useTranslations<TTranslator extends AnyBetterTranslateTranslator = DefaultBetterTranslateTranslator>(): UseTranslationsValue<TTranslator>;
 //# sourceMappingURL=use-translations.d.ts.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-translate/react",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "React context and hooks for Better Translate in web and native React apps.",
   "license": "MIT",
   "type": "module",
@@ -34,12 +34,12 @@
     "url": "git+https://github.com/jralvarenga/better-translate.git",
     "directory": "packages/react"
   },
-  "homepage": "https://github.com/jralvarenga/better-translate/tree/main/packages/react#readme",
+  "homepage": "https://better-translate.com",
   "bugs": {
     "url": "https://github.com/jralvarenga/better-translate/issues"
   },
   "dependencies": {
-    "@better-translate/core": "^2.0.0"
+    "@better-translate/core": "^2.2.1"
   },
   "peerDependencies": {
     "react": "^19.0.0"