Forem: Tolgee

Go Global or Die Trying (A Guide on How Not to Actually Die Trying)

Nazarii — Thu, 08 May 2025 12:54:16 +0000

So, you're developing a product, and suddenly it turns out that most of the users are not from an English-speaking country.

Not a problem, but you've hard-coded all the text or kept it in an unorganized JSON file.

Now, instead of delegating it to some translator or using some AI to translate it fast, you are going to be implementing every single translation, and most likely, the translation will be out of context, and you will be in an infinite loop of fixing it after getting complaints from confused users.

🏃‍♂️ Don’t want to become an errand boy or girl for the customer support and localization team?

⏰ Here is how to save your future time:

Localization Nightmare

Maybe, even as a user, you have sometimes experienced parts of the UI in a foreign language and found it confusing?

I have had complaints from Chinese users that, apparently, the Chinese version we were providing was not the right Chinese language they had chosen. What was supposed to make the app accessible made it confusing and impossible to use…

The Excel/CSV workflow turns into a nightmare for version control. It may be nice when you just started development, but before you know it, you realize that you don’t know what is even going on now.

Contextless translations and the soul-crushing manual labor of copying strings between files soon will be your new best friend if you don’t optimize it :)

Translators work blindly without visual context, developers waste hours synchronizing code with translation files, and the worst part is discovering missing translations only when users report them. So, what can you do now to avoid ending up in this hell?

At What Point Should You Even Start Localizing?

The ideal time to incorporate localization is during your initial planning of the architecture. Even date formats and UI layouts that weren't designed with language expansion in mind can be a huge problem! Think of those things in advance. Localization is not just translation.

How dates and times are written, in what order the names are written, and whether the text is written left to right or right to left are some basic questions to keep in mind when building your app. Are you ever guilty of not considering any of those?

Excel at code, not at Excel

Escaping Excel might not be easy when you are so used to it. Modern localization management platforms have come to help you fight Excel madness. They centralize where developers, translators, and project managers collaborate, so that everything is up to date together with the code. Instead of thinking about translation as a static file exchange, these platforms treat localization as a process that evolves with your codebase. Examples of such platforms are: Tolgee, Crowin, or Phrase

Key Features That Will Save Your Sanity

Translation context preservation

Editing translations within your app interface is like a jump from using Notepad to VS Code. In-context translation means that translators can see exactly where and how their translations will appear. This way, words would not get lost out of context. Imagine if someone was localizing to English and suddenly your “Shopping Cart” is now called “Trash Can” because it is the same word in another language.

// en.json
{
  "welcome_message": "Welcome to our app!",
  "items_count": "{count} items found" // How is this used? No one knows!
}

When using visual editing that preserves context, translators click directly on UI elements in the actual app and translate with perfect context. No more guessing how long the text can be and what it refers to (especially relevant to languages like German).

Tolgee JS and React: https://tolg.ee/kgt1pp

Automatic Detection of Missing Translations

"We're launching in Spanish tomorrow,”

but nobody noticed that 40% of the new features that we added are actually untranslated...

When utilizing a localization platform, it tracks your translation and automatically flags missing or outdated translations before they become production emergencies. This way you prevent fires before you have to put them out.

The CLI (Command Line Interface) helps manage your project from the command line. Pushing and pulling strings is the most basic way to work with strings using the CLI. It helps to download strings to your system or to upload the strings after changes. It is almost like using Git, so it doesn’t require a lot of getting used to if you are familiar with Git.

Example from Tolgee that has an open-source CLI :

tolgee pull [options]

Example usage:
   tolgee pull --path ./i18n

tolgee push [options]

Example usage:
   tolgee push --force-mode OVERRIDE

Developer-friendly Workflows

To help you integrate everything seamlessly, these platforms are not just a visual playground for translators. They also provide:

Git-like branching for translations alongside code features
CLI tools for extraction and synchronization
Figma and Browser plugins like the ones from Tolgee
IDE plugins that highlight missing translations
Preview environments for testing translations before release

What are the options?

If you are looking for an open-source, developer-friendly option, you can try Tolgee and find it on GitHub: https://tolg.ee/0qmbt7

Popular options:

Tolgee
Crowdin
Lokalise
Phrase

Conclusion

Step one after your MVP should be thinking strategically about how you will operate at scale. Think of the localization of different features, starting with dates and time, ending with text width and size. Integrate translation keys into your code and ensure they are named properly. Try open-source alternatives and features, such as plugins for Chrome and Figma, to simplify work for everyone.

Building a Kanban Board with Next.js,Vercel AI and Tolgee

Arindam Majumder — Fri, 15 Nov 2024 14:50:57 +0000

TL;DR

In this article, we will build a real-time Kanban board in Next.js using WebSockets, with database support, AI support through the Vercel AI SDK and localization via Tolgee.

What You Will Learn: ✨

Set up a WebSocket server in Next.js without Express.
Implement credentials-based authentication in Next.js with NextAuth.
Configure a PostgreSQL database using Docker or a cloud provider.
Integrate AI support for task descriptions with the Vercel AI SDK.
Add real-time translation and localization using Tolgee.

Star the Tolgee repository ⭐

Are you ready to build a unique Kanban board with AI and localization support? 🔥

Setting up the Project 🛠️

Initializing a Next.js Application

Initialize a new Next.js application with the following command:

ℹ️ You can use any package manager of your choice. For this project, I will use npm.

npx create-next-app@latest kanban-ai-realtime-localization --typescript --tailwind --eslint --app --src-dir --use-npm

Next, navigate into the newly created Next.js project:

cd kanban-ai-realtime-localization

Installing Dependencies

We’ll need several dependencies. Run this command to install all the dependencies required for our project:

npm install @ai-sdk/openai @tolgee/react @tolgee/web @tolgee/format-icu @tanstack/react-query @prisma/client ai socket.io socket.io-client prisma next-auth date-fns nodemon ts-node zod tsconfig-paths react-beautiful-dnd

Setting Up UI Components

For UI components, we will use shadcn/ui. Initialize it with default settings with this command:

npx shadcn@latest init -d

Now, let’s add some UI components that we are going to use in our application later on. To add reusable components from shadcn/ui, run this command:

npx shadcn@latest add button card input label select textarea toast

Inside the app/components/ui directory, some additional files will be added for these components, which we will use when building the UI for our application.

Setting up the Database Model 📦

Initializing Prisma

Initialize Prisma with the following command:

npx prisma init

After you run this command, a new schema.prisma file should be created in the prisma directory at the root of your project.

Defining the Prisma Schema

Modify the newly created schema.prisma file to use PostgreSQL as the database and include the User and Task models.

// 👇 prisma/schema.prisma

// This is your Prisma schema file,
// learn more about it in the docs: <https://pris.ly/d/prisma-schema>

// Looking for ways to speed up your queries, or scale easily with your serverless or edge functions?
// Try Prisma Accelerate: <https://pris.ly/cli/accelerate-init>

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id       String @id @default(cuid())
  email    String @unique
  password String

  tasks Task[] @relation("UserTasks")

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Task {
  id          String  @id @default(cuid())
  title       String
  description String?
  userId      String

  column Int
  order  Int

  createdBy User @relation("UserTasks", fields: [userId], references: [id])

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

The model is straightforward: each user can have multiple tasks, with each task linked to a specific user. A task has an integer column value representing its status (0 for ongoing, 1 for pending, and 2 for completed). The order value determines each task's position within its assigned column.

Now that we have our model ready, we need to push it to our database. For this, we need the connection URL.

If you already have access to a database with Neon or another service, that's great. Populate the .env file with the connection URL. You don't need to set up the database locally with docker.

Setting up a Database Locally with Docker 🐳

If you're following along and just want to try the project with a local PostgreSQL database using Docker, add a new variable named DATABASE_URL with this connection string value to the .env file.

// 👇 .env

# If you are using local DB with docker
DATABASE_URL=postgresql://postgres:password@localhost:5432/kanban-board

To run a database locally, make sure you have Docker installed. Create a new directory named scripts in the root of the project and add a file called start-local-db-docker.sh with the following lines of code:

# 👇 scripts/start-local-db-docker.sh

#!/usr/bin/env bash

# place this in .env: DATABASE_URL=postgresql://postgres:password@localhost:5432/kanban-board
DB_CONTAINER_NAME="kanban-board"

if ! [ -x "$(command -v docker)" ]; then
  echo -e "Docker is not installed. Please install docker and try again."
  exit 1
fi

if [ "$(docker ps -q -f name=$DB_CONTAINER_NAME)" ]; then
  echo "Database container '$DB_CONTAINER_NAME' is already running"
  exit 0
fi

if [ "$(docker ps -q -a -f name=$DB_CONTAINER_NAME)" ]; then
  docker start "$DB_CONTAINER_NAME"
  echo "Existing database container '$DB_CONTAINER_NAME' has been started"
  exit 0
fi

# import env variables from .env
set -a
source ../.env

# Extract components from DATABASE_URL
PROTO="$(echo $DATABASE_URL | grep :// | sed -e's,^\\(.*://\\).*,\\1,g')"
URL="$(echo ${DATABASE_URL/$PROTO/})"
USERPASS="$(echo $URL | grep @ | cut -d@ -f1)"
HOSTPORT="$(echo ${URL/$USERPASS@/} | cut -d/ -f1)"
DB_HOST="$(echo $HOSTPORT | cut -d: -f1)"
DB_PORT="$(echo $HOSTPORT | cut -d: -f2)"
DB_USER="$(echo $USERPASS | cut -d: -f1)"
DB_PASSWORD="$(echo $USERPASS | cut -d: -f2)"

# Debugging information
echo "Extracted DB_HOST: $DB_HOST"
echo "Extracted DB_PORT: $DB_PORT"
echo "Extracted DB_USER: $DB_USER"
echo "Extracted DB_PASSWORD: $DB_PASSWORD"

if [ "$DB_PASSWORD" = "password" ]; then
  echo "You are using the default password"
  read -p "Should we generate a random password for you? [y/N]: " -r REPLY
  if [[ $REPLY =~ ^[Yy]$ ]]; then
    # Generate a random URL-safe password
    DB_PASSWORD=$(openssl rand -base64 12 | tr '+/' '-_')
    sed -i -e "s#:password@#:$DB_PASSWORD@#" ../.env
  else
    echo "Please set a password in the `.env` file and try again"
    exit 1
  fi
fi

echo "Starting the container on port $DB_PORT"

docker run -d \\
  --name $DB_CONTAINER_NAME \\
  -e POSTGRES_USER="$DB_USER" \\
  -e POSTGRES_PASSWORD="$DB_PASSWORD" \\
  -e POSTGRES_DB="$DB_CONTAINER_NAME" \\
  -p "$DB_PORT:5432" \\
  docker.io/postgres && echo "Database container '$DB_CONTAINER_NAME' was successfully created"

This script basically reads the .env file for the DATABASE_URL variable and extracts all the relevant data like the username, password, the database name and creates a container if it does not exist. If it already does, it simply spins up the existing container.

Run this script to create and run a PostgreSQL container which will host all the user data for our application.

bash scripts/start-local-db-docker.sh

Now, we should have a running container with PostgreSQL. You can check if that is the case by running this command:

docker ps | grep "kanban-board"

Now, we will need a way to instantiate a Prisma client to interact with the database.

Create a new file index.ts inside the src/db directory and add the following lines of code:

// 👇 src/db/index.ts

import { PrismaClient } from "@prisma/client";

const prismaClientSingleton = () => {
  return new PrismaClient();
};

declare const globalThis: {
  prismaGlobal: ReturnType<typeof prismaClientSingleton>;
} & typeof global;

export const db = globalThis.prismaGlobal ?? prismaClientSingleton();

if (process.env.NODE_ENV !== "production") globalThis.prismaGlobal = db;

We set up a singleton instance of the PrismaClient to ensure only one instance is created and reused across your application, especially helpful in development mode.

We can now use our exported constant db to interact with our database in our application.

Run the following command to push your changes in your schema to the database.

npx prisma db push

Now, to have the updated types work in the IDE, run the following command to generate new types based on our updated schema.

npx prisma generate

This is all that we need to set up our application database. 🥳

Setting up Tolgee for Localization 🗣️

To enable localization in your Next.js application with Tolgee, follow these steps:

Create language.ts

This file handles language detection and cookie management.

// 👇 src/tolgee/language.ts

"use server";

import { detectLanguageFromHeaders } from "@tolgee/react/server";
import { cookies, headers } from "next/headers";
import { ALL_LANGUAGES, DEFAULT_LANGUAGE } from "@/tolgee/shared";

const LANGUAGE_COOKIE = "NEXT_LOCALE";

export async function setLanguage(locale: string) {
  const cookieStore = cookies();
  cookieStore.set(LANGUAGE_COOKIE, locale, {
    // One year
    maxAge: 1000 * 60 * 60 * 24 * 365,
  });
}

export async function getLanguage() {
  const cookieStore = cookies();
  const locale = cookieStore.get(LANGUAGE_COOKIE)?.value;
  if (locale && ALL_LANGUAGES.includes(locale)) {
    return locale;
  }

  // Try to detect language only if in a browser environment
  if (typeof window !== "undefined") {
    const detected = detectLanguageFromHeaders(headers(), ALL_LANGUAGES);
    return detected || DEFAULT_LANGUAGE;
  }

  return DEFAULT_LANGUAGE;
}

The setLanguage function saves the selected language (locale) as a cookie with a one-year expiry, allowing the app to remember the user's language preference across sessions.

The getLanguage function checks for the saved language in cookies. If a valid language is found, it returns that; otherwise, it attempts to detect the language from the browser's headers if running in a browser. If detection fails or the environment isn't a browser, it defaults to DEFAULT_LANGUAGE.

Create shared.ts

This file contains shared constants and functions for handling localization, including fetching static data for translations

// 👇 src/tolgee/shared.ts

import { FormatIcu } from "@tolgee/format-icu";
import { DevTools, Tolgee } from "@tolgee/web";

const apiKey = process.env.TOLGEE_API_KEY;
const apiUrl = process.env.TOLGEE_API_URL;

export const ALL_LANGUAGES = ["en", "cs", "de", "fr"];

export const DEFAULT_LANGUAGE = "en";

export async function getStaticData(
  languages: string[],
  namespaces: string[] = [""],
) {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const result: Record<string, any> = {};
  for (const lang of languages) {
    for (const namespace of namespaces) {
      if (namespace) {
        result[`${lang}:${namespace}`] = (
          await import(`../../messages/${namespace}/${lang}.json`)
        ).default;
      } else {
        result[lang] = (await import(`../../messages/${lang}.json`)).default;
      }
    }
  }
  return result;
}

export function TolgeeBase() {
  return Tolgee().use(FormatIcu()).use(DevTools()).updateDefaults({
    apiKey,
    apiUrl,
    fallbackLanguage: "en",
  });
}

The getStaticData function is responsible for loading translations for specific languages and namespaces to prefetch localized content. It fetches JSON files from messages directory, by language and namespace, and then bundles everything into a single object and returns it.

For language selection in our application, we will provide the user with four different language choices (English, Czech, French and German). You can add support to other languages if you like.

Inside the messages directory at the root of the project, we will store different static data for different words and sentences.

ℹ️ You can find link to these static translation file in my repository. There is nothing to explain in that file as they are bunch of translation sentences in different other languages.

The TolgeeBase function sets up Tolgee with tools for handling translations. It adds support for ICU message formatting (FormatIcu) and includes DevTools for debugging. The function uses the API key and URL from environment variables and sets English (en) as the fallback language.

Update Environment Variables

We are using two different env variables, populate the .env file with these API keys. Sign up for an account in Tolgee and get access to the TOLGEE_API_KEYS, but for this application, it is not required to have that API key.

// 👇 .env

TOLGEE_API_URL=https://app.tolgee.io

# Optional
TOLGEE_API_KEY=

Create server.ts

This file configures the Tolgee instance for server-side rendering, setting up translation handling.

// 👇 src/tolgee/server.ts

import { TolgeeBase, ALL_LANGUAGES, getStaticData } from "@/tolgee/shared";
import { createServerInstance } from "@tolgee/react/server";
import { getLanguage } from "@/tolgee/language";

export const { getTolgee, getTranslate, T } = createServerInstance({
  getLocale: getLanguage,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  createTolgee: async (locale: any) =>
    TolgeeBase().init({
      // including all locales
      // on server we are not concerned about bundle size
      staticData: await getStaticData(ALL_LANGUAGES),
      observerOptions: {
        fullKeyEncode: true,
      },
      language: locale,
      fetch: async (input, init) =>
        fetch(input, { ...init, next: { revalidate: 0 } }),
    }),
});

This code creates a Tolgee instance for server-side translation handling. It starts by setting getLocale to use the getLanguage function, which retrieves the user’s preferred language. Then, in createTolgee, it initializes Tolgee with translation data for all supported languages through getStaticData.

It also sets Tolgee to use the provided language (from getLanguage) and configures a custom fetch function to always load fresh data by setting revalidate: 0, preventing caching of translation requests.

Create client.ts

This sets up the Tolgee provider for client-side rendering.

// 👇 src/tolgee/client.ts

"use client";

import { TolgeeBase } from "@/tolgee/shared";
import { TolgeeProvider, TolgeeStaticData } from "@tolgee/react";
import { useRouter } from "next/navigation";
import { useEffect } from "react";

type Props = {
  language: string;
  staticData: TolgeeStaticData;
  children: React.ReactNode;
};

const tolgee = TolgeeBase().init();

export const TolgeeProviderClient = ({
  language,
  staticData,
  children,
}: Props) => {
  const router = useRouter();

  useEffect(() => {
    const { unsubscribe } = tolgee.on("permanentChange", () => {
      router.refresh();
    });
    return () => unsubscribe();
  }, [router]);

  return (
    <TolgeeProvider
      tolgee={tolgee}
      options={{ useSuspense: false }}
      fallback="Loading..."
      ssr={{
        language,
        staticData,
      }}
    >
      {children}
    </TolgeeProvider>
  );
};

This code sets up a client-side Tolgee provider for translations. TolgeeProviderClient takes language, staticData, and children as props, and it initializes Tolgee with the specified language and data. Inside useEffect, it listens for language changes with permanentChange, refreshing the page through router.refresh() whenever the language updates.

Finally, TolgeeProvider renders the children, using ssr options to preload translations and displaying "Loading..." if translations aren’t ready instantly.

Wrap the Application with TolgeeProviderClient in layout.tsx

Finally, wrap your application with the <TolgeeProviderClient /> component to ensure all translations are accessible.

// 👇 src/app/layout.tsx

import type { Metadata } from "next";
import localFont from "next/font/local";
import { Toaster } from "@/components/ui/toaster";
import "./globals.css";
import { Navbar } from "@/components/navbar";
import { getLanguage } from "@/tolgee/language";
import { getStaticData } from "@/tolgee/shared";
import { TolgeeProviderClient } from "@/tolgee/client";

// Rest of the code...

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const locale = await getLanguage();

  const staticData = await getStaticData([locale, "en"]);
  return (
    <html lang={locale}>
        <body
          className={`${geistSans.variable} ${geistMono.variable} antialiased`}
        >
          <TolgeeProviderClient language={locale} staticData={staticData}>
            <Navbar />
            {children}
            <Toaster />
          </TolgeeProviderClient>
        </body>
    </html>
  );
}

