@tolgee/react 4.10.0-rc.f068ae1.0 → 5.0.0-alpha.2

package/README.md

@@ -1,44 +1,90 @@
+<!-- This file was generated using pnpm generate-readmes script 
+        
+        Don't edit this file. Edit the README.md.njk. Macros can be found in readmeMacros/macros.njk
+        
+        -->
+
+<h1 align="center" style="border-bottom: none">
+    <b>
+        <a href="https://tolgee.io">Tolgee for React</a><br>
+    </b>
+    The Tolgee i18n SDK for React
+    <br>
+</h1>
+
+<div align="center">
+
+[![Logo](https://user-images.githubusercontent.com/18496315/188628892-33fcc282-26f1-4035-8105-95952bd93de9.svg)](https://tolgee.io)
+
+Tolgee is an open-source alternative to Crowdin, Phrase, or Lokalise with its very own revolutionary integrations.
+
 ![test workflow](https://github.com/tolgee/tolgee-js/actions/workflows/test.yml/badge.svg)
-![@tolgee/react version](https://img.shields.io/npm/v/@tolgee/react?label=%40tolgee%2Freact)
+
+![@tolgee/react version](https://img.shields.io/npm/v/@tolgee/react?label=@tolgee/react)
+
 ![types typescript](https://img.shields.io/badge/Types-Typescript-blue)
+![typescript](https://img.shields.io/github/languages/top/tolgee/tolgee-js)
 ![licence](https://img.shields.io/github/license/tolgee/tolgee-js)
-[![twitter](https://img.shields.io/twitter/follow/Tolgee_i18n?style=social)](https://twitter.com/Tolgee_i18n)
-[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-js?style=social)](https://github.com/tolgee/tolgee-js)
+[![github stars](https://img.shields.io/github/stars/tolgee/tolgee-js?style=social&label=Tolgee%20JS)](https://github.com/tolgee/tolgee-js)
+[![github stars](https://img.shields.io/github/stars/tolgee/server?style=social&label=Tolgee%20Server)](https://github.com/tolgee/server)
+[![Github discussions](https://img.shields.io/github/discussions/tolgee/tolgee-platform)](https://github.com/tolgee/tolgee-platform/discussions)
+</div>
 
-# Tolgee for React
+<div align="center">
 
-React integration library of Tolgee. For more information about using Tolgee with React, visit our
-[documentation website 📖](https://tolgee.io/docs/web/using_with_react/installation).
+[<img src="https://img.shields.io/badge/-Facebook-424549?style=social&logo=facebook" height=25 />](https://www.facebook.com/Tolgee.i18n)
+[<img src="https://img.shields.io/badge/-Twitter-424549?style=social&logo=twitter" height=25 />](https://twitter.com/Tolgee_i18n)
+[<img src="https://img.shields.io/badge/-Linkedin-424549?style=social&logo=linkedin" height=25 />](https://www.linkedin.com/company/tolgee)
 
-[<img src="https://raw.githubusercontent.com/tolgee/documentation/main/tolgee_logo_text.svg" alt="Tolgee" width="200" />](https://tolgee.io)
+**Become part of the family. Join [slack channel <img src="https://img.shields.io/badge/-Tolgee Comunity-424549?style=social&logo=slack" height=25 />](https://join.slack.com/t/tolgeecommunity/shared_invite/zt-195isb5u8-_RcSRgVJfvgsPpOBIok~IQ)**
 
-Lokalize (translate) your CRA, Gatsby, Next.js or other React projects to multiple languages with Tolgee. Integration of
-Tolgee is extremely simple! 🇯🇵 🇰🇷 🇩🇪 🇨🇳 🇺🇸 🇫🇷 🇪🇸 🇮🇹 🇷🇺 🇬🇧
+</div>
 
-## Features
 
-- All in One localization solution for your JS application 🙌
-- Out of box in-context localization 🎉
-- Automated screenshot generation 📷
-- Translation management platform 🎈
-- Open-source 🔥
+
+# What is Tolgee for React?
+React integration library of Tolgee. This package makes it super simple to add i18n to your React app!
+For more information about using Tolgee with React, visit the [docs 📖](https://tolgee.io/integrations/react).
+
+Localize (translate) your CRA, Gatsby, Next.js, or other React projects to multiple languages with Tolgee. Integration of Tolgee is extremely simple! 🇯🇵 🇰🇷 🇩🇪 🇨🇳 🇺🇸 🇫🇷 🇪🇸 🇮🇹 🇷🇺 🇬🇧
+
+
+## Quick links
+- [Tolgee for React docs](https://tolgee.io/js-sdk/5.0.0-alpha.1/integrations/react/installation)
+- [Tolgee JS SDK docs](https://tolgee.io/js-sdk)
+- [Tolgee Website](https://tolgee.io)
+    - Product (Learn more about the great features)
+        - [Dev tools](https://tolgee.io/features/dev-tools)
+        - [Translation assistance](https://tolgee.io/features/translation-assistance)
+        - [Collaboration](https://tolgee.io/features/collaboration)
+- [Tolgee platform docs](https://tolgee.io/platform)
+  
+
 
 ## Installation
 
-First, install the package.
+```
+npm install @tolgee/react
+```
 
-    npm install @tolgee/react
 
 Then use the library in your app:
 
 ```typescript jsx
-import { TolgeeProvider } from "@tolgee/react";
+import { TolgeeProvider, ReactPlugin, FormatSimple } from "@tolgee/react";
+
+const tolgee = Tolgee()
+  .use(ReactPlugin())
+  .use(FormatSimple())
+  .init({
+    language: 'en',
+    apiUrl: process.env.REACT_APP_TOLGEE_API_URL,
+    apiKey: process.env.REACT_APP_TOLGEE_API_KEY
+  });
 
-...
 
 <TolgeeProvider
-  apiUrl={process.env.REACT_APP_TOLGEE_API_URL}
-  apiKey={process.env.REACT_APP_TOLGEE_API_KEY}
+  tolgee={tolgee}
 >
   <Your app components>
 </TolgeeProvider>
@@ -73,20 +119,85 @@ import { useTranslate } from "@tolgee/react";
 
 ...
 
-const t = useTranslate();
+const { t } = useTranslate();
 
 ...
 
 t("key_to_translate")
 ```
 
+
 ## Prerequisites
 
-1. You have some React based project
-2. You have generated API key from [Tolgee Cloud](https://app.tolgee.io) or self-hosted Tolgee instance.
+1. You have some React-based project
+2. You have generated an API key from [Tolgee Cloud](https://app.tolgee.io) or a self-hosted Tolgee instance.
+   
+
+
+## Why to use Tolgee?
+Because it saves a lot of time, you would spend on localization tasks without it. Because it enables you to provide perfectly translated software.
+
+### Features
+
+- All-in-one localization solution for your JS application 🙌
+- Out-of-box in-context localization 🎉
+- Automated screenshot generation 📷
+- Translation management platform 🎈
+- Open-source 🔥
+
+![Frame 47](https://user-images.githubusercontent.com/18496315/188637819-ac4eb02d-7859-4ca8-9807-27818a52782d.png)
+Read more on the [Tolgee website](https://tolgee.io)
+
+
+## Development
+
+We welcome your PRs.
+
+To develop the package locally:
+1. Clone [the repository](https://github.com/tolgee/tolgee-js)
+1. Install the packages in the repository root
+```
+pnpm install
+```
+
+
+1. Run the development script
+```
+pnpm develop:react
+```
+This runs the development suite of this monorepo for the `react` integration. The changes in each dependency package are
+automatically built and propagated to the test application, which you can open and play within the browser.
+
+
+
+
+### Testing
+
+To run Jest tests of this package, execute
+```
+npm run test
+```
+In the `/packages/react` directory.
+
+
+
+
+### End-to-end (e2e) testing
+To run the e2e tests, simply execute
+```
+pnpm run e2e run react
+```
+
+To open and play with e2e tests, run:
+```
+pnpm run e2e open react
+```
+
+
 
-## Quick integration guide
+## Contributors
 
-![react-integrate-infinite](https://user-images.githubusercontent.com/18496315/137310546-d4addbe2-4825-4262-bd18-b731b1941bce.gif)
+<a href="https://github.com/tolgee/tolgee-platform/graphs/contributors">
+  <img alt="contributors" src="https://contrib.rocks/image?repo=tolgee/tolgee-js"/>
+</a>
 
-Learn more at our [documentation website 📖](https://tolgee.io).

package/README.njk.md

@@ -0,0 +1,84 @@
+{% import "../../readmeMacros/macros.njk.md" as macros %}
+{{ macros.header('Tolgee for React', 'The Tolgee i18n SDK for React', packageName) }}
+
+# What is Tolgee for React?
+React integration library of Tolgee. This package makes it super simple to add i18n to your React app!
+For more information about using Tolgee with React, visit the [docs 📖](https://tolgee.io/integrations/react).
+
+Localize (translate) your CRA, Gatsby, Next.js, or other React projects to multiple languages with Tolgee. Integration of Tolgee is extremely simple! 🇯🇵 🇰🇷 🇩🇪 🇨🇳 🇺🇸 🇫🇷 🇪🇸 🇮🇹 🇷🇺 🇬🇧
+
+{{ macros.integrationLinks('Tolgee for React docs', macros.v5link('integrations/react/installation')) }}
+
+{{ macros.installation('react') }}
+
+Then use the library in your app:
+
+```typescript jsx
+import { TolgeeProvider, ReactPlugin, FormatSimple } from "@tolgee/react";
+
+const tolgee = Tolgee()
+  .use(ReactPlugin())
+  .use(FormatSimple())
+  .init({
+    language: 'en',
+    apiUrl: process.env.REACT_APP_TOLGEE_API_URL,
+    apiKey: process.env.REACT_APP_TOLGEE_API_KEY
+  });
+
+
+<TolgeeProvider
+  tolgee={tolgee}
+>
+  <Your app components>
+</TolgeeProvider>
+```
+
+## Usage
+
+![react-infinite](https://user-images.githubusercontent.com/18496315/137308502-844f5ccf-1895-414d-bf40-6707cb691853.gif)
+
+To translate texts using Tolgee React integration, you can use `T` component or `useTranslate` hook.
+
+### T component
+
+```typescript jsx
+import { T } from "@tolgee/react";
+
+...
+
+<T>translation_key</T>
+```
+
+or
+
+```typescript jsx
+<T keyName="translation_key">Default value</T>
+```
+
+### useTranslate hook
+
+```javascript
+import { useTranslate } from "@tolgee/react";
+
+...
+
+const { t } = useTranslate();
+
+...
+
+t("key_to_translate")
+```
+
+{{ macros.prereq('React') }}
+
+{{ macros.why() }}
+
+## Development
+{{ macros.developmentInstallation() }}
+{{ macros.development('react') }}
+
+{{ macros.developmentTesting('/packages/react') }}
+
+{{ macros.e2eTesting('react') }}
+
+{{ macros.contributors() }}

package/dist/T.d.ts

@@ -1,4 +1,4 @@
-import { FallbackNSTranslation, TranslateParams } from '@tolgee/web';
+import { NsType, TranslateParams } from '@tolgee/web';
 import { FunctionComponent } from 'react';
 import { ParamsTags } from './types';
 declare type TProps = {
@@ -6,7 +6,8 @@ declare type TProps = {
     children?: string;
     noWrap?: boolean;
     keyName?: string;
-    ns?: FallbackNSTranslation;
+    ns?: NsType;
+    defaultValue?: string;
 };
 export declare const T: FunctionComponent<TProps>;
 export {};

package/dist/TolgeeProvider.d.ts

@@ -4,6 +4,7 @@ import { ReactOptions, TolgeeReactContext } from './types';
 export declare const DEFAULT_REACT_OPTIONS: ReactOptions;
 export declare const TolgeeProviderContext: React.Context<TolgeeReactContext | undefined>;
 declare type Props = {
+    children?: React.ReactNode;
     tolgee: TolgeeInstance;
     options?: ReactOptions;
     fallback?: React.ReactNode;

package/dist/hooks.d.ts

@@ -1 +1,4 @@
-export declare const useRerender: () => () => void;
+export declare const useRerender: () => {
+    instance: number;
+    rerender: () => void;
+};

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { useTranslate } from './useTranslate';
 export { TolgeeProvider, TolgeeProviderContext } from './TolgeeProvider';
 export { T } from './T';
 export { useTolgee } from './useTolgee';
-export { ReactPlugin } from './ReactPlugin';
+export { GlobalContextPlugin } from './GlobalContextPlugin';
 export * from './types';
 export * from '@tolgee/web';

package/dist/tagsTools.d.ts

@@ -1,4 +1,5 @@
+import { TranslateParams } from '@tolgee/web';
 import React from 'react';
 import { ParamsTags } from './types';
-export declare const wrapTagHandlers: (params: ParamsTags) => any;
+export declare const wrapTagHandlers: (params: TranslateParams<ParamsTags> | undefined) => any;
 export declare const addReactKeys: (val: React.ReactNode | React.ReactNode[] | undefined) => React.ReactNode;

package/dist/tolgee-react.cjs.js

@@ -79,10 +79,9 @@ var TolgeeProvider = function (_a) {
     }, []);
     var optionsWithDefault = __assign(__assign({}, DEFAULT_REACT_OPTIONS), options);
     if (optionsWithDefault.useSuspense) {
-        return (React__default["default"].createElement(TolgeeProviderContext.Provider, { value: { tolgee: tolgee, options: optionsWithDefault } },
-            React__default["default"].createElement(React.Suspense, { fallback: fallback || null }, children)));
+        return (React__default["default"].createElement(TolgeeProviderContext.Provider, { value: { tolgee: tolgee, options: optionsWithDefault } }, loading ? (fallback) : (React__default["default"].createElement(React.Suspense, { fallback: fallback || null }, children))));
     }
-    return (React__default["default"].createElement(TolgeeProviderContext.Provider, { value: { tolgee: tolgee, options: optionsWithDefault } }, fallback && loading ? fallback : children));
+    return (React__default["default"].createElement(TolgeeProviderContext.Provider, { value: { tolgee: tolgee, options: optionsWithDefault } }, loading ? fallback : children));
 };
 
 var globalContext;
@@ -102,60 +101,58 @@ function getGlobalContext() {
 var useTolgeeContext = function () {
     var context = React.useContext(TolgeeProviderContext) || getGlobalContext();
     if (!context) {
-        throw new Error("Couldn't find tolgee instance, did you forgot to use `ReactPlugin`?");
+        throw new Error("Couldn't find tolgee instance, did you forgot to use `TolgeeProvider`?");
     }
     return context;
 };
 
+var useRerender = function () {
+    var _a = __read(React.useState(0), 2), instance = _a[0], setCounter = _a[1];
+    var rerender = React.useCallback(function () {
+        setCounter(function (num) { return num + 1; });
+    }, [setCounter]);
+    return { instance: instance, rerender: rerender };
+};
+
 var useTranslateInternal = function (ns, options) {
     var _a = useTolgeeContext(), tolgee = _a.tolgee, defaultOptions = _a.options;
     var namespaces = web.getFallback(ns);
     var namespacesJoined = web.getFallbackArray(namespaces).join(':');
     var currentOptions = __assign(__assign({}, defaultOptions), options);
     // dummy state to enable re-rendering
-    var _b = __read(React.useState(0), 2), instance = _b[0], setInstance = _b[1];
-    var forceRerender = React.useCallback(function () {
-        setInstance(function (v) { return v + 1; });
-    }, [setInstance]);
+    var _b = useRerender(), rerender = _b.rerender, instance = _b.instance;
     var subscriptionRef = React.useRef();
     var subscriptionQueue = React.useRef([]);
-    var subscribeToKey = function (key) {
-        if (subscriptionRef.current) {
-            subscriptionRef.current.subscribeKey(key);
-        }
-        else {
-            subscriptionQueue.current.push(key);
-        }
+    subscriptionQueue.current = [];
+    var subscribeToNs = function (ns) {
+        var _a;
+        subscriptionQueue.current.push(ns);
+        (_a = subscriptionRef.current) === null || _a === void 0 ? void 0 : _a.subscribeNs(ns);
     };
-    React.useEffect(function () {
-        subscriptionRef.current = tolgee.onKeyUpdate(forceRerender);
-        subscriptionQueue.current.forEach(function (key) {
-            subscriptionRef.current.subscribeKey(key);
-        });
-        subscriptionQueue.current = [];
-        return function () {
-            subscriptionRef.current.unsubscribe();
-        };
-    }, []);
     var isLoaded = tolgee.isLoaded(namespaces);
     React.useEffect(function () {
+        var subscription = tolgee.onNsUpdate(rerender);
+        subscriptionRef.current = subscription;
         if (!isLoaded) {
-            subscriptionRef.current.subscribeNs(namespaces);
-            return function () {
-                subscriptionRef.current.unsubscribeNs(namespaces);
-            };
+            subscription.subscribeNs(namespaces);
         }
-    }, [namespacesJoined, isLoaded]);
+        subscriptionQueue.current.forEach(function (ns) {
+            subscription.subscribeNs(ns);
+        });
+        return function () {
+            subscription.unsubscribe();
+        };
+    }, [isLoaded, namespacesJoined]);
     React.useEffect(function () {
         tolgee.addActiveNs(namespaces);
         return function () { return tolgee.removeActiveNs(namespaces); };
     }, [namespacesJoined]);
     var t = React.useCallback(function (props) {
         var fallbackNs = props.ns || (namespaces === null || namespaces === void 0 ? void 0 : namespaces[0]);
-        subscribeToKey({ key: props.key, ns: fallbackNs });
+        subscribeToNs(fallbackNs);
         return tolgee.t(__assign(__assign({}, props), { ns: fallbackNs }));
     }, [tolgee, instance]);
-    if ((currentOptions === null || currentOptions === void 0 ? void 0 : currentOptions.useSuspense) && !isLoaded) {
+    if (currentOptions.useSuspense && !isLoaded) {
         throw tolgee.addActiveNs(namespaces, true);
     }
     return { t: t, isLoading: !isLoaded };
@@ -169,7 +166,7 @@ var useTranslate = function (ns, options) {
             params[_i] = arguments[_i];
         }
         // @ts-ignore
-        var props = web.getTranslateParams.apply(void 0, __spreadArray([], __read(params), false));
+        var props = web.getTranslateProps.apply(void 0, __spreadArray([], __read(params), false));
         return tInternal(props);
     }, [tInternal]);
     return { t: t, isLoading: isLoading };
@@ -190,9 +187,9 @@ var wrapTagHandlers = function (params) {
         else if (React__default["default"].isValidElement(value)) {
             var el_1 = value;
             result[key] = function (chunk) {
-                return __assign(__assign({}, el_1), { props: __assign(__assign({}, el_1.props), { children: el_1.props.children !== undefined
-                            ? el_1.props.children
-                            : addReactKeys(chunk) }) });
+                return el_1.props.children !== undefined
+                    ? React__default["default"].cloneElement(el_1)
+                    : React__default["default"].cloneElement(el_1, {}, addReactKeys(chunk));
             };
         }
         else {
@@ -216,7 +213,7 @@ var T = function (props) {
         // eslint-disable-next-line no-console
         console.error('T component: keyName not defined');
     }
-    var defaultValue = props.keyName ? props.children : undefined;
+    var defaultValue = props.defaultValue || (props.keyName ? props.children : undefined);
     var t = useTranslateInternal().t;
     var translation = addReactKeys(t({
         key: key,
@@ -228,17 +225,9 @@ var T = function (props) {
     return React__default["default"].createElement(React__default["default"].Fragment, null, translation);
 };
 
-var useRerender = function () {
-    var _a = __read(React.useState(0), 2); _a[0]; var setCounter = _a[1];
-    var rerender = React.useCallback(function () {
-        setCounter(function (num) { return num + 1; });
-    }, [setCounter]);
-    return rerender;
-};
-
 var useTolgee = function (events) {
     var tolgee = useTolgeeContext().tolgee;
-    var rerender = useRerender();
+    var rerender = useRerender().rerender;
     React.useEffect(function () {
         var listeners = events === null || events === void 0 ? void 0 : events.map(function (e) { return tolgee.on(e, rerender); });
         return function () {
@@ -248,13 +237,7 @@ var useTolgee = function (events) {
     return tolgee;
 };
 
-var ReactPlugin = function (props) {
-    return function (tolgee) {
-        return tolgee.use(web.DevTools({ observer: props })).use(GlobalContextPlugin(props));
-    };
-};
-
-exports.ReactPlugin = ReactPlugin;
+exports.GlobalContextPlugin = GlobalContextPlugin;
 exports.T = T;
 exports.TolgeeProvider = TolgeeProvider;
 exports.TolgeeProviderContext = TolgeeProviderContext;