Skip to content

Commit c54f752

Browse files
joelshejarjoelshejar
authored
fix: update README file (#3)
2 parents cc5c38c + d766d0f commit c54f752

File tree

1 file changed

+108
-134
lines changed

1 file changed

+108
-134
lines changed

‎README.md‎

Lines changed: 108 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -1,187 +1,161 @@
1-
# 📦 Typescript • React • Package Starter
1+
# react-ai-translator
22

3-
A slightly opinionated starter kit for developing TypeScript and/or React NPM packages. It comes with a several pre-configured tools, so you could focus on coding instead of configuring a project for the nth time. From building to releasing a package, this starter kit has you covered.
3+
[![npm version](https://badge.fury.io/js/react-ai-translator.svg)](https://badge.fury.io/js/react-ai-translator)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
45

5-
> 👋 Hello there! Follow me [@linesofcode](https://twitter.com/linesofcode) or visit [linesofcode.dev](https://linesofcode.dev) for more cool projects like this one.
6+
A **React** component for **local, secure, on-demand translations** powered by the **[Xenova/nllb-200-distilled-600M](https://huggingface.co/Xenova/nllb-200-distilled-600M)** model. This package utilizes the **WebGPU** capabilities of the device on which the app runs, ensuring data privacy and enabling you to translate text without sending data to third-party APIs.
67

7-
## 🏃 Getting started
8+
> **Note**: This is especially suitable when security is a concern and parts of the data are user-provided, which might not be captured in your `i18n` translation files.
89
9-
```console
10-
npx degit TimMikeladze/typescript-react-package-starter my-package
10+
---
1111

12-
cd my-package && git init
12+
## Table of Contents
1313

14-
pnpm install && pnpm dev
15-
```
14+
- [Features](#features)
15+
- [Installation](#installation)
16+
- [Usage](#usage)
17+
- [Example](#example)
18+
- [How It Works](#how-it-works)
19+
- [Requirements](#requirements)
20+
- [Roadmap](#roadmap)
21+
- [Contributing](#contributing)
22+
- [License](#license)
1623

17-
❗Important note: This project uses [pnpm](https://pnpm.io/) for managing dependencies. If you want to use another package manager, remove the `pnpm-lock.yaml` and control-f for usages of `pnpm` in the project and replace them with your package manager of choice. If you don't have `pnpm` installed and want to use it, you can install it by running `npm install -g pnpm`.
24+
---
1825

19-
## What's included?
26+
## Features
2027

21-
- ⚡️ [tsup](https://github.com/egoist/tsup) - The simplest and fastest way to bundle your TypeScript libraries. Used to bundle package as ESM and CJS modules. Supports TypeScript, Code Splitting, PostCSS, and more out of the box.
22-
- 📖 [Storybook](https://storybook.js.org/) - Build UI components and pages in isolation. It streamlines UI development, testing, and documentation.
23-
- 🧪 [Vitest](https://vitest.dev/) - A testing framework for JavaScript. Preconfigured to work with TypeScript and JSX.
24-
- ✅ [Biome](https://biomejs.dev/) - Format, lint, and more in a fraction of a second.
25-
- 🪝 [Lefthook](https://github.com/evilmartians/lefthook) — Run pre-commit hooks, lints staged files, executes tests, and more.
26-
- 🔼 [Release-it](https://github.com/release-it/release-it/) - release-it is a command line tool to automatically generate a new GitHub Release and populates it with the changes (commits) made since the last release.
27-
- 🐙 [Test & Publish via Github Actions](https://docs.github.com/en/actions) - CI/CD workflows for your package. Run tests on every commit plus integrate with Github Releases to automate publishing package to NPM and Storybook to Github Pages.
28-
- 🤖 [Dependabot](https://docs.github.com/en/code-security/dependabot) - Github powered dependency update tool that fits into your workflows. Configured to periodically check your dependencies for updates and send automated pull requests.
29-
- 🏃‍♀️‍➡️ [TSX](https://github.com/privatenumber/tsx) - Execute TypeScript files with zero-config in a Node.js environment.
28+
- **Secure & Local**: Utilizes your device’s GPU, keeping all data local.
29+
- **No External API Calls**: Perfect for sensitive data scenarios.
30+
- **Real-Time Translations**: On-demand translations for dynamic user content.
31+
- **Easy Integration**: Simple to install and use within any React project.
32+
- **Extensible**: Future-proof design to swap in different translation models based on your needs.
3033

31-
## Usage
34+
---
3235

33-
### 💻 Developing
36+
## Installation
3437

35-
Watch and rebuild code with `tsup` and runs Storybook to preview your UI during development.
38+
Install the package via npm (or yarn):
3639

37-
```console
38-
pnpm dev
39-
```
40+
```bash
41+
npm install react-ai-translator
4042

41-
Run all tests and watch for changes
43+
# Usage
4244

43-
```console
44-
pnpm test
45-
```
45+
Wrap your application (or a section of it) in the `TranslatorProvider` to initialize the translation model.
46+
Use the `useTranslator` hook or `Translator` component to translate text wherever needed.
4647

47-
### 🏗️ Building
48+
Below is a minimal example. For more detailed usage, see the [Example](#example) section.
4849

49-
Build package with `tsup` for production.
50+
```jsx
51+
import { useEffect, useRef, useState } from 'react'
52+
import LanguageSelector from './components/LanguageSelector';
53+
import { useTranslation } from '@joelshejar/react-ai-translator';
5054
51-
```console
52-
pnpm build
53-
```
55+
import './App.css'
5456
55-
### ▶️ Running files written in TypeScript
57+
function App() {
5658
57-
To execute a file written in TypeScript inside a Node.js environment, use the `tsx` command. This will detect your `tsconfig.json` and run the file with the correct configuration. This is perfect for running custom scripts while remaining type-safe.
59+
// Inputs and outputs
60+
const [input, setInput] = useState('I love walking my dog.');
61+
const [sourceLanguage, setSourceLanguage] = useState('eng_Latn');
62+
const [targetLanguage, setTargetLanguage] = useState('fra_Latn');
63+
const [output, setOutput] = useState('');
5864
59-
```console
60-
pnpm tsx ./path/to/file.ts
61-
```
65+
const { translate, translatedText, loading, progress, modelLoading } = useTranslation();
6266
63-
This is useful for running scripts, starting a server, or any other code you want to run while remaining type-safe.
67+
useEffect(()=>{
68+
translate(input,
69+
sourceLanguage,
70+
targetLanguage)
71+
},[])
6472
65-
### 🖇️ Linking
6673
67-
Often times you want to `link` this package to another project when developing locally, circumventing the need to publish to NPM to consume it.
74+
return (
75+
<div>
76+
<h1>Transformers.js</h1>
77+
<h2>ML-powered multilingual translation in React!</h2>
6878
69-
In a project where you want to consume your package run:
79+
<div className='container'>
80+
<div className='language-container'>
81+
<LanguageSelector type={"Source"} defaultLanguage={"eng_Latn"} onChange={x => setSourceLanguage(x.target.value)} />
82+
<LanguageSelector type={"Target"} defaultLanguage={"fra_Latn"} onChange={x => setTargetLanguage(x.target.value)} />
83+
</div>
7084
71-
```console
72-
pnpm link my-package --global
73-
```
85+
<div className='textbox-container'>
86+
<textarea value={input} rows={3} onChange={e => setInput(e.target.value)}></textarea>
87+
<div style={{width:'50%'}}>{translatedText}</div>
88+
</div>
89+
</div>
7490
75-
Learn more about package linking [here](https://pnpm.io/cli/link).
76-
77-
### 📩 Committing
78-
79-
When you are ready to commit simply run the following command to get a well formatted commit message. All staged files will automatically be linted and fixed as well.
80-
81-
```console
82-
pnpm commit
83-
```
84-
85-
### ✅ Linting
86-
87-
To lint and reformat your code at any time, simply run the following command. Under the hood, this uses [Biome](https://biomejs.dev/). If you use VSCode, I suggest installing the official [biome extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome).
88-
89-
```console
90-
pnpm lint
91-
```
92-
93-
### 🔖 Releasing, tagging & publishing to NPM
94-
95-
Create a semantic version tag and publish to Github Releases. When a new release is detected a Github Action will automatically build the package and publish it to NPM. Additionally, a Storybook will be published to Github pages.
96-
97-
Learn more about how to use the `release-it` command [here](https://github.com/release-it/release-it).
98-
99-
```console
100-
pnpm release
101-
```
102-
103-
When you are ready to publish to NPM simply run the following command:
104-
105-
```console
106-
pnpm publish
107-
```
108-
109-
#### 🤖 Auto publish after Github Release (or manually by dispatching the Publish workflow)
110-
111-
❗Important note: in order to automatically publish a Storybook on Github Pages you need to open your repository settings, navigate to "Actions" and enable **"Read & write permissions"** for Workflows. Then navigate to "Pages" and choose **"GitHub Actions"** as the source for the Build and Deployment. After a successful deployment you can find your Storybook at `https://<your-github-username>.github.io/<your-repository-name>/`.
112-
113-
❗Important note: in order to publish package to NPM you must add your token as a Github Action secret. Learn more on how to configure your repository and publish packages through Github Actions [here](https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages).
114-
115-
## 🎨 CSS & PostCSS
116-
117-
To bundle CSS files with your package that you intend on users to import within their own project, a few extra steps are required.
118-
119-
1. Add your CSS files to the `src` directory. For example, `src/styles.css`.
120-
2. Modify `tsup.config.ts` file to include your CSS file as an entry point. For example:
121-
122-
```ts
123-
import { defineConfig } from "tsup";
91+
<button disabled={modelLoading||loading} onClick={()=>translate(input,
92+
sourceLanguage,
93+
targetLanguage)}>Translate</button>
94+
</div>
95+
)
96+
}
12497
125-
export default defineConfig({
126-
entry: ["src/index.ts", "src/styles.css"],
127-
// ...
128-
});
129-
```
98+
export default App
13099
131-
3. Modify `package.json` to include the CSS file as an `exports` entry. For example:
132100
133-
```json
134-
{
135-
"exports": {
136-
"./styles.css": "./dist/styles.css"
137-
}
138-
}
139-
```
101+
# How It Works
140102
141-
4. Now consumers of your package can import your CSS file anywhere in their project. For example:
103+
- **Local Model**
104+
This library makes use of [Xenova/nllb-200-distilled-600M](https://huggingface.co/Xenova/nllb-200-distilled-600M), a distilled version of Meta AI’s *No Language Left Behind* model.
142105
143-
```ts
144-
import "your-package/styles.css";
145-
```
106+
- **WebGPU Execution**
107+
By leveraging your device’s GPU, the heavy lifting of translation is done locally, avoiding external calls.
146108
147-
Alternatively, if your package has a hard dependency on a CSS file and you want it to always be loaded when your package is imported, you can import it anywhere within your package's code and it will be bundled with-in your package.
109+
- **Security**
110+
No user data leaves your environment, making it ideal for handling private or sensitive content.
148111
149-
[tsup](https://github.com/egoist/tsup) supports PostCSS out of the box. Simply run `pnpm add postcss -D` add a `postcss.config.js` file to the root of your project, then add any plugins you need. Learn more how to configure PostCSS [here](https://tsup.egoist.dev/#css-support).
112+
---
150113
151-
Additionally consider using the [tsup](https://github.com/egoist/tsup) configuration option `injectStyle` to inject the CSS directly into your Javascript bundle instead of outputting a separate CSS file.
114+
# Requirements
152115
153-
## 🚀 Built something using this starter-kit?
116+
- **React**: ^16.8.0 or newer (hooks are used).
117+
- **Node**: ^14 or newer.
118+
- **WebGPU Support**: Ensure your browser or environment supports the [WebGPU API](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API).
119+
- **Model Size**: The `nllb-200-distilled-600M` model is relatively large; ensure sufficient memory & GPU resources.
154120
155-
That's awesome! Feel free to add it to the list.
121+
---
156122
157-
🗃️ **[Next Upload](https://github.com/TimMikeladze/next-upload)** - Turn-key solution for integrating Next.js with signed & secure file-uploads to an S3 compliant storage service such as R2, AWS, or Minio.
123+
# Roadmap
158124
159-
🏁 **[Next Flag](https://github.com/TimMikeladze/next-flag)** - Feature flags powered by GitHub issues and NextJS. Toggle the features of your app by ticking a checkbox in a GitHub issue. Supports server-side rendering, multiple environments, and can be deployed as a stand-alone feature flag server.
125+
Some upcoming goals and improvements we’re exploring:
160126
161-
🔒 **[Next Protect](https://github.com/TimMikeladze/next-protect)** - Password protect a Next.js site. Supports App Router, Middleware and Edge Runtime.
127+
1. **Static Text Discovery**
128+
Automatically scan a repo to find all static texts and consolidate them for easy translation management.
162129
163-
📮 **[Next Invite](https://github.com/TimMikeladze/next-invite)** - A drop-in invite system for your Next.js app. Generate and share invite links for users to join your app.
130+
2. **Caching Mechanism**
131+
Implement efficient caching for translated texts to minimize repeated computations.
164132
165-
🔐 **[Next Auth MUI](https://github.com/TimMikeladze/next-auth-mui)** - Sign-in dialog component for NextAuth built with Material UI and React. Detects configured OAuth and Email providers and renders buttons or input fields for each respectively. Fully themeable, extensible and customizable to support custom credential flows.
133+
3. **Dynamic Model Selection**
134+
Allow usage of different translation models based on user needs (e.g., smaller vs. larger model for specific languages).
166135
167-
⌚️ **[Next Realtime](https://github.com/TimMikeladze/next-realtime)** - Experimental drop-in solution for real-time data leveraging the Next.js Data Cache.
136+
4. **Bundle Optimization**
137+
Investigate ways to reduce package size and loading times.
168138
169-
✅ **[Mui Joy Confirm](https://github.com/TimMikeladze/mui-joy-confirm)** - Confirmation dialogs built on top of [@mui/joy](https://mui.com/joy-ui/getting-started/) and react hooks.
139+
5. **Language Detection**
140+
Automatic source language detection for more streamlined usage.
170141
171-
🗂️ **[Use File System](https://github.com/TimMikeladze/use-file-system)** - A set of React hooks to interact with the File System API. Watch a directory for changes and return a map of filepaths & contents when a file is added, modified or removed.
142+
---
172143
173-
🐙 **[Use Octokit](https://github.com/TimMikeladze/use-octokit)** - A data-fetching hook built on top of the Octokit and SWR for interacting with the Github API. Use this inside a React component for a type-safe, data-fetching experience with caching, polling, and more.
144+
# Contributing
174145
175-
🐌 **[Space Slug](https://github.com/TimMikeladze/space-slug)** - Generate unique slugs, usernames, numbers, custom words, and more using an intuitive api with zero dependencies.
146+
Contributions, issues, and feature requests are welcome!
176147
177-
🌡️ **[TSC Baseline](https://github.com/TimMikeladze/tsc-baseline/)** - Save a baseline of TypeScript errors and compare new errors against it. Useful for type-safe feature development in TypeScript projects that have a lot of errors. This tool will filter out errors that are already in the baseline and only show new errors.
148+
1. Fork the repository.
149+
2. Create a new branch for your feature or fix.
150+
3. Commit and push your changes. (please use pnpm commit)
151+
4. Submit a pull request.
178152
179-
♾️ **[react-infinite-observer](https://github.com/Tasin5541/react-infinite-observer)** - A simple hook to implement infinite scroll in react component, with full control over the behavior. Implemented with IntersectionObserver.
153+
We’ll review your submission and work together to make **react-ai-translator** better.
180154
181-
</> **[react-simple-devicons](https://github.com/shawilly/react-simple-devicons)** - A straightforward React implementation that provides access to SVG dev icons from (devicon.dev)[https://devicon.dev], allowing customization of color, size, and styling.
155+
---
182156
183-
🎋 **[GitHub Issue to Branch](https://github.com/TimMikeladze/github-issue-to-branch)** - CLI tool to quickly create well-named branches from GitHub issues.
157+
# License
184158
185-
📏 **[React DevBar](https://github.com/TimMikeladze/react-devbar/)** - A customizable floating toolbar for React applications. Build and integrate your own dev tools with a draggable interface inspired by the Vercel toolbar. Perfect for adding debugging panels, theme controls, and other development utilities for your app.
159+
This project is licensed under the [MIT License](./LICENSE).
160+
Feel free to use, modify, and distribute this library in both commercial and private projects.
186161
187-
⏲️ **[Fake Time Series](https://github.com/TimMikeladze/fake-time-series/)** - A flexible CLI tool and library for generating fake time series data. Perfect for testing, development, and demonstration purposes.

0 commit comments

Comments
 (0)