Here first we are getting access to the locale of the user based on the header or from the cookie which we set from the function. Then we provide that locale to the <html /> tag.

That is all we need to set up Tolgee in our Next.js application. ✨This is going to be a standard process that you need to do to implement location with Tolgee in any Next.js applications.

Setting up Authentication 🛡️

We will be using NextAuth for authentication in our application. First, let’s start by defining a new Zod schema which we will use to validate the user-passed data.

Zod Schema for Validation

Define a Zod schema (AuthSchema) to validate user input for email and password during login and registration. This ensures the email format is correct and the password meets specified length requirements.

// 👇 src/lib/validators/auth.ts

import { z } from "zod";

export const AuthSchema = z.object({
  email: z.string().email(),
  password: z.string().trim().min(8).max(20),
});

export type TAuthSchema = z.infer<typeof AuthSchema>;

We require the email field to be the exact email and not any other string and we want the password field to be a minimum length of 8 characters and a max length of 20 characters. We will use this validation schema in multiple places to validate the user-passed data in our login/register form to check if it meets the criteria.

NextAuth Configuration

You set up NextAuth in route.ts under src/app/api/auth/[...nextauth], using CredentialsProvider for authentication. The authorize function validates the credentials, checks the user's existence, and verifies the password.

// 👇 src/app/api/auth/[...nextauth]/route.ts

import NextAuth from "next-auth";
import CredentialsProvider from "next-auth/providers/credentials";
import { compare } from "bcrypt";
import { AuthSchema, TAuthSchema } from "@/lib/validators/auth";
import { db } from "@/db";

const handler = NextAuth({
  session: {
    strategy: "jwt",
  },
  pages: {
    signIn: "/login",
  },
  secret: process.env.NEXTAUTH_SECRET,
  providers: [
    CredentialsProvider({
      name: "Credentials",
      // These are used in the default sign-in page from next-auth.
      credentials: {
        email: {
          label: "Email",
          type: "text",
          placeholder: "example@gmail.com",
        },
        password: { label: "Password", type: "password" },
      },
      async authorize(credentials) {
        const payload: TAuthSchema | null =
          credentials?.email && credentials?.password
            ? {
                email: credentials.email,
                password: credentials.password,
              }
            : null;

        if (!payload) return null;

        const validatedFields = AuthSchema.safeParse(payload);

        if (!validatedFields.success) return null;

        const { email: userInputEmail, password: userInputPassword } =
          validatedFields.data;

        const potentialUser = await db.user.findUnique({
          where: {
            email: userInputEmail,
          },
        });

        if (!potentialUser) return null;

        const isCorrectPassword = await compare(
          userInputPassword,
          potentialUser.password,
        );

        if (!isCorrectPassword) return null;

        //Because getting the error in the IDE: _ is assigned a value but never used.
        // eslint-disable-next-line @typescript-eslint/no-unused-vars
        const { password: _, ...userWithoutPassword } = potentialUser;

        return userWithoutPassword;
      },
    }),
  ],
});

export { handler as GET, handler as POST };

The authorize function logic is responsible for logging in the user or not. The function in this setup checks if the provided email and password match an existing user in the database.

We are using only the Credential based authentication. First, it validates the credentials using the AuthSchema for field validation. If validation succeeds, it looks up the user by email in the database. If the user is found, it then compares the hashed password in the database with the password input. If both checks pass, it returns the user's data (excluding the password).

As you might have guessed, here we require NEXTAUTH_SECRET variable to be defined inside the .env file. Populate the .env file with these two variables:

// 👇 .env

# Rest of the environment variables...

# For running the application locally, set NEXTAUTH_URL to: <http://localhost:3000>
NEXTAUTH_URL=

# Set NEXTAUTH_SECRET to a random cryptographic string.
# For generating a new secret, run: `openssl rand -base64 32`
NEXTAUTH_SECRET=

User Registration API

In the src/app/api/auth/register/route.ts, we create an endpoint for user registration that hashes the password and stores user data in the database. We then return appropriate responses based on validation success.

// 👇 src/app/api/auth/register/route.ts

import { AuthSchema } from "@/lib/validators/auth";
import { NextRequest, NextResponse } from "next/server";
import { hash } from "bcrypt";
import { db } from "@/db";

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    const validatedFields = AuthSchema.safeParse(body);

    if (!validatedFields.success) {
      return NextResponse.json(
        {
          errors: validatedFields.error.flatten().fieldErrors,
        },
        { status: 422 },
      );
    }

    const { email, password } = validatedFields.data;

    const hashedPassword = await hash(password, 12);
    const user = await db.user.create({
      data: {
        email,
        password: hashedPassword,
      },
    });

    return NextResponse.json(user);
  } catch (error) {
    console.error("ERROR:", error);
    return NextResponse.json(
      { error: "Something went wrong" },
      { status: 500 },
    );
  }
}

Here, we parse the data received from the client and validate it with the AuthSchema we wrote earlier. Then, we create a hash with a rotation value of 12. This generates an encrypted text that we will store in our database, and finally, we return the user.

Now to make our application a lot solid, let’s add a middleware that checks for the userSession anytime a user visits a certain route, and if they are not authenticated they are not allowed to visit that route.

Middleware for Route Protection

We add a middleware to restrict access to the /kanban route for unauthenticated users.

// 👇 src/middleware.ts

export { default } from "next-auth/middleware";

export const config = { matcher: ["/kanban/:path*"] };

Here, we are saying that a user should not be able to visit the “/kanban” route if they are not authenticated.

We are done with the backend logic for handling authentication. Let’s work on some client-side logic.

Build Navbar Component

Our Navbar component is going to be comprised of some smaller components as well. We will have a button to login, register, logout and a select tag to allow the user to switch languages.

Let’s begin working on these components!

LangSelector Component

Inside the src/app/components directory create a new file lang-selector.tsx with the following lines of code:

// 👇 src/app/components/lang-selector.tsx

"use client";

