fbt-inline-translations 0.1.6 → 0.3.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2022 Swiftyper (https://swiftyper.sk)
+
+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

@@ -6,29 +6,139 @@ If you right-click on the underlined string, the translation dialog appears and
 
 You can make translations available to your translators, users, or the entire community and make your product multilingual.
 
-**Translations can also be approved by your trusted translator(s).**
+❇️ **Translations can also be approved by your trusted translator(s).**
+
+## 👀 Preview
 
 ![Demo of FBT inline translating](https://raw.githubusercontent.com/swiftyper-sk/fbt-inline-translations/main/images/demo.gif)
 
 
-## ℹ️ Usage notes
+## ℹ️ Usage Notes
 
-- this library requires FBT for PHP:
+- This library requires one of these FBT frameworks:
   - [FBT for Laravel (v5.5+)](https://github.com/richardDobron/laravel-fbt)
   - [FBT for PHP (v7.0+)](https://github.com/richardDobron/fbt)
+  - [FBT for JavaScript](https://github.com/facebook/fbt)
+  - [FBTee for JavaScript](https://github.com/nkzw-tech/fbtee)
+
+## ✨ Key Features
+
+- 📝 **Inline**: translating for real-time context
+- 📚 **Glossary**: support for consistent terminology
+- 👍 **Voting**: on translation options
+- 🔄 **Variations**: for dynamic content
+- 🌙 **Dark mode**: to match your theme
 
 ## 📦 Installing
 
-```
+⚠️ **React 15 or higher only.**
+
+Install the plugin via npm or yarn:
+
+```shell
 npm install fbt-inline-translations
+# or
+yarn add fbt-inline-translations
+```
+
+### How to Add Polyfills in Webpack 5
+
+Errors in the terminal will give hints on how to add the required polyfill.
+
+In your Webpack config:
+
+```javascript
+module.exports = {
+  resolve: {
+    // ...
+    fallback: {
+      "buffer": require.resolve("buffer/"),
+      "url": require.resolve("url/"),
+      "path": require.resolve("path-browserify"),
+      "http": require.resolve("stream-http"),
+      "https": require.resolve("https-browserify"),
+    },
+
+    alias: {
+      process: "process/browser",
+    },
+
+    plugins: [
+      // Work around for Buffer is undefined:
+      // https://github.com/webpack/changelog-v5/issues/10
+      new webpack.ProvidePlugin({
+        Buffer: ['buffer', 'Buffer'],
+      }),
+      new webpack.ProvidePlugin({
+        process: 'process/browser',
+      }),
+    ],
+  },
+};
+```
+
+and
+
+```shell
+npm install buffer url path-browserify stream-http https-browserify --save-dev
+# you may need to clear your cache after this change
+rm -fr node_modules/.cache
+```
+
+Restart the Dev Server and the error will be gone.
+
+## Instructions for JavaScript Version of FBT Package
+
+Copy file [fbt/InlineFbtResult.js](fbt/InlineFbtResult.js) to your project.
+
+Register custom `getFbtResult` hook:
+
+```javascript
+import { init } from "fbt";
+import FbtResult from "fbt/lib/FbtResult";
+import InlineFbtResult from "./InlineFbtResult";
+
+let inlineMode = 'NO_INLINE';
+
+if (true) { // enable inline translations
+    inlineMode = 'TRANSLATION';
+}
+
+init({
+  hooks: {
+    // ...
+    getFbtResult: (input) => {
+      if (inlineMode && inlineMode !== 'NO_INLINE') {
+        return new InlineFbtResult(
+          input.contents,
+          inlineMode,
+          input.patternString,
+          input.patternHash,
+        );
+      }
+
+      return new FbtResult(input.contents, input.errorListener);
+    },
+  },
+  // ...
+});
 ```
 
 ## 🔧 Configuration
 
-Register your FBT project on [Swiftyper Translations](https://translations.swiftyper.sk)
+Register your FBT project on [Swiftyper Translations](https://translations.swiftyper.sk).
+
 
+| **Option**                | **Type** | **Description**                                                     |
+|---------------------------|----------|---------------------------------------------------------------------|
+| `apiKey`                  | string   | API key for authenticating with the help center.                    |
+| `locale`                  | string   | Locale setting for the translation widget (e.g., `en_US`, `de_DE`). |
+| `contributor`             | string   | Contributor email for authentication.                               |
+| `darkMode`                | boolean  | Dark mode theme.                                                    |
 
-### Non-React usage
+## ⚡️ Quick Start
+
+### Non-React Usage
 
 Add this code to your page:
 
@@ -44,4 +154,41 @@ Add this code to your page:
         darkMode: false, // dark mode also depends on html class 'tw-dark'
     })
 </script>
-```
+```
+
+### React Usage
+
+In your application, wrap your `App` component. We recommend adding it around your root component in the `index.js` file.
+
+```js
+// src/index.js
+
+import ReactDOM from 'react-dom';
+import { FbtInlineTranslationsWrapper } from 'fbt-inline-translations';
+
+ReactDOM.render(
+  <FbtInlineTranslationsWrapper
+    token={'YOUR_API_KEY_HERE'}
+    locale={"sk_SK"} // translation locale
+    contributor={"contributor@email.com"} // contributor must be invited
+    darkMode={false} // dark mode also depends on html class 'tw-dark'
+  >
+    <App />
+  </FbtInlineTranslationsWrapper>,
+  document.getElementById('root')
+);
+```
+
+## 🧪 Testing
+
+```sh
+npm run dev
+```
+
+## 🌟 Contributing
+
+We welcome contributions! If you'd like to help improve this project, feel free to open an issue or submit a pull request.
+
+## 📜 License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.