diff --git a/packages/transformers/docs/source/_toctree.yml b/packages/transformers/docs/source/_toctree.yml index 76d779249..3fc96818d 100644 --- a/packages/transformers/docs/source/_toctree.yml +++ b/packages/transformers/docs/source/_toctree.yml @@ -13,6 +13,8 @@ title: Building a Vanilla JS Application - local: tutorials/react title: Building a React Application + - local: tutorials/svelte + title: Building a Svelte Application - local: tutorials/next title: Building a Next.js Application - local: tutorials/browser-extension diff --git a/packages/transformers/docs/source/tutorials/svelte.md b/packages/transformers/docs/source/tutorials/svelte.md new file mode 100644 index 000000000..c19e263f6 --- /dev/null +++ b/packages/transformers/docs/source/tutorials/svelte.md @@ -0,0 +1,459 @@ +# Building a Svelte application + +In this tutorial, we'll be building a simple [Svelte](https://svelte.dev/) application that performs multilingual translation using Transformers.js! The final product will look something like this: + +![Demo](https://huggingface.co/datasets/Xenova/transformers.js-docs/resolve/main/react-translator-demo.gif) + +Useful links: + +- [Demo on Hugging Face Spaces](https://huggingface.co/spaces/Xenova/svelte-translator) + +## Prerequisites + +- [Node.js](https://nodejs.org/en/) version 18+ +- [npm](https://www.npmjs.com/) version 9+ + +## Step 1: Initialise the project + +For this tutorial, we will use the [Svelte CLI](https://svelte.dev/docs/cli/overview) to initialise our project. The CLI creates SvelteKit projects and uses Vite under the hood, so the development server command and localhost URL shown below still apply. Run the following command in your terminal: + +```bash +npx sv create svelte-translator +``` + +If prompted to install `sv`, type y and press Enter. Then answer the prompts as follows: + +1. Template: `SvelteKit minimal` +2. Type checking: `No` (plain JavaScript) +3. Add-ons: none +4. Dependency installation: no, because we will install dependencies in the next step + +The minimal template creates a SvelteKit app with the page component in `src/routes/+page.svelte` and the HTML shell in `src/app.html`. + +Next, enter the project directory and install the necessary development dependencies: + +```bash +cd svelte-translator +npm install +``` + +To test that our application is working, we can run the following command: + +```bash +npm run dev +``` + +Visiting the URL shown in the terminal (e.g., [http://localhost:5173/](http://localhost:5173/)) should show the starter SvelteKit page. +You can stop the development server by pressing Ctrl + C in the terminal. + +## Step 2: Install and configure Transformers.js + +Now we get to the fun part: adding machine learning to our application! First, install Transformers.js from [NPM](https://www.npmjs.com/package/@huggingface/transformers) with the following command: + +```bash +npm install @huggingface/transformers +``` + +For this application, we will use the [Xenova/nllb-200-distilled-600M](https://huggingface.co/Xenova/nllb-200-distilled-600M) model, which can perform multilingual translation among 200 languages. Before we start, there are 2 things we need to take note of: + +1. ML inference can be quite computationally intensive, so it's better to load and run the models in a separate thread from the main (UI) thread. +2. Since the model is quite large (>1 GB), we don't want to download it until the user clicks the "Translate" button. + +We can achieve both of these goals by using a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers). + +Create a file called `worker.js` in the `src/routes` directory. This script will do all the heavy-lifting for us, including loading and running of the translation pipeline. To ensure the model is only loaded once, we will create the `MyTranslationPipeline` class which uses the [singleton pattern](https://en.wikipedia.org/wiki/Singleton_pattern) to lazily create a single instance of the pipeline when `getInstance` is first called, and use this pipeline for all subsequent calls: + +```javascript +import { pipeline, TextStreamer } from "@huggingface/transformers"; + +class MyTranslationPipeline { + static task = "translation"; + static model = "Xenova/nllb-200-distilled-600M"; + static instance = null; + + static async getInstance(progress_callback = null) { + this.instance ??= pipeline(this.task, this.model, { progress_callback }); + return this.instance; + } +} +``` + +## Step 3: Design the user interface + + + +We recommend starting the development server again with `npm run dev` +(if not already running) so that you can see your changes in real-time. + + + +First, let's create some child components. Create a folder called `lib` in the `src` directory, and create the following files: + +1. `LanguageSelector.svelte`: This component will allow the user to select the input and output languages. Check out the full list of languages in the [NLLB language codes](https://github.com/facebookresearch/flores/blob/main/flores200/README.md#languages-in-flores-200). + + ```svelte + + +
+ + +
+ ``` + +2. `Progress.svelte`: This component will display the overall model download progress. + + ```svelte + + +
+
+ {text} ({percentage.toFixed(2)}%) +
+
+ ``` + +Now let's update `src/routes/+page.svelte`. Replace its contents with the following, which sets up our state variables, renders the UI, and adds the page styles: + +```svelte + + +
+