import { useTolgee, useTranslate, T } from "@tolgee/react";
import { setLanguage } from "@/tolgee/language";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
} from "@/components/ui/select";
import {
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "@radix-ui/react-select";
import { ChevronDown } from "lucide-react";

export const LangSelector = () => {
  const tolgee = useTolgee(["language"]);
  const locale = tolgee.getLanguage();

  const { t } = useTranslate();

  function onSelectChange(value: string) {
    setLanguage(value);
  }

  const languageOptions = [
    { code: "en", label: "English" },
    { code: "cs", label: "Česky" },
    { code: "fr", label: "Français" },
    { code: "de", label: "Deutsch" },
  ];

  return (
    <Select value={locale} onValueChange={onSelectChange}>
      <SelectTrigger className="w-[200px] border rounded-md">
        <SelectValue placeholder={t("select-a-language")} />
        <ChevronDown className="ml-2 w-4 h-4 inline" />
      </SelectTrigger>

      <SelectContent>
        <SelectGroup>
          <SelectLabel className="mb-1">
            <T keyName="language" />
          </SelectLabel>
          {languageOptions.map(({ code, label }) => (
            <SelectItem key={code} value={code}>
              {label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  );
};

The component should be pretty self-explanatory. We are using the <Select /> component provided by shadcn/ui to map on all the available language choices we have. Based on the user selection, we set the language to that with the setLanguage function we worked on in language.ts file earlier.

💡 NOTE: Notice how we are not hardcoding any text in the code; instead, we are using components from Tolgee to render the text. This way, when the user switches the language, the text changes accordingly. If we hardcoded the text, implementing translations would be ineffective. We will continue using this approach moving forward.

We are using the <T /> component and the t function we get from useTranslate hook from Tolgee to apply translations. To learn about their differences, visit here.

LogoutBtn Component

Similarly, Inside this components directory create a new file called logout-btn.tsx with the following lines of code:

// 👇 src/components/logout-btn.tsx

"use client";

import { signOut } from "next-auth/react";
import { Button, buttonVariants } from "@/components/ui/button";
import { useRouter } from "next/navigation";
import { T, useTranslate } from "@tolgee/react";
import { useState } from "react";
import { toast } from "@/hooks/use-toast";
import { LoaderCircle } from "lucide-react";

export const LogoutBtn = () => {
  const router = useRouter();
  const { t } = useTranslate();

  const [isLoading, setIsLoading] = useState<boolean>(false);

  const handleLogout = async () => {
    setIsLoading(true);

    try {
      await signOut();
      router.push("/login");
      router.refresh();
    } catch (error) {
      console.error("ERROR:", error);
      toast({
        title: t("something-went-wrong"),
        variant: "destructive",
      });
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <Button
      onClick={handleLogout}
      className={buttonVariants({
        className:
          "text-gray-800 text-md px-3 py-2 rounded hover:bg-blue-50 hover:text-blue-700 transition",
        variant: "secondary",
      })}
      disabled={isLoading}
    >
      {isLoading && (
        <LoaderCircle className="w-5 h-5 text-gray-300 animate-spin mr-2" />
      )}
      <T keyName="logout" />
    </Button>
  );
};

Similar to earlier, when the user clicks on the Button, we trigger the handleLogout function which then tries to log out the user and if any error is occured, it then shows a toast notification with the translated error message.

We use our loading state to display a loader icon when logging out the user.

Navbar Component

Finally, now that both of the smaller components that we required are available, let’s work on the <Navbar /> component.

// 👇 src/components/navbar.tsx

import { ListTodo } from "lucide-react";
import { getServerSession } from "next-auth";
import Link from "next/link";
import { LogoutBtn } from "@/components/logout-btn";
import { buttonVariants } from "@/components/ui/button";
import { LangSelector } from "@/components/lang-selector";
import { T } from "@/tolgee/server";

export const Navbar = async () => {
  const session = await getServerSession();

  return (
    <nav className="flex items-center justify-between p-4 bg-white border-b border-gray-200 sticky top-0 z-50">
      <Link
        href={"/"}
        className="text-xl font-semibold hidden text-gray-800 sm:flex items-center select-none"
      >
        <ListTodo size={30} className="mr-2 inline" />
        <T keyName="kanban" />
      </Link>
      <div className="flex gap-4 ml-auto">
        <LangSelector />
        {session ? (
          <LogoutBtn />
        ) : (
          <>
            <Link
              href="/login"
              className={buttonVariants({
                className:
                  "text-gray-600 text-lg px-3 py-2 rounded hover:bg-blue-50 hover:text-blue-700 transition",
                variant: "outline",
              })}
            >
              <T keyName="login" />
            </Link>
            <Link
              href="/register"
              className={buttonVariants({
                className:
                  "text-gray-600 text-lg px-3 py-2 rounded hover:bg-blue-50 hover:text-blue-700 transition",
                variant: "outline",
              })}
            >
              <T keyName="register" />
            </Link>
          </>
        )}
      </div>
    </nav>
  );
};

This Navbar component creates a navigation bar for our application. It checks if a user is logged in using getServerSession. If the user is authenticated, a logout button is shown. If not, it shows the link to the user to login and register.

Build Authentication Pages

Now, that we are done with handling the backend logic for authentication and also done implementing Tolgee to our application. Let’s work on some client-side logic and build some UI.

Login Component

Inside the app/components directory, create a new file login.tsx with the following lines of code:

// 👇 src/app/components/login.tsx

"use client";

import { FormEvent, useState } from "react";
import { useRouter } from "next/navigation";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { useToast } from "@/hooks/use-toast";
import Link from "next/link";
import { signIn } from "next-auth/react";
import { T, useTranslate } from "@tolgee/react";
import { LoaderCircle } from "lucide-react";
import { Label } from "@/components/ui/label";

export const Login = () => {
  const router = useRouter();
  const { toast } = useToast();

  const { t } = useTranslate();

  const [email, setEmail] = useState<string>("");
  const [password, setPassword] = useState<string>("");
  const [isLoading, setIsLoading] = useState<boolean>(false);

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setIsLoading(true);

    try {
      const response = await signIn("credentials", {
        email,
        password,
        redirect: false,
      });

      if (response?.error) {
        toast({
          title: t("something-went-wrong"),
          variant: "destructive",
        });
      } else {
        router.push("/");
        router.refresh();
      }
    } catch (error) {
      console.error("ERROR:", error);
      toast({
        title: t("something-went-wrong"),
        variant: "destructive",
      });
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <div className="flex items-center justify-center min-h-screen bg-gray-100">
      <div className="bg-white p-8 rounded-lg shadow-lg max-w-sm w-full">
        <h2 className="text-2xl font-bold mb-6 text-center text-gray-900">
          <T keyName="login" />
        </h2>

        <form onSubmit={handleSubmit}>
          <div className="mb-4">
            <Label
              htmlFor="email"
              className="text-xs font-bold uppercase text-gray-500"
            >
              <T keyName="email" />
            </Label>
            <Input
              type="email"
              name="email"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              placeholder={t("email")}
              required
              className="w-full p-3 border border-gray-300 rounded"
            />
          </div>

          <div className="mb-6">
            <Label
              htmlFor="password"
              className="text-xs font-bold uppercase text-gray-500"
            >
              <T keyName="password" />
            </Label>
            <Input
              type="password"
              name="password"
              value={password}
              onChange={(e) => setPassword(e.target.value)}
              placeholder={t("password")}
              required
              className="w-full p-3 border border-gray-300 rounded"
            />
          </div>

          <Button
            type="submit"
            className="w-full bg-gray-600 text-white p-3 rounded hover:bg-gray-700 transition duration-200"
            disabled={isLoading}
          >
            {isLoading && (
              <LoaderCircle className="w-5 h-5 text-gray-300 mr-2 animate-spin" />
            )}
            <T keyName="login" />
          </Button>

          <p className="text-center mt-4">
            <T keyName="dont-have-an-account" />{" "}
            <Link
              href="/register"
              className="text-blue-500 hover:text-blue-600 transition duration-200"
            >
              <T keyName="register" />
            </Link>
          </p>
        </form>
      </div>
    </div>
  );
};

This Login component displays a login form for email and password, with both input fields functioning as controlled components. Upon form submission, it calls signIn from next-auth to handle authentication. If the login fails, a translated error message is displayed via a toast notification. Successful logins redirect the user to the homepage.

We also have a separate loading state variable, which we use to show a loading animation icon while logging the user into our application.

Currently, this is just a component we have created; it is not yet displayed in our application. To do that, we need to render this component in the app directory of our application.

Login Page Route

Inside the src/app/login directory, create a new file called page.tsx with the following lines of code:

// 👇 src/app/login/page.tsx

import { Login } from "@/components/login";
import { getServerSession } from "next-auth";
import { redirect } from "next/navigation";

export default async function Page() {
  const session = await getServerSession();
  if (session) redirect("/kanban");

  return <Login />;
}

In the login page, we first check if the user has an active session. If the user has an active session, we simply redirect them to the “/kanban” route (which we will implement shortly). If the user does not have an active session, we display the earlier <Login /> component we built.

We have now completed the implementation of the Login page; similarly, let’s build the Register page.

Register Component

Inside the app/components directory, create a new file register.tsx with the following lines of code:

// 👇 src/app/components/register.tsx

"use client";

import { FormEvent, useState } from "react";
import { useRouter } from "next/navigation";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { useToast } from "@/hooks/use-toast";
import Link from "next/link";
import { T, useTranslate } from "@tolgee/react";
import { LoaderCircle } from "lucide-react";
import { Label } from "@/components/ui/label";
import axios from "axios";
import { useMutation } from "@tanstack/react-query";

export const Register = () => {
  const router = useRouter();
  const { toast } = useToast();

  const { t } = useTranslate();

  const [email, setEmail] = useState<string>("");
  const [password, setPassword] = useState<string>("");

  const { mutate: register, isPending } = useMutation({
    mutationFn: async () => {
      const payload = {
        email,
        password,
      };
      await axios.post("/api/auth/register", payload);
    },
    onSuccess: () => {
      router.push("/login");
      router.refresh();
    },
    onError: (error) => {
      console.error("ERROR:", error);
      toast({
        title: t("something-went-wrong"),
        description: t("there-was-a-problem-registering-your-account"),
        variant: "destructive",
      });
    },
  });

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    register();
  }

  return (
    <div className="flex items-center justify-center min-h-screen bg-gray-100">
      <div className="bg-white p-8 rounded-lg shadow-lg max-w-sm w-full">
        <h2 className="text-2xl font-bold mb-6 text-center text-gray-900">
          <T keyName="register" />
        </h2>

        <form onSubmit={handleSubmit}>
          <div className="mb-4">
            <Label
              htmlFor="email"
              className="text-xs font-bold uppercase text-gray-500"
            >
              <T keyName="email" />
            </Label>
            <Input
              type="email"
              name="email"
              placeholder={t("email")}
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              required
              className="w-full p-3 border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-blue-500"
            />
          </div>

          <div className="mb-6">
            <Label
              htmlFor="password"
              className="text-xs font-bold uppercase text-gray-500"
            >
              <T keyName="password" />
            </Label>
            <Input
              type="password"
              name="password"
              value={password}
              onChange={(e) => setPassword(e.target.value)}
              placeholder={`${t("password")} (${t("min-length-8")})`}
              required
              className="w-full p-3 border border-gray-300 rounded"
            />
          </div>

          <Button
            type="submit"
            className="w-full bg-gray-600 text-white p-3 rounded hover:bg-gray-600 transition duration-200"
            disabled={isPending}
          >
            {isPending && (
              <LoaderCircle className="w-5 h-5 text-gray-300 animate-spin mr-2" />
            )}
            <T keyName="register" />
          </Button>

          <p className="text-center mt-4">
            <T keyName="already-have-an-account" />{" "}
            <Link
              href="/login"
              className="text-blue-500 hover:text-blue-600 transition duration-200"
            >
              <T keyName="login" />
            </Link>
          </p>
        </form>
      </div>
    </div>
  );
};

The email and password inputs in this component function as controlled components, similar to those on the login page. Here, we use React Query to simplify the process of making the POST request. This approach eliminates the need to manage separate states for loading or error handling.

When the user clicks the submit button in the form, a POST request is made to our API route for registering a user in the database we worked on earlier. If the registration succeeds, the user is redirected to the login page. If not, a toast message is displayed with the translated error message.

When the user clicks the submit button, a POST request is sent to our API route to register the user in the database we previously set up. Upon successful registration, the user is redirected to the login page. If the registration fails, we display a toast message with the translated error message using the relevant keys.

Register Page Route

Inside the src/app/register directory, create a new file called page.tsx with the following lines of code:

// 👇 src/app/register/page.tsx

import { Register } from "@/components/register";
import { getServerSession } from "next-auth";
import { redirect } from "next/navigation";

export default async function Page() {
  const session = await getServerSession();
  if (session) redirect("/kanban");

  return <Register />;
}

With this page set up, we have completed the authentication flow of our application. You should now have a working authentication-enabled application with localization support.

Setup WebSocket and QueryClient Provider

In this section, we will set up a WebSocket server for our application. Let’s first create a function that helps us get access to the socket.

getSocket Function

Inside the src/config directory, create a new file socket.ts with the following lines of code:

// 👇 src/config/socket.ts

import { io, Socket } from "socket.io-client";

let socket: Socket;

export const getSocket = (): Socket => {
  if (socket) return socket;

  socket = io(process.env.NEXT_PUBLIC_APP_URL as string, {
    autoConnect: false,
  });

  return socket;
};

This code defines a function getSocket that initializes a Socket.IO client connection to the URL specified in the environment variable NEXT_PUBLIC_APP_URL, ensuring that the socket is created only once. If the socket is already initialized, it simply returns the existing socket instance.

Socket Provider

Now, we need to manage our socket.io connection and provide a way for our components to access the socket instance. Inside the src/providers directory, create a new file socket-provider.tsx with the following lines of code:

// 👇 src/providers/socket-provider.tsx

"use client";

import { createContext, ReactNode, useContext, useMemo } from "react";
import { getSocket } from "@/config/socket";
import type { Socket } from "socket.io-client";

interface SocketContextType {
  socket: Socket | null;
}

const SocketContext = createContext<SocketContextType | undefined>(undefined);

export const useSocket = () => {
  const context = useContext(SocketContext);
  if (!context) {
    throw new Error("'useSocket' must be used within a 'SocketProviderClient'");
  }
  return context.socket;
};

export default function SocketProviderClient({
  children,
}: {
  children: ReactNode;
}) {
  const socket = useMemo(() => {
    const socketInstance = getSocket();
    return socketInstance.connect();
  }, []);

  return (
    <SocketContext.Provider value={{ socket }}>
      {children}
    </SocketContext.Provider>
  );
}

This code creates a React context for managing a Socket.IO connection, providing a useSocket hook to access the socket instance. The SocketProviderClient initializes the socket using the getSocket function and connects it, then wraps its children in a context provider to share the socket instance throughout the application.

Now, we need to wrap our application with this socket provider to get access to using WebSocket for sending and receiving data.

QueryClient and SocketProvider

Inside the same directory, create a new file providers.tsx which we will use to wrap our child components with the QueryClientProvider from @tanstack/react-query and our newly created SocketProviderClient.

Add the following lines of code to the file:

// 👇 src/providers/providers.tsx

"use client";

import { PropsWithChildren, useState } from "react";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import SocketProviderClient from "@/providers/socket-provider";

const Providers = ({ children }: PropsWithChildren) => {
  const [queryClient] = useState(() => new QueryClient());

  return (
    <QueryClientProvider client={queryClient}>
      <SocketProviderClient>{children}</SocketProviderClient>
    </QueryClientProvider>
  );
};

export default Providers;

Now, all we need to do is, wrap our application with this <Providers /> component which will give access to our application socket and the react-query support.

Wrap the Application Layout with the Providers

Modify the layout.tsx in the root of the project with the following lines of code:

// 👇 src/app/layout.tsx

import type { Metadata } from "next";
import localFont from "next/font/local";
import { Toaster } from "@/components/ui/toaster";
import "./globals.css";
import { Navbar } from "@/components/navbar";
import Providers from "@/providers/providers";
import { getLanguage } from "@/tolgee/language";
import { getStaticData } from "@/tolgee/shared";
import { TolgeeProviderClient } from "@/tolgee/client";

// Rest of the code...

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const locale = await getLanguage();

  const staticData = await getStaticData([locale, "en"]);
  return (
    <html lang={locale}>
      <Providers>
        <body
          className={`${geistSans.variable} ${geistMono.variable} antialiased`}
        >
          <TolgeeProviderClient language={locale} staticData={staticData}>
            <Navbar />
            {children}
            <Toaster />
          </TolgeeProviderClient>
        </body>
      </Providers>
    </html>
  );
}

Custom WebServer with Socket.io

Now, we are ready to create our own Socket.io server. Create a new file server.ts and add the following lines of code:

// 👇 server.ts

// NOTE: Always Keep this 'tsconfig-paths' import at the top.
// It allows us to use custom paths and aliases defined in the
// `tsconfig.json` file like '@/db'
import "tsconfig-paths/register";

import { createServer } from "node:http";
import next from "next";
import { Server } from "socket.io";
import { db } from "@/db";
import { Task as TTask } from "@prisma/client";
import { DraggableLocation } from "react-beautiful-dnd";

const dev = process.env.NODE_ENV !== "production";
const hostname = process.env.HOST || "localhost";
const port = Number(process.env.PORT) || 3000;

const app = next({ dev, hostname, port });
const handler = app.getRequestHandler();

app.prepare().then(() => {
  const httpServer = createServer(handler);

  const io = new Server(httpServer);

  io.on("connection", (socket) => {
    console.log(`'${socket.id}' user just connected! ✨`);

    socket.on("disconnect", () => {
      console.log(`'${socket.id}' user just disconnected! 👀`);
    });
  });

  httpServer
    .once("error", (err) => {
      console.error("ERROR: server failure", err);
      process.exit(1);
    })

    .listen(port, () => {
      console.log(`Listening on '<http://$>{hostname}:${port}'`);
    });
});

Now, this server.ts file becomes the entry point to our application. We can do almost anything we would do with a socket.io server with a backend framework like express.js.

We can now listen for any events similar to listening for ‘connection’ and ‘disconnect’ here. We will modify this file in the future to listen to our custom events.

Typescript Server Configuration

Now, create a new file tsconfig.server.json which will hold settings specific to our server. Add the following lines of code:

// 👇 tsconfig.server.json

{
    "extends": "./tsconfig.json",
    "compilerOptions": {
      "module": "CommonJS",
      "outDir": "dist",
      "lib": ["es2019"],
      "target": "es2019",
      "isolatedModules": false,
      "noEmit": false,
    },
    "include": ["server.ts"]
  }

This tsconfig.server.json file extends the base TypeScript configuration found in tsconfig.json and specifies some custom settings for our project. It uses CommonJS for module output, and directs compiled files to the dist directory. The isolatedModules option is set to false, permitting files that may not be self-contained, while noEmit is false, allowing output files to be generated. Finally, it includes only the server.ts file in the compilation process.

Update the `package.json`

For our development server, we will be using nodemon and also now we are using server.ts file as our server. So, modify the scripts in the package.json file to this:

  // 👇 package.json

  "scripts": {
    "dev": "nodemon",
    "build": "next build && tsc --project tsconfig.server.json",
    "start": "NODE_ENV=production node server.ts",
    "lint": "next lint"
  },
  // Rest of the configuration...

Also, we need to tweak the nodemon configuration to watch changes in the server.ts file and change its execution command.

Nodemon Configuration

Create a new file nodemon.json in the root of the project with the following configuration:

// 👇 nodemon.json

{
  "watch": ["server.ts"],
  "exec": "ts-node --project tsconfig.server.json server.ts",
  "ext": "js ts"
}

Setup Kanban Board

Finally, now we are done with all the pre-works for our board. Let’s work on displaying and creating tasks for our board.

Task Component

Inside the src/components directory, create a new file task.tsx with the following lines of code:

// 👇 src/components/task.tsx

import { Task as TTask } from "@prisma/client";
import {
  Card,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import Link from "next/link";
import { T } from "@tolgee/react";

import { format } from "date-fns";

export const Task = ({ task }: { task: TTask }) => {
  const createdDate = format(new Date(task.createdAt), "hh:mm a, dd MMM yyyy");

  return (
    <Card className="w-full max-w-sm my-2 mx-auto">
      <CardHeader>
        <CardTitle>{task.title}</CardTitle>
      </CardHeader>
      {task.description ? (
        <CardContent>
          <Link
            href={`/kanban/${task.id}`}
            className="text-gray-800 font-semibold underline hover:text-gray-900 underline-offset-2"
          >
            <T keyName="view-description" />
          </Link>
        </CardContent>
      ) : null}
      <CardFooter className="text-sm text-gray-500">
        <span className="font-semibold mr-2">
          <T keyName="created-on" />
          {": "}
        </span>
        {createdDate}
      </CardFooter>
    </Card>
  );
};

We will use this to display tasks in our application. Here, we are essentially accepting a task object as a prop and using the Card component to present the task content in a card-like fashion. We are using the date-fns package to format the date in a more readable manner.

AddTask Component

Now, let’s create a component that we can use to add tasks to our board. Inside the src/components directory, create a new file add-task.tsx with the following lines of code:

// 👇 src/components/add-task.tsx

"use client";

import { ChangeEvent, FormEvent, useEffect, useState } from "react";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";
import { Textarea } from "@/components/ui/textarea";
import { GearIcon } from "@radix-ui/react-icons";
import { useMutation } from "@tanstack/react-query";
import { useTranslate, T } from "@tolgee/react";

import { useChat } from "ai/react";
import axios from "axios";
import { useToast } from "@/hooks/use-toast";
import { useSocket } from "@/providers/socket-provider";
import { Task as TTask } from "@prisma/client";
import { TCreateTaskSchema } from "@/lib/validators/create-task";
import { LoaderCircle } from "lucide-react";

export const AddTask = ({ userId }: { userId: string }) => {
  const [title, setTitle] = useState<string>("");
  const [description, setDescription] = useState<string>("");

  const socket = useSocket();

  const { t } = useTranslate();
  const { toast } = useToast();

  const {
    messages,
    handleSubmit: handleAISubmit,
    setInput: setAIInput,
    isLoading: isAILoading,
  } = useChat();

  useEffect(() => {
    const lastAssistantMessage = messages.findLast(
      (message) => message.role === "assistant",
    )?.content;
    if (lastAssistantMessage && description !== lastAssistantMessage) {
      setDescription(lastAssistantMessage);
    }
  }, [messages, description]);

  const handleGenerateClick = () => {
    setAIInput(title);
    handleAISubmit();
  };

  const { mutate: createTask, isPending } = useMutation({
    mutationFn: async () => {
      const payload: TCreateTaskSchema = {
        title,
        description,
      };
      const { data } = await axios.post(`/api/tasks/${userId}/create`, payload);
      return data as TTask;
    },
    onSuccess: (newTask) => {
      setTitle("");
      setDescription("");

      socket?.emit("task-created", newTask);
    },
    onError: (error) => {
      console.error("ERROR:", error);
      toast({
        title: t("something-went-wrong"),
        description: t("failed-to-create-task"),
        variant: "destructive",
      });
    },
  });

  const isSubmitDisabled = isPending || title.length === 0 || isAILoading;

  const handleFormSubmit = async (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    createTask();
  };

  const handleTitleChange = (event: ChangeEvent<HTMLInputElement>) => {
    setTitle(event.target.value);
  };

  return (
    <div className="flex justify-center mt-2">
      <div className="w-full max-w-5xl p-6 bg-white rounded-lg shadow-lg transition-shadow duration-300 ease-in-out hover:shadow-2xl">
        <form onSubmit={handleFormSubmit} className="space-y-4">
          <Input
            autoFocus
            type="text"
            placeholder={t("task-title")}
            value={title}
            onChange={handleTitleChange}
            className="w-full px-4 py-2 rounded"
          />
          <Button
            type="button"
            onClick={handleGenerateClick}
            className="flex items-center gap-2 font-semibold h-10 px-4 text-white rounded w-full sm:w-auto"
            disabled={title.split(" ").length < 3 || isPending || isAILoading}
          >
            {isAILoading ? (
              <LoaderCircle className="w-5 h-5 text-gray-300 animate-spin" />
            ) : (
              <GearIcon className="w-5 h-5 text-gray-300" />
            )}
            <T keyName="generate" />
          </Button>

          <Textarea
            placeholder={t("task-description")}
            value={description}
            // Prevent user input in Textarea
            readOnly
            className="mt-4 w-full h-28 px-4 py-2 border border-gray-300 rounded resize-none"
          />

          <Button
            type="submit"
            className="font-semibold h-10 px-4 text-white rounded w-full sm:w-auto"
            disabled={isSubmitDisabled}
          >
            {isPending && (
              <LoaderCircle className="w-5 h-5 text-gray-300 animate-spin" />
            )}
            <T keyName="submit" />
          </Button>
        </form>
      </div>
    </div>
  );
};

This component has a lot going on. There are two input fields, both of which are controlled components. However, the textarea is set to readOnly since it’s meant to be populated by the AI rather than by the user. We use two state variables, title, and description, to manage the title and description fields.

When the user clicks the submit button, an API request is made to our task creation endpoint, which adds a new task for the user in the database and returns it. If any errors occur, a toast displays the translated error message. Upon success, we reset the input fields and emit an event that the server will pick up, triggering an update on the board component to display all tasks.

The useChat hook, accessed from Vercel's AI SDK, is particularly interesting here. It provides access to fields like the message history and the current input message, along with the isPending variable, which tracks whether the AI’s response is still loading.

When the user clicks the Generate button, we submit the title to the AI. Once we receive a response, we check the messages field using the useEffect hook. If the assistant’s message updates, we set the description to this new message.

Update the `server.ts` file

Now, we will update the server.ts file to also listen for the task-created event. Modify the server.ts file in the root of the project with the following lines of code:

// 👇 server.ts

// Rest of the code...

app.prepare().then(() => {
  const httpServer = createServer(handler);

  const io = new Server(httpServer);

  io.on("connection", (socket) => {
    console.log(`'${socket.id}' user just connected! ✨`);

    socket.on("task-created", async (payload: TTask) => {
      io.sockets.emit("task-created", payload);
    });

    socket.on("disconnect", () => {
      console.log(`'${socket.id}' user just disconnected! 👀`);
    });
  });

  httpServer
    .once("error", (err) => {
      console.error("ERROR: server failure", err);
      process.exit(1);
    })

    .listen(port, () => {
      console.log(`Listening on '<http://$>{hostname}:${port}'`);
    });
});

Here, we listen for that event, and once it is received, we emit it to all the connected sockets. It is then received by the <Board /> component, which we will create in a moment. This component will be responsible for displaying all the tasks in a board format and updating the tasks with the received data.

Setup API Routes for AI and Task creation

Now, in our <AddTask /> component, when the user clicks on the Generate button, the handleAISubmit function makes a call to /api/chat endpoint with a POST request. So, we need to create that API route for handling response streaming to our description field.

Zod Schema for Message Validation

Let’s create a schema file for validation of the input from the user and the AI. Inside the src/lib/validators directory, create a new file message.ts with the following lines of code:

// 👇 src/lib/validators/message.ts

import { z } from "zod";

const MessageSchema = z.object({
  role: z.string().min(1),
  content: z.string().min(1),
});

export const ResponseBodySchema = z.object({
  messages: z.array(MessageSchema),
});

export type TResponseBodySchema = z.infer<typeof ResponseBodySchema>;

Now, we can use these schemas to infer the type of response from the AI to get type validation in our API route.

Chat Route for OpenAI

Finally, Inside the src/api/chat directory, create a new file route.ts with the following lines of code:

// 👇 src/api/chat/route.ts

import { ResponseBodySchema } from "@/lib/validators/message";
import { NextRequest, NextResponse } from "next/server";

import { openai } from "@ai-sdk/openai";
import { streamText, convertToCoreMessages } from "ai";

// Allow streaming responses up to 15 seconds
export const maxDuration = 15;

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    const validatedFields = ResponseBodySchema.safeParse(body);

    if (!validatedFields.success) {
      return NextResponse.json(
        {
          errors: validatedFields.error.flatten().fieldErrors,
        },
        { status: 422 },
      );
    }

    const { messages } = validatedFields.data;

    const lastUserMessage = messages.findLast(
      (message) => message.role === "user",
    )?.content;

    if (!lastUserMessage) {
      return NextResponse.json(
        { error: "No user message found" },
        { status: 400 },
      );
    }

    const response = await streamText({
      model: openai("gpt-3.5-turbo"),
      messages: convertToCoreMessages([
        {
          role: "user",
          content: `Generate a short description for a kanban board task with the title: ${lastUserMessage}.
          Make sure to give the response in plain text and not include any markdown characters.`,
        },
      ]),
    });

    return response.toDataStreamResponse();
  } catch (error) {
    console.error("ERROR:", error);
    return NextResponse.json(
      { error: "Something went wrong" },
      { status: 500 },
    );
  }
}

In this API route, we start by validating the input to ensure it includes a messages array where each object has a role and content field. Next, we extract the latest user message (i.e., the most recent question or request to the AI) from this array. With this message in hand, we pass it to the streamText function, prompting the AI to generate a task description based on the message content.

Finally, we return the response as a data stream, allowing the client to update the messages array in real-time. This streaming response triggers the useEffect hook, which updates the description field, displaying the AI-generated description directly in the text area.

Zod Schema for Add Task Validation

Inside the src/lib/validators directory, create a new file create-task.ts with the following lines of code:

// 👇 src/lib/validators/create-task.ts

import { z } from "zod";

export const CreateTaskSchema = z.object({
  title: z.string().trim().min(1).max(50),
  description: z.string().trim().optional(),
});

export type TCreateTaskSchema = z.infer<typeof CreateTaskSchema>;

The CreateTaskSchema schema defines the structure for creating a task. It requires a title between 1 and 50 characters and includes an optional description.

The inferred type, TCreateTaskSchema, provides type safety for this structure, allowing us to use it for consistent typing in both client-side and server-side code.

API Endpoint for Creating a Task

Now, let’s work on the task creation endpoint, i.e. /api/tasks/[userId]/create.

Create a new directory with this path and create a route.ts inside the file with the following lines of code:

// 👇 app/api/tasks/[userId]/create/route.ts

import { db } from "@/db";
import { CreateTaskSchema } from "@/lib/validators/create-task";
import { getServerSession } from "next-auth";
import { NextRequest, NextResponse } from "next/server";

export async function POST(
  req: NextRequest,
  { params }: { params: { userId: string } },
) {
  try {
    const session = await getServerSession();

    if (!session) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    const body = await req.json();

    const validatedFields = CreateTaskSchema.safeParse(body);
    if (!validatedFields.success) {
      return NextResponse.json(
        { error: validatedFields.error.flatten().fieldErrors },
        { status: 422 },
      );
    }

    const { title, description } = validatedFields.data;

    const columnTasks = await db.task.findMany({
      where: {
        userId: params.userId,
        column: 0,
      },
    });

    const newOrder = columnTasks.length;

    const newTask = await db.task.create({
      data: {
        title,
        ...(description ? { description } : {}),
        userId: params.userId,
        column: 0,
        order: newOrder,
      },
    });

    return NextResponse.json(newTask);
  } catch (error) {
    console.error("ERROR:", error);
    return NextResponse.json(
      { error: "Internal Server Error" },
      { status: 500 },
    );
  }
}

This API route creates a new task. It first checks for a valid user session with getServerSession. If there is no active session (the user is not logged in), it returns a 401 Unauthorized error. Next, it validates the request body with CreateTaskSchema, and if validation fails, it responds with a 422 status and error details.

If the input is valid, it counts tasks in the default column (0 - ongoing) for ordering, then creates a new task in the database with the provided title, optional description, user ID, column, and order value, which is the length of the array. The new task is returned on success; otherwise, it returns an Internal Server Error.

Build the Kanban Board

💡 Here, we will build the main UI components and some APIs for updating tasks on our Board

Board Component

Now, let’s create a <Board /> component that renders multiple different tasks for our application.

Inside the src/components directory, create a new file board.tsx with the following lines of code:

// 👇 src/components/board.tsx

"use client";

import { useSocket } from "@/providers/socket-provider";
import { useEffect, useState } from "react";
import {
  DragDropContext,
  Draggable,
  Droppable,
  DropResult,
} from "react-beautiful-dnd";
import { getSession } from "next-auth/react";
import axios from "axios";
import { Session } from "next-auth";
import { Task as TTask } from "@prisma/client";
import { Task } from "@/components/task";
import { T, useTranslate } from "@tolgee/react";
import { useToast } from "@/hooks/use-toast";

export const Board = ({ userId }: { userId: string }) => {
  const socket = useSocket();
  const { toast } = useToast();

  const { t } = useTranslate();

  const [tasks, setTasks] = useState<TTask[] | null>([]);
  const [session, setSession] = useState<Session | null>(null);

  useEffect(() => {
    const fetchSession = async () => {
      try {
        const sessionData = await getSession();
        setSession(sessionData);
      } catch (error) {
        console.error("ERROR:", error);
        toast({
          title: t("something-went-wrong"),
          variant: "destructive",
        });
      }
    };
    fetchSession();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  useEffect(() => {
    if (!session) return;

    const fetchUserTasks = async () => {
      try {
        const userEmail = session.user?.email || "";
        const { data } = (await axios.get("/api/tasks", {
          params: { userId, email: userEmail },
        })) as { data: { tasks: TTask[] } };

        setTasks(data.tasks);
      } catch (error) {
        console.error("ERROR:", error);
      }
    };
    fetchUserTasks();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [session]);

  useEffect(() => {
    const handleTasksUpdated = (data: TTask[] | undefined) => {
      if (!data) return;
      setTasks(data);
    };

    const handleTaskCreated = (newTask: TTask) => {
      setTasks((prevTasks) => [...(prevTasks || []), newTask]);
    };

    socket?.on("tasks-updated", handleTasksUpdated);
    socket?.on("task-created", handleTaskCreated);

    return () => {
      socket?.off("tasks-updated", handleTasksUpdated);
      socket?.off("task-created", handleTaskCreated);
    };
  }, [socket]);

  const tasksByStatus = (status: number) =>
    tasks?.filter((task) => task.column === status);

  const columns = {
    0: "Ongoing",
    1: "Pending",
    2: "Completed",
  };

  const handleDragEnd = ({ destination, source }: DropResult) => {
    if (!destination) return;
    if (
      destination.index === source.index &&
      destination.droppableId === source.droppableId
    )
      return;

    socket?.emit("task-drag", {
      source,
      destination,
      email: session?.user?.email || "",
    });
  };

  if (!tasks || tasks.length === 0) return null;

  return (
    <div className="container mx-auto mt-10 mb-5">
      <DragDropContext onDragEnd={handleDragEnd}>
        <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
          {Object.entries(columns).map(([status, title]) => (
            <div
              key={status}
              className="p-4 border rounded-lg shadow-lg bg-gray-50 flex flex-col items-center"
            >
              <h2 className="text-xl font-bold mb-4 text-center">
                <T keyName={title.toLowerCase()} />
              </h2>
              <Droppable droppableId={status}>
                {(provided) => (
                  <div
                    {...provided.droppableProps}
                    ref={provided.innerRef}
                    className="w-full flex flex-col items-center min-h-40"
                  >
                    {tasksByStatus(Number(status))?.map((task, index) => (
                      <Draggable
                        key={task.id}
                        draggableId={task.id}
                        index={index}
                      >
                        {(provided) => (
                          <div
                            ref={provided.innerRef}
                            {...provided.draggableProps}
                            {...provided.dragHandleProps}
                            className="w-full"
                          >
                            <Task task={task} />
                          </div>
                        )}
                      </Draggable>
                    ))}
                    {provided.placeholder}
                  </div>
                )}
              </Droppable>
            </div>
          ))}
        </div>
      </DragDropContext>
    </div>
  );
};

This is the component where we will be utilizing the main feature of a Kanban board, i.e., drag-and-drop items. For this, we will use our previously installed package, react-beautiful-dnd. The component first fetches the user session using getSession and sets it in the state. Once the session is available, it makes an API call to fetch tasks for the logged-in user and stores them in tasks.

It listens for two-socket events —tasks-updated, which updates the task list, and task-created, which appends a new task to the current task list.

Tasks are grouped by column status (0 for "Ongoing," 1 for "Pending," and 2 for "Completed") using the tasksByStatus function. The component maps these statuses to render each column with the corresponding tasks.

The DragDropContext wrapper enables drag-and-drop functionality. When a task is moved, handleDragEnd sends the new task order to the server via a socket event for syncing.

Each column is a Droppable area that contains draggable Task components, allowing users to reorder tasks within and across columns.

API Route to fetch User Tasks

Now, let’s work on the /api/tasks route which is responsible for returning a list of user tasks from the database.

Inside the app/api/tasks, create a route.ts file with the following lines of code:

// 👇 src/app/api/tasks/routs.ts

import { db } from "@/db";
import { getServerSession } from "next-auth";
import { NextRequest, NextResponse } from "next/server";

export async function GET(req: NextRequest) {
  try {
    const session = await getServerSession();

    if (!session) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    const url = new URL(req.url);
    const passedEmail = url.searchParams.get("email") || "";
    const userId = url.searchParams.get("userId");

    if (!userId || session.user?.email !== passedEmail) {
      return NextResponse.json({ error: "Forbidden" }, { status: 403 });
    }

    const userWithBoardsAndTasks = await db.user.findUnique({
      where: { email: passedEmail, id: userId },
      select: {
        id: true,
        password: false,
        tasks: true,
      },
    });

    if (!userWithBoardsAndTasks) {
      return NextResponse.json({ error: "User not found" }, { status: 404 });
    }

    return NextResponse.json(userWithBoardsAndTasks);
  } catch (error) {
    console.error("ERROR:", error);
    return NextResponse.json(
      { error: "Internal Server Error" },
      { status: 500 },
    );
  }
}

The GET function in this API route fetches a user's information, including their tasks. It starts by validating the authentication using getServerSession. If the session is absent, a 401 Unauthorized status is returned.

The route extracts the email and userId from the request URL's query parameters. If the userId is missing or the session's user email does not match the provided email, a 403 Forbidden status is returned.

Next, it queries the database for a user with the specified email and ID, selecting only the user's ID and tasks. If no user is found, a 404 Not Found status is returned. If the user exists, their data is sent in the response.

Now, we are almost done; we just need to listen for the task-drag event from the <Board /> component inside the server.ts file and handle it accordingly.

Update the `server.ts` file

Modify the server.ts file in the root of the project with the following lines of code:

// 👇 server.ts

// NOTE: Always Keep this 'tsconfig-paths' import at the top.
// It allows us to use custom paths and aliases defined in the
// `tsconfig.json` file like '@/db'
import "tsconfig-paths/register";

import { createServer } from "node:http";
import next from "next";
import { Server } from "socket.io";
import { db } from "@/db";
import { Task as TTask } from "@prisma/client";
import { DraggableLocation } from "react-beautiful-dnd";

const dev = process.env.NODE_ENV !== "production";
const hostname = process.env.HOST || "localhost";
const port = Number(process.env.PORT) || 3000;

const app = next({ dev, hostname, port });
const handler = app.getRequestHandler();

app.prepare().then(() => {
  const httpServer = createServer(handler);

  const io = new Server(httpServer);

  io.on("connection", (socket) => {
    console.log(`'${socket.id}' user just connected! ✨`);

    socket.on("task-created", async (payload: TTask) => {
      io.sockets.emit("task-created", payload);
    });

    socket.on(
      "task-drag",
      async (payload: {
        source: DraggableLocation;
        destination: DraggableLocation;
        email: string;
      }) => {
        const { source, destination, email } = payload;

        try {
          const updatedTasks = await handleTaskDrag(email, source, destination);
          if (updatedTasks) {
            io.sockets.emit("tasks-updated", updatedTasks);
          }
        } catch (error) {
          console.error(
            "ERROR: failed to update or fetch the user tasks",
            error,
          );
        }
      },
    );

    socket.on("disconnect", () => {
      console.log(`'${socket.id}' user just disconnected! 👀`);
    });
  });

  httpServer
    .once("error", (err) => {
      console.error("ERROR: server failure", err);
      process.exit(1);
    })

    .listen(port, () => {
      console.log(`Listening on '<http://$>{hostname}:${port}'`);
    });
});

async function handleTaskDrag(
  email: string,
  source: DraggableLocation,
  destination: DraggableLocation,
) {
  const dbUser = await db.user.findUnique({ where: { email } });
  if (!dbUser) return;

  const tasks = await db.task.findMany({ where: { userId: dbUser.id } });
  return updateTasksInDB(tasks, source, destination);
}

async function updateTasksInDB(
  tasks: TTask[],
  source: DraggableLocation,
  destination: DraggableLocation,
) {
  const { droppableId: sourceColumn, index: sourceOrder } = source;
  const { droppableId: destinationColumn, index: destinationOrder } =
    destination;

  const taskMoved = tasks.find(
    (task) =>
      task.column === Number(sourceColumn) && task.order === sourceOrder,
  );

  if (!taskMoved) return;

  // Filter the moved task from the tasks array.
  tasks = tasks.filter((task) => task.id !== taskMoved.id);

  taskMoved.column = Number(destinationColumn);
  taskMoved.order = destinationOrder;

  const columns: { [key: number]: TTask[] } = {
    0: tasks.filter((task) => task.column === 0),
    1: tasks.filter((task) => task.column === 1),
    2: tasks.filter((task) => task.column === 2),
  };

  columns[taskMoved.column].splice(destinationOrder, 0, taskMoved);

  // Reorder each column to have sequential order values
  Object.values(columns).forEach((columnTasks) => {
    columnTasks.forEach((task, index) => {
      task.order = index;
    });
  });

  tasks = [...columns[0], ...columns[1], ...columns[2]];

  // Sort tasks by column and order before returning
  tasks.sort((a, b) =>
    a.column === b.column ? a.order - b.order : a.column - b.column,
  );

  const updateTasksPromises = tasks.map((task) =>
    db.task.update({
      where: {
        id: task.id,
      },
      data: {
        column: task.column,
        order: task.order,
      },
    }),
  );

  // Execute all updates in parallel
  await Promise.all(updateTasksPromises);

  return tasks;
}

The task-drag event is responsible for handling the drag-and-drop functionality of tasks within your Kanban board. When a task is dragged from one position to another, this event is triggered, allowing the server to update the task's status and position in the database.

When a client emits the 'task-drag' event, it sends a payload containing the source and destination locations of the task being dragged, as well as the user's email address. The server listens for this event.

The server then calls the handleTaskDrag function, passing the user's email, the source, and the destination as arguments. This function is responsible for fetching the user from the database using their email address, ensuring that the task updates are associated with the correct user.

Within handleTaskDrag, the function retrieves the user's tasks from the database and then calls updateTasksInDB, which processes the task update logic. This function updates the column and order of the task based on the drag-and-drop operation, ensuring that the tasks are rearranged correctly in the database.

If the tasks are updated successfully, the updated tasks are emitted back to all connected clients using io.sockets.emit, broadcasting the changes so that the user interface can be updated in real time.

Now that we have both the <AddTask /> and the <Board /> components ready, it's time to use them inside our application.

Kanban Page Route

Inside the src/app/kanban directory, create a new file page.tsx with the following lines of code:

// 👇 src/app/kanban/page.tsx

import { AddTask } from "@/components/add-task";
import { Board } from "@/components/board";
import { db } from "@/db";
import { getServerSession } from "next-auth";
import { redirect } from "next/navigation";

export default async function Page() {
  const session = await getServerSession();
  if (!session) redirect("/login");

  const dbUser = await db.user.findUnique({
    where: { email: session.user?.email || "" },
    select: { id: true },
  });

  if (!dbUser) redirect("/register");

  const userId = dbUser.id;

  return (
    <>
      <AddTask userId={userId} />
      <Board userId={userId} />
    </>
  );
}

It starts by checking the user's session with getServerSession, redirecting to the login page if the session is absent. This statement is probably never going to execute because we built a middleware.ts file earlier in the src directory, which states that any route starting with /kanban cannot be accessed by unauthenticated users.

However, it never hurts to add an extra layer of validation, as Next.js deduplicates any similar duplicate requests. After confirming the session, it retrieves the user's ID from the database; if the user is not found, it redirects to the registration page.

Finally, it renders the AddTask and Board components, passing the user's ID as a prop.

There is one last thing remaining: if you’ve noticed, in the <Task /> component earlier, we had a way for the user to view the description with a link to /kanban/[taskId].

Kanban Description Page Route

Inside the src/app/kanban/[taskId] directory, create a new file page.tsx with the following lines of code:

// 👇 src/app/kanban/[taskId]/page.tsx

import { buttonVariants } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { db } from "@/db";
import { ArrowLeft } from "lucide-react";
import Link from "next/link";
import { redirect } from "next/navigation";
import { getTranslate, T } from "@/tolgee/server";
import { getServerSession } from "next-auth";

export default async function Page({ params }: { params: { taskId: string } }) {
  const session = await getServerSession();
  if (!session) redirect("/login");

  const task = await db.task.findUnique({
    where: { id: params.taskId },
  });

  if (!task) redirect("/kanban");

  const t = await getTranslate();

  return (
    <div className="flex items-center justify-center px-4 mt-20">
      <div className="w-full max-w-lg space-y-4">
        <Link
          href={"/kanban"}
          className={buttonVariants({
            variant: "secondary",
            size: "lg",
          })}
        >
          <ArrowLeft className="mr-2 h-4 w-4" />
          <T keyName="back" />
        </Link>

        <Card className="p-6 bg-white shadow-lg rounded-lg border border-gray-200">
          <CardHeader>
            <CardTitle className="text-2xl font-bold text-gray-800">
              {task.title}
            </CardTitle>
          </CardHeader>

          <CardContent>
            <p className="text-gray-700 text-lg leading-relaxed">
              {task.description || t("no-description-provided-for-this-task")}
            </p>
          </CardContent>
        </Card>
      </div>
    </div>
  );
}

The same is true here: we first validate the session. As mentioned earlier, this should never be executed because of the middleware we already have in place.

Then, we simply fetch the task from the database using the taskId we received as a prop. If the task does not exist, we redirect the user to the /kanban page. If it does exist, we display the title and description of the task.

Home Page Route

Finally, let’s work on the root Home page of our application (/ route). Modify the src/app/page.tsx with the following lines of code:

import { getServerSession } from "next-auth";
import { redirect } from "next/navigation";

export default async function Home() {
  const session = await getServerSession();
  if (session) redirect("/kanban");

  redirect("/login");
}

Here, we simply check if the user is authenticated. If they are, they are sent to the /kanban route; if not, they are redirected to the login page.

That is literally all we need to do to get our Kanban board running perfectly. Now, you should have a fully functioning Kanban board with authentication, localization, and real-time support. 🥳

Conclusion ⚡

Wow! 😮‍💨 We’ve accomplished a lot together today.

If you made it this far, you’ve successfully built an AI and localization-powered Kanban board from scratch along with the help of a blog post. Give yourself a well-deserved pat on the back!

Star the Tolgee repository ⭐

Follow Tolgee for more content like this.

Tolgee Follow

Tolgee is an open-source developer tool for web apps localization 🐁

Share your thoughts in the comment section below! 👇

Thank you so much for reading! 🎉 🫡

I have localized the best short-linking platform in the world

Jan Cizmar — Wed, 06 Nov 2024 10:18:05 +0000

As part of playing with Tolgee, I have tried translating dub.co, a well-established open-source company, into other languages! It took me 1 hour, and the results are astonishing!

In this tutorial, I’ll walk you through an easy and efficient approach to localization in a Next.js application using Tolgee - a platform designed for fast and autonomous translation management.

You will also learn how to integrate Tolgee with Dub.co, a popular link management platform allowing users to access and interact with the application in their preferred languages.

Prerequisites

To fully understand this tutorial, you need to have a basic understanding of React or Next.js.

You will also need to set up the following:

Tolgee Project - an existing project with at least two language translations.
Tolgee CLI - allows you to interact with the Tolgee platform from your computer using the command line.
Docker - required for running Dub.co. It is an open-source platform that uses containerization to make it easier to create, deploy, and run applications.
Docker Compose - a software application for defining and running multi-container Docker applications.
Python (version 3.8 or higher): necessary for configuring some of Dub.co’s packages.

What is Tolgee?

Tolgee is a developer-friendly localization platform that allows you to translate your application into any language without modifying your code. It is designed for web applications but also supports mobile and desktop applications.

With Tolgee, you don't need to look for keys in your source code, edit localization files, or perform manual exporting data for translators. Tolgee offers in-context translation, a translation memory for keeping track of already translated strings, machine and auto translations, and many others.

Please help us with a star. 🥹

It would help us to create more articles like this 💖

Star the Tolgee repository ⭐

How to set up Dub.co on your local computer

Dub.co is an open-source link management platform that allows marketing teams to add powerful analytics to their links, create short links, generate QR codes for links, and many more. It was created by Steven Tey (formerly of Vercel).

Follow these steps to set up Dub.co on your computer:

Clone the Dub.co GitHub repository by running the code snippet below.

git clone https://github.com/dubinc/dub.git

Navigate into the dub folder and install the project dependencies:

pnpm install

Within the apps/web folder, rename the .env.example file to .env.

Create a new Tinybird account, and copy your Admin Auth Token into the .env file.

TINYBIRD_API_KEY=<your_admin_auth_token>

Navigate into the packages/tinybird directory and install the Tinybird CLI using the following command:

pip3 install tinybird-cli

Execute the following command in your terminal and enter your Admin Auth Token when prompted to authenticate using the Tinybird CLI:

tb auth

Publish the Tinybird datasource and endpoints by running the code snippet below:

tb push

Create an Upstash database and copy the following credentials from the REST API section to the .env file:

UPSTASH_REDIS_REST_URL=<your_rest_url>
UPSTASH_REDIS_REST_TOKEN=<your_rest_token>

Navigate to the QStash tab and copy the following credentials into the .env file.

QSTASH_TOKEN=
QSTASH_CURRENT_SIGNING_KEY=
QSTASH_NEXT_SIGNING_KEY=

Next, within the apps/web directory, run the following command to start the Docker Compose stack:

docker-compose up

Generate the Prisma client and create its database tables using the following commands:

npx prisma generate
npx prisma db push

Dub.co supports multiple authentication methods. Create a GitHub app and copy the URL below as its callback URL.

http://localhost:8888/api/auth/callback/github

Finally, start the development server:

pnpm dev

You can access the web application by navigating to http://localhost:8888 in your browser, create a workspace, and get started. If you encounter any issues, refer to the complete installation guide for more detailed assistance.

How to configure Tolgee in a Next.js application

In this section, you'll learn how to add Tolgee to a Next.js application and configure it to support multiple languages, allowing users to access the app in their preferred language.

To implement localization in Next.js applications, you will need to install the Tolgee React SDK.

npm install @tolgee/react

Next, create a Tolgee Platform account and sign into your dashboard.

Add a new project by clicking the Project button and selecting your preferred languages for the project. For this application, we'll use five languages: English (as the base language), Chinese, Hindi, Spanish, and Arabic.

Click the profile icon in the top-right corner of your dashboard, then select Project API Keys to create an API key for your Tolgee project.

Create a .env.development.local and copy your API key into the file:

NEXT_PUBLIC_TOLGEE_API_KEY=<paste_your_API_key_here>
NEXT_PUBLIC_TOLGEE_API_URL=https://app.tolgee.io

Select Translations from the sidebar menu and add a new translation to the project.

You can create a translation key, add the content or string you need to translate, provide a description, and then save it.

Tolgee provides various machine translation options by default, allowing you to easily translate content into the available languages within your project.

Congratulations! You’ve successfully set up the Tolgee platform for translations within your application. Next, let’s configure Tolgee within the Dub.co project to easily generate translations directly in the application.

How to set up localization in Dub.co

In this section, I’ll guide you through configuring Tolgee to support client-server interactions within the Dub.co project.

First, install the Tolgee CLI package.

npm install --global @tolgee/cli

Run the following code snippet to sign into your Tolgee platform using your project API key.

tolgee login <your_tolgee_api_key>

Next, create an i18n folder within the apps/web directory. This folder will store the JSON files containing translations for the various languages available in the Tolgee platform project.

apps
├── web #👈🏼 this folder
    ├── app 
    ├── i18n  #👈🏼 newly created 
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

Within the apps/web directory, fetch the language translations created in your Tolgee project by running the code snippet below:

tolgee --project-id <tolgee_platform_project_id> pull --path ./i18n

The code snippet above automatically populates the i18n folder with the various language translations created within the Tolgee platform.

apps
├── web 
    ├── app 
    ├── i18n #👇🏻 translation files
        ├── ar.json
        ├── en.json
        ├── es.json 
        ├── zh.json  
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

Create a tolgee folder which will contain Tolgee configurations within the apps/web directory:

apps
├── web # 👈🏼 this folder
    ├── app 
    ├── i18n  
    ├── tolgee # 👈🏼 Tolgee folder
packages
├── tailwind-config
├── tinybird
├── tsconfig
├── ui
├── utils

Add a shared.ts file in the tolgee directory, then copy the following code snippet into the file:

import { FormatIcu } from "@tolgee/format-icu";
import { DevTools, Tolgee } from "@tolgee/react";

const apiKey = process.env.NEXT_PUBLIC_TOLGEE_API_KEY;
const apiUrl = process.env.NEXT_PUBLIC_TOLGEE_API_URL;

//👇🏻 available translations
export const ALL_LOCALES = ["en", "ar", "es", "zh"];

//👇🏻 default translation
export const DEFAULT_LOCALE = "en";

//👇🏻 returns an object containing the translation files
export async function getStaticData(languages: string[]) {
  const result: Record<string, any> = {};

  for (const lang of languages) {
    result[lang] = (await import(`../i18n/${lang}.json`)).default;
  }

  return result;
}

export function TolgeeBase() {
  return Tolgee().use(FormatIcu()).use(DevTools()).updateDefaults({
    apiKey,
    apiUrl,
    fallbackLanguage: "en",
    defaultLanguage: DEFAULT_LOCALE,
  });
}

The code snippet above configures Tolgee with default and fallback languages to enable localization within the application.

Next, create a client.tsx file in the tolgee directory, then copy the code snippet below into the file:

'use client';

import { TolgeeBase } from './shared';
import { TolgeeProvider, useTolgeeSSR } from '@tolgee/react';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';

type Props = {
  locales: any;
  locale: string;
  children: React.ReactNode;
};

const tolgee = TolgeeBase().init();

export const TolgeeNextProvider = ({ locale, locales, children }: Props) => {
  const tolgeeSSR = useTolgeeSSR(tolgee, locale, locales);
  const router = useRouter();

  useEffect(() => {
    const { unsubscribe } = tolgeeSSR.on('permanentChange', () => {
      router.refresh();
    });

    return () => unsubscribe();
  }, [tolgeeSSR, router]);

  return (
    <TolgeeProvider
      tolgee={tolgeeSSR}
      options={{ useSuspense: false }}
      fallback="Loading"
    >
      {children}
    </TolgeeProvider>
  );
};

The client.tsx file serves the purpose of translating client components and also enables the in-context functionality for server-rendered components. The code snippet above defines the TolgeeNextProvider component, which wraps the entire Dub.co application, providing configurations needed to manage language changes and translations.

Create a custom locale.ts file in the tolgee folder and copy the following code snippet into it:

"use server";

import { cookies, headers } from "next/headers";
import { ALL_LOCALES, DEFAULT_LOCALE } from "./shared.ts";

const COOKIE_NAME = "NEXT_LOCALE";

//👇🏻 Retrieves the current language setting for the user.
// If not set, it attempts to detect the user's language from browser preferences.
// Defaults to the application's default locale if no match is found.
export async function getUserLocale() {
  return (
    cookies().get(COOKIE_NAME)?.value || detectLanguage() || DEFAULT_LOCALE
  );
}

//👇🏻 Sets the user’s preferred language in a cookie to persist their selection.
export async function setUserLocale(locale: string) {
  cookies().set(COOKIE_NAME, locale);
}

//👇🏻 Attempts to detect the user's preferred language based on browser settings.
const detectLanguage = () => {
  const allPreferred = getAcceptedLanguages();

  for (const language of allPreferred) {
    // Checks for an exact match in the list of supported locales
    const exactMatch = ALL_LOCALES.find((l) => l === language);
    if (exactMatch) {
      return exactMatch;
    }

    // Falls back to matching only the two-letter language code
    const getTwoLetters = (fullTag: string) =>
      fullTag.replace(/^(.+?)(-.*)?$/, "$1");

    const preferredTwoLetter = getTwoLetters(language);
    const twoLetterMatch = ALL_LOCALES.find(
      (l) => getTwoLetters(l) === preferredTwoLetter,
    );
    if (twoLetterMatch) {
      return twoLetterMatch;
    }
  }
};

//👇🏻 Retrieves accepted languages from the "Accept-Language" HTTP header.
// Returns an array of languages in order of preference.
function getAcceptedLanguages() {
  const acceptLanguageHeader = getAcceptLanguageHeader();
  if (!acceptLanguageHeader) {
    return [];
  }

  // Splits the header value by commas to separate each language code
  return acceptLanguageHeader.split(",").map((lang) => {
    const [language] = lang.split(";");
    return language.trim();
  });
}

//👇🏻 Fetches the "Accept-Language" HTTP header from the user's browser.
// This header lists languages preferred by the user, ranked by preference.
function getAcceptLanguageHeader() {
  return headers().get("Accept-Language");
}

Finally, create a server.tsx file in the tolgee folder, then copy the following code snippet into the file:

import { getUserLocale } from "./locale.ts";
import { TolgeeBase, ALL_LOCALES, getStaticData } from './shared';
import { createServerInstance } from '@tolgee/react/server';

export const { getTolgee, getTranslate, T } = createServerInstance({
   getLocale: async () => getUserLocale(),
  createTolgee: async (locale) =>
    TolgeeBase().init({
      // including all locales
      // on server we are not concerned about bundle size
      staticData: await getStaticData(ALL_LOCALES),
      observerOptions: {
        fullKeyEncode: true,
      },
      language: locale,
      fetch: async (input, init) => {
        const data = await fetch(input, { ...init, next: { revalidate: 0 } });
        return data;
      },
    }),
});

The application utilizes the React server cache for sharing Tolgee instance across components in a single render. This allows the app to use the Tolgee instance anywhere in the server components.

Congratulations! You’ve successfully configured Tolgee and are now ready to start adding translations to various content within the application.

How to translate your application content with Tolgee

Here, you'll learn how to translate content within your web application and see how Tolgee enables easy in-app translation.

To get started, you need to wrap the entire Dub.co application with the TolgeeNextProvider component, defined in tolgee/client.tsx. Navigate to the apps/web/app folder, then go to the app.dub.co/(dashboard) directory, and update the layout.tsx file as shown below:

import { MainNav } from "@/ui/layout/main-nav";
import { HelpButtonRSC } from "@/ui/layout/sidebar/help-button-rsc";
import Toolbar from "@/ui/layout/toolbar/toolbar";
import { constructMetadata } from "@dub/utils";
import { ReactNode } from "react";
import Providers from "../../providers";
//👇🏻 Tolgee imports
import { TolgeeNextProvider } from "../../../tolgee/client.tsx";
import { getUserLocale } from "../../../tolgee/locale.ts";
import { getStaticData } from "../../../tolgee/shared.ts";


export const metadata = constructMetadata();

export default async function Layout({ children }: { children: ReactNode }) {
  const locale = await getUserLocale();
  const locales = await getStaticData([locale, "en"]);

  return (
    <TolgeeNextProvider locale={locale} locales={locales}>
      <Providers>
        <div className="min-h-screen w-full bg-white">
          <MainNav toolContent={<HelpButtonRSC />}>{children}</MainNav>
        </div>
        {/* <ChangelogPopup /> */}
        <Toolbar show={["onboarding"]} />
      </Providers>
    </TolgeeNextProvider>
  );
}

The code snippet above wraps the dashboard routes with the Tolgee provider, enabling language switching and localization throughout the application.

Tolgee provides two hooks to help you select and translate text within your application: useTolgee and useTranslate.

The useTolgee hook returns the Tolgee instance, allowing you to subscribe to various events that will trigger re-renders when translating text.
The useTranslate hook includes a translation function (t function) that renders the actual translations directly within the app.

Update the page.tsx file in the app.dub.co/(dashboard)/[slug] directory by adding the following code snippet:

"use client";
import { PageContent } from "@/ui/layout/page-content";
import WorkspaceLinksClient from "./page-client";
//👇🏻 Tolgee installations
import { useTolgee, useTranslate } from "@tolgee/react";
import { setUserLocale } from "tolgee/locale";


export default function WorkspaceLinks() {
  const { t } = useTranslate();
  const tolgee = useTolgee(["pendingLanguage"]);
  const language = tolgee.getPendingLanguage();

  return (
    <PageContent title="Links">
    {/** -- HTML input for selecting the preferred language -- */}
      <div className="flex w-full flex-col px-10">
        <p>Select Language</p>
        <select
          defaultValue={language}
          className="rounded-sm"
          name="locale"
          id="locale"
          onChange={(e) => setUserLocale(e.currentTarget.value)}
        >
          <option value="en">English</option>
          <option value="es">Spanish</option>
          <option value="ar">Arabic</option>
          <option value="zh">Chinese</option>
        </select>

        <p>{t("hello")}</p>
      </div>
    {/** -- end of Tolgee -- */}
      <WorkspaceLinksClient />
    </PageContent>
  );
}

The code snippet above displays an HTML <select> tag that allows users to choose and switch between different languages. The {t("hello")} element uses Tolgee’s translation function to render a value of the "hello" key based on the selected language.

Finally, you can update the remaining content throughout the application to support language changes, allowing users to view all components in their selected language.

Tolgee also provides an in-context translation feature, allowing you to translate strings directly within your application, whether in development or production, simply by clicking the text and holding the Alt or Option key.

Congratulations! You've successfully completed the project for this tutorial.

The source code for this tutorial is available here:

https://github.com/JanCizmar/dub-with-tolgee

Conclusion

So far, you’ve learnt how to add localization to your software applications using Tolgee, implement support for multiple languages, and make language switching seamless within a real-world project.

Tolgee is a fast, developer-focused localization platform that allows you to provide context to your content and generate translations in seconds. It also supports multiple JavaScript frameworks, including Vue, Angular, and Svelte, and integrates with tools like Figma and a REST API for flexibility.

If you're looking to create a personalized experience for your users, Tolgee is an excellent choice. Feel free to contribute and star our GitHub repository, and join our Slack community to connect with others and engage with the team.

Thank you for reading!

✨8 Powerful Open-Source tools for Creating Accessible Web Apps ✨

Marketa Cizmar — Fri, 25 Oct 2024 09:49:12 +0000

Are you ready to elevate your skills and create websites that everyone can enjoy?

Making your websites and apps accessible means opening the door for everyone to enjoy what you’ve created, no matter their abilities.

This means creating experiences that are easy to navigate and understand for all users.

By focusing on accessibility, you’re not just enhancing user experience; you’re also opening your app to a wider audience and inviting new users to join your community. An inclusive design helps everyone feel welcome and can lead to more engagement and success.

In this list, we’ll introduce you to 8 open-source tools that will help you build user-friendly applications.

Let’s discover how you can make your projects shine! ✨

Localization Tools 🌍

Tolgee

Tolgee helps you manage translations in your web applications effortlessly. It streamlines the localization process, making it easier to offer your content in multiple languages.

Key Features: In-Context translation, team collaboration platform, automatic machine translation, native support for popular frameworks like React, Angular, and Vue

Why Do You Need It: By using Tolgee, you can ensure that users who speak different languages can understand and navigate your app. This inclusivity enhances the user experience and allows you to reach a wider audience.

Star the Tolgee repository ⭐

Color and Contrast Tools 🎨

Chroma.js

Chroma.js is a JavaScript library for color manipulation. It includes tools for working with color contrast, color blending, and color scales, making it a powerful tool for developers who need fine-grained control over color contrast in their applications.

Key Features: built-in WCAG contrast checking, create color scales and manipulate colors programmatically, supports various color models

Why Do You Need It: Chroma.js is perfect for developers who want more control over how colors are used in their applications. The built-in contrast checking ensures your colors meet accessibility standards, making it a valuable tool for accessible design.

Star the Chroma.js repository ⭐

Accessibility Testing Tools ✅

axe-core

Axe-core is a tool designed to identify accessibility issues in your web applications. It provides automated testing, helping you ensure that your app meets accessibility standards.

Key Features: Support of automated testing, integration with frameworks, detailed reporting, and cross-platform testing

Why Do You Need It: By using axe-core, you can catch potential accessibility problems early in the development process. This proactive approach helps create a better experience for all users, particularly those with disabilities.

Star the axe-core repository ⭐

Nightwatch.js

Nightwatch.js is an easy-to-use Node.js-based testing framework for automating browser testing. It uses Selenium under the hood, making it a great choice for developers looking to write tests in JavaScript.

Key Features: Simple syntax for writing tests, built-in assertions, support for various browser drivers, and easy integration with CI/CD tools.

Why Do You Need It: Nightwatch.js simplifies the process of writing and running automated tests for your web applications. By ensuring that accessibility standards are met, you can deliver a better experience for all users, reducing the risk of issues going unnoticed.

Star the Nightwatch.js repository ⭐

Speech-to-Text Tools 🗣️

Vosk

Vosk is an offline speech recognition toolkit that supports a wide variety of languages. It can be integrated into apps and used on mobile devices, servers, or embedded systems.

Key Features: Supports multiple languages, works offline, provides real-time transcription, and is lightweight with easy integration.

Why Do You Need It: Vosk allows you to add speech recognition to your web app without relying on internet connectivity. By providing speech-to-text capabilities, you’re making your app accessible to users who prefer voice interaction or those with mobility challenges.

Star the Vosk repository ⭐

Visualization and Reporting Tools 📊

Pa11y

Pa11y is your automated accessibility testing pal. It helps you check the compliance of your web apps against WCAG standards. It also offers automated reporting with detailed insights into issues that affect accessibility.

Key Features: Command-line interface, detailed reports, integration with CI/CD, and compatibility with popular browsers.

Why Do You Need It: Pa11y allows you to regularly audit your website for accessibility issues and ensure you’re meeting best practices. By addressing these issues early, you enhance the usability of your app for all users.

Star the Pa11y repository ⭐

Usability Testing Tools 🔍

Playwright

Playwright, developed by Microsoft, is an open-source framework that enables end-to-end testing of web applications across all modern browsers. It’s ideal for simulating real user interactions and performing usability tests across different environments.

Key Features: Cross-browser automation, mobile device emulation, integration with CI/CD pipelines, and screenshot/video capture.

Why Do You Need It: Playwright’s cross-browser support helps you ensure that your app is usable and performs consistently across various browsers and devices. You can script user flows to test and refine your app’s usability.

Star the Pa11y repository ⭐

Extra ressources 📖

A11y Project

The A11y Project is a community-driven initiative aimed at making web accessibility easier for developers. It serves as a comprehensive resource hub, providing valuable information, tools, and guidance on creating accessible websites.

Key Features: accessibility articles, checklists, links to helpful tools, guides for implementing web accessibility best practices

Why Do You Need It: The A11y Project is essential for developers who want to ensure their web applications meet accessibility standards. By using its resources, you can learn how to create more inclusive experiences, helping all users to engage with your content effectively.

Star the A11y project repository ⭐

You’re ready to make your web applications more inclusive! Focusing on accessibility opens your projects to more users and creates a welcoming space. Every small step you take helps everyone enjoy your work.

So go ahead, get creative, and make the web a better place for everyone!

Happy coding! 🚀

17 Must-know React Projects for Developers 👩‍💻 🔥

Anmol Baranwal — Wed, 16 Oct 2024 10:43:09 +0000

The react ecosystem is huge, thanks to the developer community.

Thousands of packages, libraries and frameworks make it so powerful.

Today, we are exploring 17 cool React projects that will be very useful for developers. I've also covered three awesome UI component libraries.

Let's jump in.

1. Tolgee - web-based localization platform.

Tolgee is an open source alternative to Crowdin, Phrase and Lokalise.

You can manage translations by using tolgee for translating texts, editing them in real-time and synchronizing them with your app.

Imagine you have a button in your app that says Submit. Instead of manually creating translations for Submit in different languages (like "Enviar" for Spanish), you add Tolgee to your app.

Instead of manually editing the large JSONs with lot of localization data, you can alt+click the button directly in your app and change its translation on the spot, without digging through code.

Get started with Tolgee React SDK by using this command.

npm i @tolgee/react

This is how you can use this.

// wrap your code with the tolgee provider

import { Tolgee, DevTools, TolgeeProvider, FormatSimple } from "@tolgee/react";

const tolgee = Tolgee()
  .use(DevTools())
  .use(FormatSimple())
  .init({
    language: 'en',
    apiUrl: process.env.VITE_APP_TOLGEE_API_URL,
    apiKey: process.env.VITE_APP_TOLGEE_API_KEY,
  });

...

<TolgeeProvider
  tolgee={tolgee}
  fallback="Loading..." // loading fallback
>
  <App />
</TolgeeProvider>

// Use the T component to translate your texts

import { T } from "@tolgee/react";

export const Component = () => {
  return (
    <h1>
      <T keyName="translate_me">Translate me!</T>
    </h1>
  )
}

Check this sample app using Tolgee React SDK.

You can read the docs about react integration. It supports all the other frameworks like Angular, Vue, Svelte, Vanilla JS and Nextjs.

There are lots of features like:

-→ In-context Translation : translate them directly in the app with the Tolgee i18n tool.

-→ One-click screenshots : Click once to take a screenshot from your app with highlighted phrases to translate.

Tolgee has 1.7k stars on GitHub and growing strong.

Star Tolgee ⭐️

2. Mantine Hooks - react hooks for state and UI management.

How many times have you been stuck in writing hooks from scratch?
Well, I'm never going to do it from now on thanks to mantine hooks!

It's not efficient to write more code since you would end up maintaining it later so it's better to use these production-level hooks to make your work a lot easier.

Trust me, getting 60+ hooks is a big deal considering they have a simple way for you to see the demo of each of the hooks with easy docs to follow.

Get started with the following npm command.

npm install @mantine/hooks

This is how you can use useScrollIntoView as part of mantine hooks.

import { useScrollIntoView } from '@mantine/hooks';
import { Button, Text, Group, Box } from '@mantine/core';

function Demo() {
  const { scrollIntoView, targetRef } = useScrollIntoView<HTMLDivElement>({
    offset: 60,
  });

  return (
    <Group justify="center">
      <Button
        onClick={() =>
          scrollIntoView({
            alignment: 'center',
          })
        }
      >
        Scroll to target
      </Button>
      <Box
        style={{
          width: '100%',
          height: '50vh',
          backgroundColor: 'var(--mantine-color-blue-light)',
        }}
      />
      <Text ref={targetRef}>Hello there</Text>
    </Group>
  );
}

They almost have everything from local storage to pagination, to scroll view, intersection, and even some very cool utilities like eye dropper and text selection. This is damn too helpful!

You can read the docs.

They have more than 26.4k+ stars on GitHub. It's not only for the hooks because Mantine is a component library for React.

Star Mantine Hooks ⭐️

3. Aceternity UI - copy paste components for your website.

After Shadcn was appreciated in the developer community, we saw a surge of new component-based libraries. To be honest, we don't need 100 new libraries, but some definitely stood out.

Aceternity UI is one of them where you can copy paste the most trending components and use them in your websites without having to worry about styling and animations.

You can explore all the components.

I will discuss the top 4 that I really loved. These are animated but you can get the idea based on how they look.

✅ Floating dock: Useful as navigation, it does a clean animation when I hover over any icon.

✅ Lamp Section Header: Useful for separating sections and has a smooth transition of expanding based on scroll.

✅ GitHub Globe: The globe can be dragged. This was originally used on the GitHub website if you are curious.

✅ Animated Tooltip: Useful for showcasing authority and trust. You can use it to show people or organizations you work with.

hovered over the second avatar

You will find code, installation instructions, a CLI guide and even the description of props that are used within the code.

One thing I really loved is that a lot of components are keeping things simple, no fancy over-kill type stuff. You can read the docs.

This is the only project on the list that is not open source but definitely worth checking out.

Visit Aceternity UI 🔥

4. xyflow - to build node-based UIs with React.

XYFlow is a powerful open source library for building node-based UIs with React or Svelte. It is a mono repo and provides React Flow & Svelte Flow. Let's see more on what we can do with React flow.

You can watch this video to understand React Flow in 60 seconds.

Some of the features are available in pro mode, but the ones in the free tier are more than enough to make a very interactive flow. React flow is written in TypeScript and tested with Cypress.

Get started with the following npm command.

npm install reactflow

Here's how you can create two nodes, Hello & World, connected by an edge. The nodes have predefined initial positions to prevent overlap and we are also applying styling to ensure sufficient space for rendering the graph.

import ReactFlow, { Controls, Background } from 'reactflow';
import 'reactflow/dist/style.css';

const edges = [{ id: '1-2', source: '1', target: '2' }];

const nodes = [
  {
    id: '1',
    data: { label: 'Hello' },
    position: { x: 0, y: 0 },
    type: 'input',
  },
  {
    id: '2',
    data: { label: 'World' },
    position: { x: 100, y: 100 },
  },
];

function Flow() {
  return (
    <div style={{ height: '100%' }}>
      <ReactFlow nodes={nodes} edges={edges}>
        <Background />
        <Controls />
      </ReactFlow>
    </div>
  );
}

export default Flow;

This is how it looks. You can also add a label, change the type and make it interactive.

You can read the docs and see example React Flow apps for Create React App, Next.js and Remix.

React Flow comes with several additional plugin components which can help you to make more advanced apps with the Background, Minimap, Controls, Panel, NodeToolbar and NodeResizer components.

For instance, you may have noticed dots in the background on many websites. You can simply use the Background component in React Flow to implement that pattern.

import { Background } from 'reactflow';

<Background color="#ccc" variant={'dots'} />  // this will be under React Flow component. Just an example.

In case, you're looking for a quick article, I recommend checking React Flow - A Library for Rendering Interactive Graphs by Webkid.

It has 25k+ stars on GitHub.

Star xyflow ⭐️

5. cmdk - Fast, unstyled command menu React component.

This is a command menu React component that can also be used as an accessible combobox. You render items, and it filters and sorts them automatically. ⌘K (project name) supports a fully composable API so you can wrap items in other components or even as static JSX.

Get started with the following npm command.

pnpm install cmdk

This is how you can use this in general.

import { Command } from 'cmdk'

const CommandMenu = () => {
  return (
    <Command label="Command Menu">
      <Command.Input />
      <Command.List>
        <Command.Empty>No results found.</Command.Empty>

        <Command.Group heading="Letters">
          <Command.Item>a</Command.Item>
          <Command.Item>b</Command.Item>
          <Command.Separator />
          <Command.Item>c</Command.Item>
        </Command.Group>

        <Command.Item>Apple</Command.Item>
      </Command.List>
    </Command>
  )
}

You can read the docs about parts and styling.

You can see how you can change it based on the styling you want.

raycast

linear

vercel

framer

You should see the list of all the examples and the FAQs which answers a lot of important questions.

It has almost 9.7k stars on GitHub.

Star cmdk ⭐️

6. Magic UI - UI library for design engineers.

Magic UI is another component based library where you can copy and paste them into your apps. It's more focused on creating landing pages and user-facing marketing materials.

You can view all the components. Let's see the top 4 that I really loved:

✅ Bento grid : You can use this layout to showcase the features. This has a smooth animation.

✅ Interactive icon cloud : An interactive 3D tag cloud component with icons. Could be useful to showcase the tech stack or tools you work with.

✅ Animated grid pattern : Grid blocks that appear and disappear to showcase smooth animation.

✅ Particles : A fun way to add some visual flair to your website.

They have a lot of useful components since everyone has a different preference based on what they need.

Other than this, they also provide sample templates like Portfolio. Check the live preview.

Magic UI has 10.2k stars on GitHub which just shows how popular they are.

Star Magic UI ⭐️

7. React Content Loader - SVG-powered component to easily create skeleton loadings.

I often visit websites and there is nothing there (blank page). I know it's loading since I'm a developer, but not everyone can realize it.

That is why skeleton loaders are important, they give users a visual signal that something is happening, especially for the loading state.

This project provides you with an SVG-powered component to easily create placeholder loadings (like Facebook's cards loading).

Skeletons are often used during the loading state to indicate to users that content is still loading. Every developer should use this handy project to improve the overall UX of the app.

A few things that make this one better!

✅ Lightweight - less than 2kB and 0 dependencies for the web version.

✅ Feel free to change the colors, speed, sizes, and even RTL.

✅ It supports React Native with the common API and powerful features.

Get started with the following npm command.

npm i react-content-loader --save

This is how you can use it.

import React from "react"
import ContentLoader from "react-content-loader"

const MyLoader = (props) => (
  <ContentLoader 
    speed={2}
    width={400}
    height={160}
    viewBox="0 0 400 160"
    backgroundColor="#f3f3f3"
    foregroundColor="#ecebeb"
    {...props}
  >
    <rect x="48" y="8" rx="3" ry="3" width="88" height="6" /> 
    <rect x="48" y="26" rx="3" ry="3" width="52" height="6" /> 
    <rect x="0" y="56" rx="3" ry="3" width="410" height="6" /> 
    <rect x="0" y="72" rx="3" ry="3" width="380" height="6" /> 
    <rect x="0" y="88" rx="3" ry="3" width="178" height="6" /> 
    <circle cx="20" cy="20" r="20" />
  </ContentLoader>
)

export default MyLoader

The output of this is shown below.

You can even drag the individual skeleton or use pre-defined made for different socials like Facebook, and Instagram.

You can read the docs and see the demo.

The project has 13.7k+ stars on GitHub and is used by 50k+ developers on GitHub.

Star React Content Loader ⭐️

8. Tremor - React components to build charts and dashboards.

Tremor provides 20+ open source React components to build charts and dashboards built on top of Tailwind CSS to make visualizing data simple again.

Get started with the following npm command.

npm i @tremor/react

This is how you can use Tremor to build things quickly.

import { Card, ProgressBar } from '@tremor/react';

export default function Example() {
  return (
    <Card className="mx-auto max-w-md">
      <h4 className="text-tremor-default text-tremor-content dark:text-dark-tremor-content">
        Sales
      </h4>
      <p className="text-tremor-metric font-semibold text-tremor-content-strong dark:text-dark-tremor-content-strong">
        $71,465
      </p>
      <p className="mt-4 flex items-center justify-between text-tremor-default text-tremor-content dark:text-dark-tremor-content">
        <span>32% of annual target</span>
        <span>$225,000</span>
      </p>
      <ProgressBar value={32} className="mt-2" />
    </Card>
  );
}

This will be generated based on the above code.

You can read the docs. Between, they use remix icons under the hood.

From the variety of components that I've seen, it's a good starting point. Trust me!

Tremor also provides a clean UI kit. How cool is that!

If you're looking for an alternative, you can check out Shadcn charts which are based on recharts.

Tremor has 16k+ stars on GitHub.

Star Tremor ⭐️

9. Victory - React components for building interactive data visualizations.

A lot of developers work on a lot of data these days (mostly using APIs). A method to easily visualize that data is a cool concept to take your app to the next level.

Victory is an ecosystem of composable React components for building interactive data visualizations.

Get started with the following npm command.

npm i --save victory

This is how you can use this.

<VictoryChart
  domainPadding={{ x: 20 }}
>
  <VictoryHistogram
    style={{
      data: { fill: "#c43a31" }
    }}
    data={sampleHistogramDateData}
    bins={[
      new Date(2020, 1, 1),
      new Date(2020, 4, 1),
      new Date(2020, 8, 1),
      new Date(2020, 11, 1)
    ]}
  />
</VictoryChart>

This is how it's rendered. They also offer animations and theme options, which are generally useful.

You can read the docs and follow the tutorial to get started. They provide around 15 different chart options and an insane customization under each of them, it's almost unbelievable!

It's also available for React Native (docs). Check FAQs if you want solutions to common problems with code and explanation such as styling, annotation (labels), handling axes.

Victory has 11k stars on GitHub.

Star Victory ⭐️

10. React Diagrams - a super simple, no-nonsense diagramming library written in React.

A flow & process orientated diagramming library inspired by Blender, Labview and Unreal engine.

Get started with the following npm command. You will then find a dist folder that contains all the minified and production ready code.

yarn add @projectstorm/react-diagrams

Let's see how we can use it.

import createEngine, { 
    DefaultLinkModel, 
    DefaultNodeModel,
    DiagramModel 
} from '@projectstorm/react-diagrams';

import {
    CanvasWidget
} from '@projectstorm/react-canvas-core';

We need to call createEngine which will bootstrap a DiagramEngine for us that contains all the default setups.

// create an instance of the engine with all the defaults
const engine = createEngine();

// creating two nodes
// node 1
const node1 = new DefaultNodeModel({
    name: 'Node 1',
    color: 'rgb(0,192,255)',
});
node1.setPosition(100, 100);
let port1 = node1.addOutPort('Out');

// node 2
const node2 = new DefaultNodeModel({
    name: 'Node 1',
    color: 'rgb(0,192,255)',
});
node2.setPosition(100, 100);
let port2 = node2.addOutPort('Out');

//we link the two ports of both of the nodes
// also add a label to the link
const link = port1.link<DefaultLinkModel>(port2);
link.addLabel('Hello World!');

We need to create a DiagramModel to contain everything, add all the elements to it and then add it to the engine.

const model = new DiagramModel();
model.addAll(node1, node2, link);
engine.setModel(model);

// we just need to render in react
<CanvasWidget engine={engine} />

You can read the docs and check the live demo.

The inspiration for this library is Joint JS (a fantastic library) and the need for rich HTML nodes, LabView, Blender Composite sub-system.

You can also find detailed info on how to make custom nodes and custom ports on the docs.

It has 8.7k stars on GitHub.

Star React Diagrams ⭐️

11. UI Layout - design that your website needs.

This is the third component-based library that I'm discussing apart from Acernity UI and Magic UI.

This is also a collection of reusable components, each with a bunch of examples in different styles.

You can see the list of all components. Let's cover the top 5 that I really loved.

✅ Video Masking : Creative video masking with various shapes, adding unique and artistic effects to images through custom cutouts. This looks insane!

✅ Blur Vignette : Apple Vision Pro like Blur Effect to use it in images, videos and cards. The background is a playing video.

✅ Noise effect : A noise effect component that adds a noise overlay to your website, with adjustable opacity for control.

✅ Spotlight Cards : a mouse-sensitive spotlight effect that highlights the border of the div or section as you move your cursor.

✅ Masonary Grid : An adaptive masonry grid component that arranges items in a dynamic, variable-height layout, similar to Unsplash.

If you need a structure for custom Talwind UI blocks (interested in coding from scratch), then I recommend checking out flowrift and flash UI.

UI Layout has 356 stars on GitHub and is definitely valuable for someone focusing on interface design.

Star UI Layout ⭐️

12. React Cosmos - Sandbox for developing and testing UI components in isolation.

React Cosmos is a powerful tool for developing and testing UI components in isolation. It allows you to focus on one component at a time, resulting in faster iteration and higher-quality components.

You can install it using this npm command for a nextjs project. You can also use it with Vite, React native or even a custom bundler.

npm i -D react-cosmos react-cosmos-next

It has all the features to make it a standard.

You can read the docs and check the live demo.

They have 8.3k stars on GitHub.

Star React Cosmos ⭐️

13. React Joyride - create guided tours in your apps.

Tours can be an excellent way to showcase your app to new users or explain the functionality of new features. It improves the user experience and can create a personalized touch.

Get started with the following npm command.

npm i react-joyride

This is how you can use it.

import React, { useState } from 'react';
import Joyride from 'react-joyride';

/*
 * If your steps are not dynamic you can use a simple array.
 * Otherwise you can set it as a state inside your component.
 */
const steps = [
  {
    target: '.my-first-step',
    content: 'This is my awesome feature!',
  },
  {
    target: '.my-other-step',
    content: 'This another awesome feature!',
  },
];

export default function App() {
  // If you want to delay the tour initialization you can use the `run` prop
  return (
    <div>
      <Joyride steps={steps} />
      ...
    </div>
  );
}

They also provide a list of components and an easy way to customize the default user interface.

You can read the docs and see the demo. You can also play with the live codesandbox.

They have 6.8k+ stars on GitHub and have more than 250k weekly downloads on the npm package.

Star React Joyride ⭐️

14. React Spring - spring physics based React animation library.

If you like react-motion but feel like your transitions aren’t smooth, it’s because it’s exclusively using React rendering.

If you like Popmotion but feel like you are limited by what you can do, it’s because it entirely skips React rendering.

react-spring gives both options, try it!

Get started with the following npm command.

npm i @react-spring/web

This is how you can import a higher-order component to wrap things up for animations.

import { animated } from '@react-spring/web'

// use it.
export default function MyComponent() {
  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        background: '#ff6d6d',
        borderRadius: 8,
      }}
    />
  )
}

I decided to try React Spring because of the below codesandbox. It's amazing how many things can we do with React Spring.

You can read the docs.

They also provide a lot of examples that you can learn from.

It provides an insane amount of options, such as useScroll, which allows you to create scroll-linked animations.

For instance, this codesandbox tells the usage of useScroll.

React Spring has around 28.1k stars on GitHub.

Star React Spring ⭐️

15. BlockNote - block-based rich text editor (Notion style) and extensible.

It's often said not to reinvent the wheel unless you're learning something new.

Blocknote is the open source react rich text editor. You can easily add a modern text editing experience to your app. Built on top of Prosemirror and Tiptap.

They have a lot of features as shown below.

You can easily customize the built-in UI Components, or create your custom Blocks, inline content and styles. If you want to go even further, you can extend the core editor with additional Prosemirror or TipTap plugins.

Other libraries are powerful but often have quite a steep learning curve and require you to customize every single detail of your editor. BlockNote instead, offers a great experience with minimal setup, including a ready-made and animated UI.

Get started with the following npm command.

npm install @blocknote/core @blocknote/react

This is how you can use this. With the useCreateBlockNote hook, we can create a new editor instance and then use the theBlockNoteView component to render it.

@blocknote/react/style.css is also imported to add default styling for the editor and the Inter font that BlockNote exports (optional).

import "@blocknote/core/fonts/inter.css";
import { BlockNoteView, useCreateBlockNote } from "@blocknote/react";
import "@blocknote/react/style.css";

export default function App() {
  // Creates a new editor instance.
  const editor = useCreateBlockNote();

  // Renders the editor instance using a React component.
  return <BlockNoteView editor={editor} />;
}

You can read the docs and the ui components that are available.

You should give it a try, especially because it includes a wide range of features like a 'slash' menu, smooth animations and the potential to create a real-time collaboration app.

slash menu

realtime collab

format menu

They have also provided 20+ examples with the preview and code.

Blocknote has 6.5k stars on GitHub.

Star BlockNote ⭐️

16. Remotion - make videos using React.

Create real MP4 videos using React and scale your video production using server-side rendering and parametrization.

If you've seen GitHub wrapped for the last 2 years, it was made by the Remotion team.

Get started with the following command.

npx create-video@latest

It gives you a frame number and a blank canvas where you can render anything you want using React.

This is an example React component that renders the current frame as text.

import { AbsoluteFill, useCurrentFrame } from "remotion";
 
export const MyComposition = () => {
  const frame = useCurrentFrame();
 
  return (
    <AbsoluteFill
      style={{
        justifyContent: "center",
        alignItems: "center",
        fontSize: 100,
        backgroundColor: "white",
      }}
    >
      The current frame is {frame}.
    </AbsoluteFill>
  );
};

You can read the docs including the fundamentals.

Check the list of resources including templates, SAAS Starter kits, effects, examples and even full projects.

Also, check demo videos created during products and campaigns.

For instance, this was created with Remotion. Watch this!

You can watch the tutorial demo of Remotion by Fireship, their videos are just damn awesome :)

They have 20.5k stars on GitHub and are used by 2k+ developers.

Star Remotion ⭐️

17. MDX - Markdown for the component era.

MDX allows you to use JSX in your markdown content. You can import components, such as interactive charts or alerts and embed them within your content.

In simple words, MDX can be explained as a format that combines markdown with JSX and looks as follows:

# Hello, world!

<div className="note">
  > Some notable things in a block quote!
</div>

The heading and block quote are markdown, while those HTML-like tags are JSX. MDX supports JavaScript expressions inside curly braces and also supports import/export statements as well. See the list of all components.

You can read the docs which explains the core concepts of MDX. Also, check playground if you're interested in the live demo.

MDX has 17k stars on GitHub and is used by 390k+ devs on GitHub.

Star MDX ⭐️

These react libraries can improve your game as a developer.

Some can save hundreds of hours while others on this list can help you improve user experience. That's it for now.

Have a great day! Till next time.

If you loved this, please follow me for more :)

Follow Tolgee for more content like this.

Tolgee Follow

Tolgee is an open-source developer tool for web apps localization 🐁

8 Open-Source Tools to grow your app and reach new markets! 🔥

Marketa Cizmar — Sat, 12 Oct 2024 06:44:53 +0000

Expanding your app into new markets can feel daunting, but it doesn’t have to be! With the right tools at your fingertips, you can streamline processes, engage users, and gain valuable insights—all while keeping things affordable and accessible. Let’s explore eight fantastic open-source tools that can help you localize your app, connect with your audience, and ultimately grow your user base across the globe.

1. Tolgee (Localization)

Tolgee is an open-source tool that simplifies the localization process for developers. It offers in-context translations, automatic screenshots, and easy integration with existing apps, helping you break into international markets quickly.

Key Features: In-context translation, automatic screenshots, multi-language support, autonomous localization
Why You Need It: Great for expanding your app to non-English-speaking regions efficiently

Star the Tolgee repository ⭐

2. Unleash (Feature Flags & Segmentation)

Unleash is an open-source feature flag management tool that enables developers to launch new features to specific audiences, regions, or user segments. It lets you experiment with market-specific features, helping you optimize your app for different regions before a full-scale launch.

Key Features: Progressive rollout, segmentation, A/B testing
Why You Need It: Experiment with different markets or features without redeploying code

Star the Unleash repository ⭐

3. Discourse (Community Building & Engagement)

Discourse is a modern open-source discussion platform designed to create engaging and interactive communities. It provides features like threaded conversations, user profiles, and notifications to foster discussion and engagement.

Key Features: Real-time discussions, mobile-friendly design, extensive plugin ecosystem.
Why You Need It: Ideal for building forums and communities with rich interaction, making it easier to engage users across different markets.

Star the Discourse repository ⭐

4. Matomo (Privacy-Focused Analytics)

Matomo is a widely used open-source web analytics platform that provides detailed insights while giving you complete control over your data. It is highly customizable and can be self-hosted.

Key Features: Full data ownership, customizable dashboards, heatmaps, and session recordings.
Why You Need It: Offers valuable insights without compromising user privacy, making it suitable for regions with strict privacy laws.

Star the Matomo repository ⭐

5. Glific (Localized Chatbots)

Glific is an open-source, two-way communication platform designed to help organizations engage with users via WhatsApp and other messaging platforms. It allows for multilingual interactions, making it ideal for developers looking to reach users in regions where mobile messaging apps are the primary means of communication.

Key Features: WhatsApp integration, multilingual chatbots, real-time analytics.
Why You Need It: Engage with users in emerging markets where messaging apps dominate, boosting engagement and conversions.

Star the Glific repository ⭐

6. Budibase (Development Tool)

Budibase is an open-source low-code platform that enables rapid development of internal tools, dashboards, and applications. Its intuitive interface allows teams to quickly create market-specific solutions with minimal coding, making it ideal for adapting to local user needs.

Description: An open-source low-code platform for building internal tools, dashboards, and applications quickly.
Why You Need It: Rapidly create market-specific tools or applications tailored to local user requirements without extensive coding.

Star the Budibase repository ⭐

7. Mautic (Social media & marketing)

Mautic is an open-source marketing automation platform that streamlines email campaign management and user interactions. It allows businesses to tailor campaigns for specific regions and languages, enhancing user acquisition and engagement in diverse markets.

Description: An open-source marketing automation platform that helps manage email campaigns and user interactions.
Why You Need It: Tailor marketing campaigns to specific regions and languages, enhancing user acquisition efforts.

Star the Mautic repository ⭐

8. Pimcore (Digital Asset Management)

Pimcore is an open-source digital experience platform that combines product information management (PIM), digital asset management (DAM), and content management (CMS).

Key Features: Centralized content management, multi-channel publishing, multi-language support.
Why You Need It: Manage and distribute digital assets and product information for different markets efficiently.

Star the Pimcore repository ⭐

I easily translated my React.js applications into multiple languages. Here is how... 🤯

Jan Cizmar — Mon, 23 Sep 2024 13:35:30 +0000

Translating an App to multiple languages (localization) is tricky part of many applications.

Tolgee is simplifying the localization process and saves developer's time by removing repetitive tasks 🔁 ❌

Saving time? That's what I want. Show me how to localize my React app!

What is Tolgee

Tolgee is an open-source i18n tool combining localization platform and SDKs to provide simple way to translate the web applications for both developers and translators.

Tolgee is not just another software localization platform offering integrations that only syncs local data with the backend. Instead, Tolgee is truly integrated into your app via SDKs.

In context translating 📖

As a developer of localized application, you probably have to modify localization data every time you need to change a text.

So you have to open the file, add or find the key to modify, save it and check whether everything was changed correctly in the app.

With Tolgee you can just ALT + click the actual translated text in your app and 💥boom💥 translation dialog appears and you are able to translate it right away.

Automatic Screenshot Generation 📸

Another tricky part of localization is providing context to translators. Only exporting the keys and translations in source language is not always enough.

Tolgee enables you to take and upload screenshot directly in the in-context translation dialog. So no more manual taking and uploading screenshots.

Localization platform included ✅

Tolgee is also localization platform, where you can manage all your localization strings. You can provide access to translators and they can translate the texts there.

If you have uploaded screenshots before, they know the context of the translations perfectly and can produce perfect results.

Isn't that hard to integrate? No it's not!

To get started, you can simply follow the integration guides provided in the platform.

Login to Tolgee Cloud or use your self hosted Tolgee instance.
Create a new project by clicking Add button in the top right. Fill the project name.

Optionally, you can add multiple languages to translate your app into.
Select Integrate from side menu, choose React (Vite) and generate an API key with all scopes checked.

Success! 🎉 Now you just have to follow the integration guide.

Let's integrate it into React App

Generate brand new React App and open it your favorite editor

npm create vite@latest tolgee-hello-world -- --template react-ts
# follow the vite guide

Install Tolgee packages ⬇️
```
npm install @tolgee/react
```
Add Tolgee properties to you development .env file env.development.local by copying it from the integration guide
```
VITE_APP_TOLGEE_API_URL=https://app.tolgee.io
VITE_APP_TOLGEE_API_KEY=<your API key>
```
Wrap your App component in main.tsx with TolgeeProvider component. Again, you can copy it from the integration guide.

Go to App.tsx and replace all the crap with simple "Hello world!" message.

import './App.css';

function App() {
  return (
    <div className="App">
      <h1>Hello world!</h1>
    </div>
  );
}

export default App;

Wrap the "Hello world!" with <T> component and add keyName prop.

import './App.css';
import { T } from '@tolgee/react';

function App() {
  return (
    <div className="App">
      <h1>
        <T keyName="hello_world">Hello world!</T>
      </h1>
    </div>
  );
}

export default App;

Let's run the App in the browser and see the magic! 🪄

Hold your ALT key and move your mouse over the text. It should be highlighted.
When you click it, dialog opens and you're able to edit the text or generate screenshots.

After you hit the update button, your Hello World! text will be immediately changed to the new value!

Congratulations! You're done! 🎉🎉🎉

Now you are able to translate your React applications. To learn more about Tolgee or to find out how to translate more complicated cases, visit our docs.

Tolgee - Developer friendly localization tool

Tolgee helps teams localize apps effortlessly. We make translation simple with real-time updates and easy integration into your workflow.

Say goodbye to complex file management and focus on building great products. Fast, smooth, and built for devs.

If you like this tutorial, please help us with a star. It would help us to create more articles like this 💖

Star the Tolgee repository ⭐

Overriding dependency version in Spring Boot

Jan Cizmar — Sat, 14 Oct 2023 13:58:50 +0000

Do you know that feeling when you spend hours trying to do something without any luck and then you find out that the solution could not be easier? Well, that just happened to me. I was trying to upgrade the Hibernate version in our Spring boot app.

What doesn't work

I tried to exclude the dependency from spring boot and include the desired one the standard gradle way. With no luck...

    implementation ("org.springframework.boot:spring-boot-starter-data-jpa"){
        exclude group: 'org.hibernate.orm', module: 'hibernate-core'
        exclude group: "org.hibernate.orm", module: "hibernate-jpamodelgen"
    }
    implementation "org.hibernate:hibernate-core:$hibernateVersion"

After hours of trying to diagnose why I always got the version included in Spring Boot, I found out that there is the Spring Boot dependency management plugin. That's the plugin which handles all the spring boot versions and enforces the versions defined by spring boot.

What works

Fortunately, there is a way to override the version. And it's super easy.

You just need to specify the version in your build.gradle.

ext['<dependency>.version'] = '6.0.9'

or using properties.gradle:

spring-framework.version=6.0.9

as stated here in the Spring docs.

And voilà! It works! You can find the list of the version properties you can override here.

Hope this helps future travelers who will struggle with the same.

Thanks for reading, and please consider using and staring Tolgee platform on GitHub ⭐️ - a tool healing your localization pain.

i18n and i18next: What's the difference?

Marketa Cizmar — Tue, 24 Jan 2023 12:45:39 +0000

For many, this question has a pretty clear answer, but people, who are new to software development or who started to use i18next as the first choice, can be mistaken. So let's make it clear!

What is i18n?

The better question would be "What does i18n stands for". i18n is the abbreviation of the word internationalization, where the " 18" stands for the number of letters between the first i and the last n.

What is internationalization?

It's the process of designing the software application so that it can be adapted to various languages and regions. What does it mean? It means that when you are using some i18n/localization library or if you have your application prepared to be translated to different languages, you are doing internationalization. Yay! 🎉

What is i18next?

i18next is an internationalization framework written in and for JavaScript. It's a library you integrate into your application code. i18next helps you to render different strings for users speaking different languages.

So what is the difference?

i18n is an abbreviation that is used across all the programming languages and software development world. i18next is a JS framework/set of libraries.

i18next is not a standard

Although i18next is currently used by many developers, it's not a standard. It has a nice catchy name and if you google i18n, you can get the i18next website as a first result, but there are plenty of other libraries for JavaScript you can use. Here are some of them:

FormatJS

react-intl (a react i18n library from FormatJS family)

Tolgee JS (Our integrations)

Typesafe-i18n

i18next is not the only solution out there. Different solutions suit different needs.

TL;DR

i18n is the abbreviation for internationalization
i18next is a JavaScript framework enabling internationalization

How to remove Java from JavaScript

Štěpán Granát — Mon, 24 Oct 2022 08:57:13 +0000

As a React developer, I have a suspicion to JS classes usage. In React bubble, it feels like a bad practice when I see them somewhere.

However, recently I got a task to rewrite our @tolgee/core, which is VanillaJS, and so far, there have been classes everywhere. I somehow felt it is not right. But then I realized that I don't actually know how to replace classes outside of React. Hmm ...

Wait, what's wrong with the classes?

Classes are basically added syntax sugar which gives you the impression that you are working with a class based programming language when you are actually not. Classes in JavaScript are implemented differently from the others. My main complaints are these:

How this works is a cause of many issues, and correctly understanding it is not easy
Inheritance is becoming an outdated concept, and classes encourage you to use it
Private fields in classes are not supported everywhere yet, and their syntax is weird (and Typescript private fields are not really private)
Class instances don't play well with desctructuring assignment

Classes in JavaScript tried to bring it closer to traditional OO languages, but it didn't go all the way. So if you are used to OOP, you won't get a very good experience, and it will feel like JS is crappy language. But it doesn't have to be this way.

Like a fish out of water

In React, you don't need classes and even when you use external libraries, they usually don't require you to write classes. So it's easy to say, "classes are not necessary, just write functions" however, the second you step outside the React ecosystem, it's different.

As I realized this, it got me thinking: Why is that? How comes, that with React classes are not necessary?

State and lifecycle

If you write a complex system, you need a way how to store your state somewhere. React has a way how to treat the state in your components, and it provides you with a lifecycle, which defines when the internal state is created, modified, and destroyed. Notice that it's very similar to class instances. In a way, React component is conceptually very similar to a class as it gives you a frame where your code lives, and you can "hook" into its lifecycle.

I think that's what I'm missing, that's why it's not easy to replace classes in our core.

Classes without classes

So I have a justification for classes, but that would mean I have to live with their shortcomings. Do I need to use class, this, extends, and new like Java programmer? It somehow feels bad. I like the world of simple objects and simple functions. I like the simple world.

Let's try to "emulate" classes as React does.

One way is to separate methods from data. This is often used in languages that don't support classes (e.g. C).

// equivalent of constructor
function createCar(color) {
  return {
    color,
  };
}

// equivalent of methods
function setCarColor(car, color) {
  car.color = color;
}

This method works, but it has even more disadvantages than classes as it doesn't encapsulate the data. It neither supports inheritance nor provides any nice way to replace it. All the data are exposed outside, meaning anyone can modify anything without your knowledge. The lifecycle is not enforced, it's just convention.

Closure objects

I've come across a lecture from David Crockford, where he recommends using closure instead of class.

By far, the worst new feature in es6 is class. This one was strongly recommended by all the Java guys who have to write in JavaScript now and who don't want to learn a new language. This gives them the illusion of writing in a language that they think they already know.

-- David Crockford

If you look at it, it kind of reminds the definition of a React component.

function Car(color) {
  const state = {
    color,
  };

  function setColor(color) {
    state.color = color;
  }

  return Object.freeze({
    setColor,
  });
}

The principle of this is that you create a higher-order function that wraps your methods and state variables. This function serves as your constructor. Its content is inaccessible from outside by definition. Then you just return what you want to be publicly available in an object which is the only gate to your data. It nicely forces you to create getters and setters for everything.

Even though this object represents the "instance", the data are not stored directly in it, so we can freeze it with Object.freeze. Data are actually stored in the constructor closure, and in the instance, we only "leak" functions that we want to be public.

How about inheritance?

Instead of traditional inheritance, you can use composition here, as you can call any other constructors, and combine their methods in your new object.

function Car(color) {

  ...

  const { setSpeed } = Vehicle();

  return Object.freeze({
    setColor,
    setSpeed,
  });
}

I've always found class inheritance confusing, and this way is much more readable for me. It's also quite similar to how React allows you to compose hooks, so it feels familiar.

Even though I haven't seen this method used in many places, it feels quite natural to me. I like how I see exactly what is passed where. It also brings an advantage in code optimization as private methods are truly private (unlike Typescript private methods), so the optimizer can optimize them accordingly.

One simple advantage is that you can safely use the desctructuring assignment here, as we won't run into issues with binding and prototype chain.

// this is perfectly ok
const { setColor } = Car(...)

Seems good. What's the catch?

No catch, except ...

Usage with typescript is not as smooth as with classes. With classes Typescript knows how to work with them and
so if you create class Car you can then use type Car as an type annotation for it's instance. This is not possible
with functions. It is possible to infer type, but we need to be more explicit.

let car: ReturnType<typeof Car>;

Over time I've started using a convention that with every constructor I also export the type of the instance like this:

export function Car(...) {
  ...
}
export type CarInstance = ReturnType<typeof Car>

For some reason, Typescript has a major issue with recursion in objects. It breaks this system if you want to return the instance itself in any method (which is quite common practice for chainable objects).

export function Car(...) {
  const car = Object.freeze({
    ...
    addWheel: (...) => {
      ...
      return car
    }
  })
  return car
}

export type CarInstance = ReturnType<typeof Car>

If you build this file into Car.d.ts with tsc compiler (v4.8.4), it will produce something like this:

export declare function Car(...): Readonly<{
  addWheel: (...) => Readonly<any>;
}>;

export declare type Instance = ReturnType<typeof Tolgee>;

Notice that the recursive function type is reduced to any, which is quite sad. I couldn't find any way around this, only to type the function explicitly, which is not ideal, but in my usecase still acceptable. Let's hope it will get better in future Typescript versions. If influential people will pull the strings, maybe we'll get some improvement.

// Detect dark theme var iframe = document.getElementById('tweet-1579319192729186304-731'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1579319192729186304&theme=dark" }

The Typescript drawbacks are quite significant, however for my usecase they are still outweight by drawbacks of classes and their "inappropriateness" in JavaScript.

Conventions

I've quite naturally started using capitalized function names for the constructors. I've seen different approaches with make or create prefixes, but I like the simplicity better.

There is also no clear name for this whole convention, I've seen it called Crockford objects or Crockford classes, but I would prefer "Closure objects", so the name has some reference to its meaning.

Conclusion

Python enthusiasts use the word "pythonic" for constructions that feel natural to them. I would call this "javascriptic" if that would be a term, but even if it's not, I think you know what I mean.

PS: Check Tolgee.io and give us github stars

Original article was published on our blog.

Tolgee: i18n revolution for modern JS frameworks; And it is open-source

Jan Cizmar — Mon, 19 Sep 2022 10:44:12 +0000

Hi all,

I am Jan from Tolgee. A few years ago I had an idea to create a tool that enables me and my team to simplify the localization/i18n process and enable non-programmers to modify localization strings without Git knowledge and anything. I started to develop the project and now, a few years after, we have a production-ready working solution. So let me explain what it does and why you should consider using it.

What is internationalization/localization/i18n/l10n?

Basically, if you're using some i18n library, enabling you to translate strings (like button labels, page titles, etc.) in your app to different human languages, you are doing internationalization. If you are actually translating the strings or preparing your app for usage in a specific region, you are doing localization. The i18n / l10n are just abbreviations for these two terms, where 18 and 10 mean the number of characters omitted in the word.

(simplified explanation)

What's Tolgee?

Tolgee is a localization platform that also provides its own integration libraries. It provides many great features making the app localization a piece of cake.

There are many i18n libraries out there. Why should I use Tolgee?

Tolgee can do a lot more than just traditional i18n library. It doesn't only provide the different strings for different languages, but it also enables you to change the strings directly in the app you are currently working on. It also allows others to translate/modify/fix strings in your app. Even your grandma, your aunt, or your Armenian friend from studies abroad.

It is also a localization platform, where you can translate your strings, while it suggests results from various third-party translators like Google Translator or DeepL.

It also enables developers to provide screenshots from the app in one click, so translators know the context and don't provide wrong translations. Which happens a lot btw.

And much more...

Why there are wrong translations on the Internet?

In most cases, it's because translators don't know the context of what they're translating. They see just the source string, but they don't see what's around it. So they have to guess the context, which leads to extremely wrong results. Let me explain with an example.

I am a Czech native speaker so I am using Netflix App translated to Czech. Once I opened the login page of the app. There was a password field and on the right side of the field there was a button labeled "POŘAD" which translated from Czech back to English means "TV SHOW". The designers of the app definitely didn't label their password showing the button "TV SHOW", they labeled it "SHOW". But the translators didn't know that they were translating a button for showing a password. They saw just the string "SHOW" and they were translating the Netflix app, so they guessed. And they guessed wrong.

There are many occurrences of wrong translations like this and the only way how to avoid this is to provide the context to your translators. But taking a screenshot or providing a text description to each label can be annoying.

How does Tolgee help me to have my app perfectly translated?

The operation of providing context has to be easy. Otherwise, developers won't do it. That's why Tolgee enables you to provide a screenshot with a highlighted string to translate with a single click. In the same dialog, where you can modify your localization strings, you can let Tolgee automatically take the screenshot from your App and highlight the string to be translated. This operation takes less than a few seconds. So the developers won't be annoyed by that.

How does it help developers? (The ALT+click magic)

There are various dev Tools for various things. You have React Dev tools, there are Angular dev tools, there are dev tools for state management libraries, etc. Tolgee brings dev tools for localization. When you click a translation string in your app with the ALT key, Tolgee dev tools open and you can translate your string. You never have to edit a .json/.po or other localization data files. The only thing you have to do is ALT + Click the string.

Cool. But how does it work?

In the development mode of the App, the strings are fetched from Tolgee API. If you modify the string or add a new key, the key is saved in the Tolgee Platform. So in development mode, you are working with remote data. That's basically it.

So my App relies on Tolgee Servers?

No! For the production build, you can export the translations from the API and store them as a static asset. So your app doesn't fetch anything from Tolgee API when it's used in the production environment.

So I have to export the string from Tolgee every time I change a string?

No! You can do that automatically in the CI/CD pipeline when your app is built. Or whenever you wish. We are also working on Tolgee CLI, which will help you with tasks like this.

My mama speaks Spanish. Can she translate the strings when my app is deployed?

Yes! She can use (the Tolgee Tools Chrome plugin)[https://chrome.google.com/webstore/detail/tolgee-tools/hacnbapajkkfohnonhbmegojnddagfnj] to enable the dev tools also in deployed App. Then she can translate it directly in the app.

What frameworks are supported?

Tolgee has integrations for React, Angular, Vue, Svelte, Next.js, Gatsby, and others. Learn more here.

How long does it take to integrate?

The integration is very fast! You can do it in seconds. It doesn't take longer than other libraries. There are integration guides in the docs and also in the platform. If you get lost you can just contact us via chat on our website or via our community Slack channel.

Does it work with SSR?

Yes. There are guides in the docs on how to make it work with popular SSR frameworks.

Can I self-host the platform?

Yes. It's open source and you can self-host the platform. Just follow the docs.

I am using i18next I don't want to migrate

No problem. Tolgee has also SDK for i18next. So you can use it with it. Here are the docs.

Typescript?

The @tolgee/core and all the JS integrations are written in Typescript so the API is typed. You don't have to install @types/.... The types are provided with the npm packages. We also plan to provide type-safety for the translation keys, similar to typesafe-i18n, in the future.

What technologies are used?

For the platform, we use Kotlin/SpringBoot on the backend and Typescript/React on the front end. For the integrations, we use Typescript if we can.

Nice. So what do you want?

It would be nice if you try Tolgee and give us some feedback. Also, we would be pretty happy to get some GitHub stars from you.

Thanks for reading!

Let this script type instead of you when you record a video of your browser ⌨

Jan Cizmar — Wed, 07 Sep 2022 12:29:37 +0000

I was working on cool gifs for Tolgee's new readme, where we show how simply you can modify a localization string in your App. But when I need to type something into input, I always make like 5 mistakes and my typing is not very nice to look at. So I created a script that types the string instead of me when I hit a specific shortcut. Now I use this to record videos, where I have to fill in some input, and I don't want to record it like 1000 times because I was typing inconsistently.

It can be useful for some pranks if you extend this. But let's leave this to your imagination.

How does it work?

So how does it work? It takes the array of strings. When I hit ctrl + h for the first time, it iterates over characters in the first string and modifies the value of the currently focused input by adding the current character. It waits 30ms between every character addition. When I hit the shortcut a second time, it does the same thing with the second string.

React issue

When you just modify the value property of an input element, React doesn't trigger your onChange listener and so the value is not changed, since React state is not updated. To trigger the onChange event listener you have to also dispatch input and do some other stuff you can read
about [here (https://stackoverflow.com/questions/30683628/react-js-setting-value-of-input/52486921#52486921).

The script

The script (I call it typescript 😄):

(() => {
  const strs = ["This is text...", "This is another text."];
  let hits = 0;
  window.onkeyup = async (event) => {
    if (event.ctrlKey && event.key === "h") {
      const input = document.activeElement;
      for (const char of strs[hits]) {
        if (input.value !== undefined) {
          setNativeValue(input, input.value + char)
        }
        await new Promise((resolve) => setTimeout(resolve, 30))
      }
      hits++;
    }
  }

  // Boring part starts here
  // It makes it working with react.js apps
  function setNativeValue(element, value) {
    let lastValue = element.value;
    element.value = value;
    let event = new Event("input", {target: element, bubbles: true});
    // React 15
    event.simulated = true;
    // React 16
    let tracker = element._valueTracker;
    if (tracker) {
      tracker.setValue(lastValue);
    }
    element.dispatchEvent(event);
  }
})()

How to use it

Copy the script and modify the strings to be typed
Copy the modified script
Go to the console of developer tools in your browser and paste the script
Hit enter
Focus an input and hit ctrl + h
Your text is being typed

Tolgee is an open-source solution for software localization i18n. Translate your applications and save up to 90% of time needed for localization! Tolgee.io

Star our GitHub repository [tolgee/tolgee-platform (https://github.com/tolgee/tolgee-platform) ⭐⭐⭐!

Forem: Tolgee

Go Global or Die Trying (A Guide on How Not to Actually Die Trying)

Localization Nightmare

At What Point Should You Even Start Localizing?

Excel at code, not at Excel

Key Features That Will Save Your Sanity

What are the options?

Conclusion

Building a Kanban Board with Next.js,Vercel AI and Tolgee

TL;DR

Setting up the Project 🛠️

Initializing a Next.js Application

Installing Dependencies

Setting Up UI Components

Setting up the Database Model 📦

Initializing Prisma

Defining the Prisma Schema

Setting up a Database Locally with Docker 🐳

Setting up Tolgee for Localization 🗣️

Setting up Authentication 🛡️

Zod Schema for Validation

NextAuth Configuration

User Registration API

Middleware for Route Protection

Build Navbar Component

LangSelector Component

LogoutBtn Component

Navbar Component

Build Authentication Pages

Login Component

Login Page Route

Register Component

Register Page Route

Setup WebSocket and QueryClient Provider

getSocket Function

Socket Provider

QueryClient and SocketProvider

Wrap the Application Layout with the Providers

Custom WebServer with Socket.io

Typescript Server Configuration

Update the package.json

Nodemon Configuration

Setup Kanban Board

Task Component

AddTask Component

Update the server.ts file

Setup API Routes for AI and Task creation

Zod Schema for Message Validation

Chat Route for OpenAI

Zod Schema for Add Task Validation

API Endpoint for Creating a Task

Build the Kanban Board

Board Component

API Route to fetch User Tasks

Update the server.ts file

Kanban Page Route

Kanban Description Page Route

Home Page Route

Conclusion ⚡

Tolgee Follow

I have localized the best short-linking platform in the world

Prerequisites

What is Tolgee?

How to set up Dub.co on your local computer

How to configure Tolgee in a Next.js application

How to set up localization in Dub.co

How to translate your application content with Tolgee

Conclusion

✨8 Powerful Open-Source tools for Creating Accessible Web Apps ✨

Localization Tools 🌍

Color and Contrast Tools 🎨

Accessibility Testing Tools ✅

￼

Speech-to-Text Tools 🗣️

Visualization and Reporting Tools 📊

Usability Testing Tools 🔍

Extra ressources 📖

17 Must-know React Projects for Developers 👩‍💻 🔥

1. Tolgee - web-based localization platform.

2. Mantine Hooks - react hooks for state and UI management.

Update the `package.json`

Update the `server.ts` file

Update the `server.ts` file

What is i18n?

What is internationalization?

What is i18next?

So what is the difference?

i18next is not a standard

TL;DR