Transformers.js

+

ML-powered multilingual translation in Svelte!

+ +
+
+ sourceLanguage = e.target.value} + /> + targetLanguage = e.target.value} + /> +
+ +
+ + +
+
+ + + +
+ {#if ready === false} + + + {/if} +
+
+ + +``` + +The `translate` function is just a placeholder for now. We will replace it in the next section. Some styles use `:global(...)` because styles in Svelte components are scoped, and those selectors target elements inside the child components. + +## Step 4: Connecting everything together + +Now that we have a basic user interface set up, we can finally connect everything together. + +First, let's set up the Web Worker and the `translate` function. Replace the ` +``` + +SvelteKit server-renders pages by default, so creating the worker inside `onMount` keeps it browser-only and avoids running Web Worker code during SSR. In Svelte 5, you can return a cleanup function from `onMount` instead of using `onDestroy`. + +Now, let's add an event listener in `src/routes/worker.js` to listen for messages from the main thread. We will send back messages (e.g., for model loading progress and text streaming) to the main thread with `self.postMessage`. + +```javascript +// Listen for messages from the main thread +self.addEventListener("message", async (event) => { + // Retrieve the translation pipeline. When called for the first time, + // this will load the pipeline and save it for future use. + const translator = await MyTranslationPipeline.getInstance((x) => { + // Forward only progress_total events to show overall download progress + if (x.status === "progress_total") { + self.postMessage(x); + } + }); + + // Capture partial output as it streams from the pipeline + const streamer = new TextStreamer(translator.tokenizer, { + skip_prompt: true, + skip_special_tokens: true, + callback_function: function (text) { + self.postMessage({ + status: "update", + output: text, + }); + }, + }); + + // Actually perform the translation + const output = await translator(event.data.text, { + tgt_lang: event.data.tgt_lang, + src_lang: event.data.src_lang, + + // Allows for partial output to be captured + streamer, + }); + + // Send the output back to the main thread + self.postMessage({ + status: "complete", + output, + }); +}); +``` + +You can now run the application with `npm run dev` and perform multilingual translation directly in your browser! + +## (Optional) Step 5: Build and deploy + +To build your application, run `npm run build`. You can then run `npm run preview` to preview the production build locally. + +For this demo, we will deploy our application as a static [Hugging Face Space](https://huggingface.co/docs/hub/spaces), but you can deploy it anywhere you like! If you haven't already, you can create a free Hugging Face account [here](https://huggingface.co/join). + +1. Visit [https://huggingface.co/new-space](https://huggingface.co/new-space) and fill in the form. Remember to select "Static" as the space type. +2. SvelteKit's default adapter does not create a `dist` folder for static hosting. To deploy this as a Static Space, configure [`@sveltejs/adapter-static`](https://svelte.dev/docs/kit/adapter-static), then run `npm run build`. +3. Go to "Files" → "Add file" → "Upload files". Drag the files generated by the static adapter into the upload box and click "Upload". After they have uploaded, scroll down to the button and click "Commit changes to main". + +**That's it!** Your application should now be live at `https://huggingface.co/spaces//`!