DEV Community: Ademola Thompson

How to make your React app multilingual

Ademola Thompson — Thu, 12 Mar 2026 16:33:21 +0000

When you build a React application for the first time, your UI usually speaks only one language (e.g., English, French). However, as your user base grows, you might consider making your app available in the languages your users prefer. How do you handle this without rewriting or restructuring your entire code?

In this tutorial, you will build a simple React application and learn how to localize and translate it without breaking or restructuring your code.

Prerequisites

Before you start, you will need:

Node.js 18+
Understanding of JavaScript/ReactJS

Building a React application

In this section, you will build a simple React application with 4 pages:

Home
About
Contact
Notifications

If you want to skip this part and go straight to the localization section, you can clone the starter template on GitHub. Otherwise, let’s start building!

Step 1: Initialize a React project

Open your command line interface (CLI) on your computer and type this command to create a ReactJS application with Vite:

npm create vite@latest my-app -- --template react-ts

The command above will create a new project called my-app and use the typescript template for it. Once done, navigate into my-app and install dependencies:

cd my-app && npm install

Now, you can optionally open your application in VSCode:

code .

Finally, you can start your React application by typing this from your root folder (my-app) in the CLI:

npm run dev

You will see a page like this when you visit http://localhost:5173/:

Step 2: Install dependencies and configure your project

Now that you’ve created an empty React project, you need to install some additional dependencies and then update some of the files.

Start by installing a package for routing. Type this into your CLI from your project root folder (my-app):
```
npm install react-router-dom
```
This will install React Router, which the project will use for routing your app to different pages.

Next, update your main.tsx file to use BrowserRouter from react-router-dom. This will enable client-side routing of different components/pages without a full page reload:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import App from "./App";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </StrictMode>
);

Now, update your App.tsx file:

import { Routes, Route } from "react-router-dom";
import { Navbar } from "./components/Navbar";
import { Footer } from "./components/Footer";
import { Home } from "./pages/Home";
import { About } from "./pages/About";
import { Contact } from "./pages/Contact";
import { Notifications } from "./pages/Notifications";
import "./App.css";

export default function App() {
  return (
    <div className="app">
      <Navbar />
      <main>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
          <Route path="/contact" element={<Contact />} />
          <Route path="/notifications" element={<Notifications />} />
        </Routes>
      </main>
      <Footer />
    </div>
  );
}

This renders the Navbar and Footer on every page, and uses Routes to map each URL path to its corresponding page component, so visiting /about renders the About component, /contact renders Contact, and so on. You will create the components and pages in the next section.

Finally, update your CSS files. Update App.css like this:

.app {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
}

main {
  flex: 1;
}

Update index.css like this:

*, *::before, *::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  color: #111;
  background: #fff;
  line-height: 1.6;
}

a {
  text-decoration: none;
  color: inherit;
}

Congratulations! If you have completed this section, you are ready to build your components.

Step 3: Build your navbar and footer components

In your src folder, create a folder called components. This will hold your navbar and footer components.

Now, create two files called Navbar.tsx and Footer.tsx inside the Components folder.

Navbar.tsx:

// src/components/Navbar.tsx
import { Link } from "react-router-dom";
import "./Navbar.css";

export function Navbar() {
  return (
    <nav className="navbar">
      <Link to="/" className="logo">
        MyApp
      </Link>
      <ul>
        <li>
          <Link to="/">Home</Link>
        </li>
        <li>
          <Link to="/about">About</Link>
        </li>
        <li>
          <Link to="/contact">Contact</Link>
        </li>
        <li>
          <Link to="/notifications">Notifications</Link>
        </li>
      </ul>
    </nav>
  );
}

Footer.tsx:

// src/components/Footer.tsx
import "./Footer.css";

export function Footer() {
  return (
    <footer className="footer">
      <p>© 2026 MyApp. All rights reserved.</p>
    </footer>
  );
}

Now, you can style both components however you want. The following CSS files provide simple styles you can use. Create them inside your components folder.

Navbar.css:

/* src/components/Navbar.css */
.navbar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 1rem 2rem;
  border-bottom: 1px solid #eee;
}

.logo {
  font-weight: 700;
  font-size: 1.2rem;
  color: #111;
  text-decoration: none;
}

.navbar ul {
  list-style: none;
  display: flex;
  gap: 1.5rem;
}

.navbar a {
  text-decoration: none;
  color: #444;
  font-size: 0.95rem;
}

.navbar a:hover {
  color: #000;
}

Footer.css:

/* src/components/Footer.css */
.footer {
  padding: 1.5rem 2rem;
  border-top: 1px solid #eee;
  text-align: center;
  color: #999;
  font-size: 0.85rem;
}

Once you are done, you will be ready to build actual pages for your application.

Step 4: Create components for your pages

Start by creating a new folder inside your existing src folder. Call it pages. It will hold your app’s pages and their related styles. Inside this new folder, create the following files:

Home.tsx
About.tsx
Contact.tsx
Notifications.tsx

Now, update each of the files with some code:

Home.tsx:

// src/pages/Home.tsx
import "./Home.css";

export function Home() {
  return (
    <div className="home">
      <section className="hero">
        <h1>Build something people love</h1>
        <p>We help teams ship faster, collaborate better, and grow with confidence. Start for free — no credit card required.
        </p>
        <button>Get started</button>
      </section>

      <section className="features">
        <div className="card">
          <h3>Fast by default</h3>
          <p>Optimized for performance from day one so your users never wait.</p>
        </div>
        <div className="card">
          <h3>Easy to use</h3>
          <p>A clean interface your whole team can pick up without training.</p>
        </div>
        <div className="card">
          <h3>Built to scale</h3>
          <p>Grows with you from your first user to your millionth.</p>
        </div>
      </section>
    </div>
  );
}

About.tsx:

// src/pages/About.tsx
import "./About.css";

export function About() {
  return (
    <div className="about">
      <h1>About us</h1>
      <p>We are a small team of developers and designers who believe that great software should be accessible to everyone, regardless of where they are in the world.
      </p>
      <div className="team">
        <div className="member">
          <div className="avatar">JD</div>
          <h3>Jane Doe</h3>
          <span>Co-founder & CEO</span>
          <p>
            Jane leads product and strategy with over 10 years of experience building developer tools.
          </p>
        </div>
        <div className="member">
          <div className="avatar">JS</div>
          <h3>John Smith</h3>
          <span>Co-founder & CTO</span>
          <p>
            John oversees engineering and architecture, previously at several Y Combinator startups.
          </p>
        </div>
        <div className="member">
          <div className="avatar">AP</div>
          <h3>Aisha Patel</h3>
          <span>Head of Design</span>
          <p>
            Aisha crafts the product experience with a background in design systems and accessibility.
          </p>
        </div>
      </div>
    </div>
  );
}

Contact.tsx:

// src/pages/Contact.tsx
import { useState } from "react";
import "./Contact.css";

export function Contact() {
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");
  const [message, setMessage] = useState("");
  const [submitted, setSubmitted] = useState(false);

  function handleSubmit() {
    if (!name || !email || !message) return;
    setSubmitted(true);
    setName("");
    setEmail("");
    setMessage("");
    setTimeout(() => setSubmitted(false), 3000);
  }
  return (
    <div className="contact">
      {submitted && <div className="toast">Message sent successfully!</div>}
      <h1>Contact us</h1>
      <p>
        Have a question or want to work together? We would love to hear from you.
      </p>
      <div className="form">
        <div className="field">
          <label htmlFor="name">Your name</label>
          <input
            id="name"
            type="text"
            placeholder="Jane Doe"
            value={name}
            onChange={(e) => setName(e.target.value)}
          />
        </div>
        <div className="field">
          <label htmlFor="email">Email address</label>
          <input
            id="email"
            type="email"
            placeholder="jane@example.com"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
          />
        </div>
        <div className="field">
          <label htmlFor="message">Message</label>
          <textarea
            id="message"
            rows={5}
            placeholder="Tell us what's on your mind..."
            value={message}
            onChange={(e) => setMessage(e.target.value)}
          />
        </div>
        <button onClick={handleSubmit}>Send message</button>
      </div>
    </div>
  );
}

Notifications.tsx:

//src/pages/Notifications.tsx
import "./Notifications.css";

const notifications = [
  {
    id: 1,
    user: "Alice Martin",
    action: "joined the team",
    date: new Date("2025-11-03"),
  },
  {
    id: 2,
    user: "Bob Chen",
    action: "left a comment on your post",
    date: new Date("2025-11-05"),
  },
];

const dateFormatter = new Intl.DateTimeFormat(navigator.language, {
  year: "2-digit",
  month: "2-digit",
  day: "2-digit",
});

export function Notifications() {
  return (
    <div className="notifications">
      <h1>Notifications</h1>
      <ul className="notification-list">
        {notifications.map((a) => (
          <li key={a.id} className="notification-item">
            <div className="notification-avatar">
              {a.user === "System" ? "S" : a.user[0]}
            </div>
            <div className="notification-body">
              <p>
                <strong>{a.user}</strong> {a.action}
              </p>
              <span className="notification-date">
                {dateFormatter.format(a.date)}
              </span>
            </div>
          </li>
        ))}
      </ul>
    </div>
  );
}

Congratulations! You have created four new pages in your React application, including a contact page with a form, and a notifications page with some hard-coded notifications.

Now, you should style your pages. Create the following files inside your pages folder:

Home.css
About.css
Contact.css
Notifications.css

You can update the styling of your pages however you want. The following are simple styles you can use.

Home.css:

/* src/pages/Home.css */
.home {
  max-width: 900px;
  margin: 0 auto;
  padding: 0 2rem 4rem;
}

.hero {
  text-align: center;
  padding: 5rem 2rem 3rem;
}

.hero h1 {
  font-size: 2.2rem;
  font-weight: 800;
  line-height: 1.2;
  margin-bottom: 1rem;
}

.hero p {
  color: #555;
  font-size: 1.05rem;
  margin-bottom: 2rem;
  max-width: 520px;
  margin-left: auto;
  margin-right: auto;
}

.hero button {
  background: #000;
  color: #fff;
  border: none;
  padding: 0.75rem 1.75rem;
  font-size: 1rem;
  border-radius: 6px;
  cursor: pointer;
}

.hero button:hover {
  background: #222;
}

.features {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  gap: 1.5rem;
}

.card {
  padding: 1.5rem;
  border: 1px solid #eee;
  border-radius: 8px;
}

.card h3 {
  margin-bottom: 0.5rem;
  font-size: 1rem;
  font-weight: 600;
}

.card p {
  color: #555;
  font-size: 0.9rem;
}

About.css:

/* src/pages/About.css */
.about {
  max-width: 800px;
  margin: 0 auto;
  padding: 3rem 2rem 4rem;
}

.about h1 {
  font-size: 2rem;
  font-weight: 800;
  margin-bottom: 1rem;
}

.about > p {
  color: #555;
  font-size: 1.05rem;
  margin-bottom: 3rem;
  line-height: 1.8;
  max-width: 580px;
}

.team {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  gap: 1.5rem;
}

.member {
  padding: 1.5rem;
  border: 1px solid #eee;
  border-radius: 8px;
}

.avatar {
  width: 40px;
  height: 40px;
  border-radius: 50%;
  background: #111;
  color: #fff;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 0.8rem;
  font-weight: 700;
  margin-bottom: 0.75rem;
}

.member h3 {
  font-size: 0.95rem;
  font-weight: 600;
  margin-bottom: 0.2rem;
}

.member span {
  font-size: 0.8rem;
  color: #888;
  display: block;
  margin-bottom: 0.6rem;
}

.member p {
  font-size: 0.85rem;
  color: #555;
  line-height: 1.6;
}

Contact.css:

/* src/pages/Contact.css */
.contact {
  max-width: 520px;
  margin: 0 auto;
  padding: 3rem 2rem 4rem;
}

.contact h1 {
  font-size: 2rem;
  font-weight: 800;
  margin-bottom: 0.5rem;
}

.contact > p {
  color: #555;
  font-size: 1.05rem;
  margin-bottom: 2rem;
}

.form {
  display: flex;
  flex-direction: column;
  gap: 1.25rem;
}

.field {
  display: flex;
  flex-direction: column;
  gap: 0.4rem;
}

.field label {
  font-size: 0.9rem;
  font-weight: 500;
}

.field input,
.field textarea {
  padding: 0.65rem 0.85rem;
  border: 1px solid #ddd;
  border-radius: 6px;
  font-size: 0.95rem;
  font-family: inherit;
  color: #111;
  resize: vertical;
}

.field input:focus,
.field textarea:focus {
  outline: none;
  border-color: #000;
}

button {
  background: #000;
  color: #fff;
  border: none;
  padding: 0.75rem 1.5rem;
  font-size: 1rem;
  border-radius: 6px;
  cursor: pointer;
  align-self: flex-start;
}

button:hover {
  background: #222;
}

.toast {
  position: fixed;
  bottom: 2rem;
  right: 2rem;
  background: #111;
  color: #fff;
  padding: 0.85rem 1.25rem;
  border-radius: 8px;
  font-size: 0.9rem;
  font-weight: 500;
  animation: slideUp 0.2s ease;
}

@keyframes slideUp {
  from {
    transform: translateY(10px);
    opacity: 0;
  }
  to {
    transform: translateY(0);
    opacity: 1;
  }
}

Notifications.css:

/* src/pages/Notifications.css */
.notifications {
  max-width: 640px;
  margin: 0 auto;
  padding: 3rem 2rem 4rem;
}

.notifications h1 {
  font-size: 2rem;
  font-weight: 800;
  margin-bottom: 2rem;
}

.notification-list {
  list-style: none;
  display: flex;
  flex-direction: column;
  gap: 0;
}

.notification-item {
  display: flex;
  align-items: flex-start;
  gap: 1rem;
  padding: 1rem 0;
  border-bottom: 1px solid #f0f0f0;
}

.notification-item:last-child {
  border-bottom: none;
}

.notification-avatar {
  width: 36px;
  height: 36px;
  border-radius: 50%;
  background: #111;
  color: #fff;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 0.8rem;
  font-weight: 700;
  flex-shrink: 0;
}

.notification-body {
  display: flex;
  flex-direction: column;
  gap: 0.2rem;
}

.notification-body p {
  font-size: 0.9rem;
  color: #111;
  line-height: 1.5;
}

.notification-date {
  font-size: 0.8rem;
  color: #aaa;
}

Congrats! You have completely built a React application with multiple pages. To view your app in the browser, type this command in your CLI:

npm run dev

You should see a page like this:

You are now ready to make your app multilingual.

How to Localize a Website

You’ve built a great website or web app with React, and now you want to make it available in multiple languages without significantly breaking your code.

In this section, you will learn how to localize your web app by using Lingo.dev, an AI tool that makes it super easy to translate React applications. Create a free account to get started.

Step 1: Install the Lingo.dev compiler

From the root directory of your app, type this command to install the Lingo.dev compiler:

pnpm install @lingo.dev/compiler

Step 2: Update your app’s configuration for localization

Open your vite.config.ts file and add the lingoCompilerPlugin to your list of plugins above your react() plugin:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite"; // import from Lingo.dev

export default defineConfig({
  plugins: [
  // lingoCompilerPlugin
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: false,
      },
    }),
    react(),
  ],
});

The code above uses the lingoCompilerPlugin plugin to tell your application how it should handle localization. Inside it, you define:

sourceRoot: The directory where your app's source files live. The default value is src.
sourceLocale: The language your app is currently written in. This is set to English.
targetLocales: An array of the languages you want to translate your app into. Here, it is set to Spanish, German, and French. You can add more language codes if you want.
models: The translation engine to use. Use lingo.dev for easy setup.
usePseudotranslator: Set to false so you can get real translations instead of pseudo-translations.

NOTE: You must place the lingoCompilerPlugin before the react() plugin. This enables the compiler to transform your JSX before React processes it.

Step 3: Configure your API key

Create a .env file in your root folder to hold your Lingo.dev API key.

To get your API key, open your Lingo.dev dashboard, click the Get API key button at the top right, and copy your API key.

Now paste your API key into your .env file:

LINGODOTDEV_API_KEY=your_api_key

Step 4: Connect your app to the translation compiler

Now, you need to connect your application to the translation compiler by wrapping
your app with LingoProvider in your entry point. Open your src/main.tsx file and add this:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import { LingoProvider } from "@lingo.dev/compiler/react"; //new 
import App from "./App";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </LingoProvider>
  </StrictMode>,
);

The code above wraps the LingoProvider around your app.

Step 5: Add a language switcher

Next, add a language switcher to your app so users can easily switch between languages. Create a new file inside your components folder and call it LanguageSwitcher.tsx. Add this code to it:

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <div>
      <label>Language:</label>
      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Español</option>
        <option value="de">Deutsch</option>
        <option value="fr">Français</option>
      </select>
    </div>
  );
}

Now update your navbar component to include the language switcher:

// src/components/Navbar.tsx
import { LanguageSwitcher } from "./LanguageSwitcher";

export function Navbar() {
  return (
    <nav className="navbar">
      <Link to="/" className="logo">
        MyApp
      </Link>
      <ul>
        <li>
          <Link to="/">Home</Link>
        </li>
        {/* other nav links */}
        </ul>
      <LanguageSwitcher />
    </nav>
  );
}

Step 6: Test your translations

Congratulations! You have successfully localized your React application to four languages (English, Spanish, German, and French). To see this in action, open your CLI and run your development server:

npm run dev

Next, open your app in the browser and try to toggle the language switcher:

The first time you do this, it will take a few seconds before the translated texts show up. After that, the translations will be stored in cache and only updated when you update your texts.

The Lingo.dev compiler will create a folder called lingo inside your src folder. You can find your cache here.

Step 7: Handle locale-based routing

Locale-based routing helps to boost your website's SEO by telling search engines which version of your page is intended for which audience. When a user in France searches for your app, Google can serve them /fr instead of /en.

To perform locale-based routing, do the following:

Update your App.tsx file to prefix all routes with a locale segment:

// src/App.tsx
import { Routes, Route, Navigate } from "react-router-dom"; // updated import
import { Navbar } from "./components/Navbar";
import { Footer } from "./components/Footer";
import { Home } from "./pages/Home";
import { About } from "./pages/About";
import { Contact } from "./pages/Contact";
import { Notifications } from "./pages/Notifications";
import "./App.css";

export default function App() {
  // detect the browser's language
  const defaultLocale = navigator.language.split("-")[0] || "en";
  return (
    <div className="app">
      <Navbar />
      <main>
        <Routes>
          <Route
            path="/"
            element={<Navigate to={`/${defaultLocale}`} replace />}
          />{" "}
          {/* redirect to default locale */}
          <Route path="/:locale" element={<Home />} />
          <Route path="/:locale/about" element={<About />} />
          <Route path="/:locale/contact" element={<Contact />} />
          <Route path="/:locale/notifications" element={<Notifications />} />
        </Routes>
      </main>
      <Footer />
    </div>
  );
}

Update your language switcher to sync with the URL. This way, when a user switches the locale to a different language, the URL also changes to the right locale:

// src/components/LanguageSwitcher.tsx
import { useLingoContext } from "@lingo.dev/compiler/react";
import { useNavigate, useLocation } from "react-router-dom";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();
  const navigate = useNavigate();
  const location = useLocation();

  function handleChange(newLocale: string) {
    setLocale(newLocale);
    const rest = location.pathname.replace(/^\/[a-z]{2}/, "") || "/";
    navigate(`/${newLocale}${rest}`);
  }
  return (
    <div>
      <label>Language:</label>
      <select value={locale} onChange={(e) => handleChange(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Español</option>
        <option value="de">Deutsch</option>
        <option value="fr">Français</option>
      </select>
    </div>
  );
}

The updated LanguageSwitcher component does two things at once when the user picks a language:

- It calls `setLocale` to update the active translation.
- It calls `navigate` to update the URL. The regex `/^\/[a-z]{2}/` strips the current locale prefix from the path so the new locale can be prepended cleanly.

Now, switching from `/fr/about` to Spanish gives you `/es/about`.

Finally, update your navbar links to use the active locale:

// src/components/Navbar.tsx
import { Link } from "react-router-dom";
import { useLingoContext } from "@lingo.dev/compiler/react";
import "./Navbar.css";
import { LanguageSwitcher } from "./LanguageSwitcher";

export function Navbar() {
  const { locale } = useLingoContext();

  return (
    <nav className="navbar">
      <Link to={`/${locale}`} className="logo">MyApp</Link>
      <ul>
        <li><Link to={`/${locale}`}>Home</Link></li>
        <li><Link to={`/${locale}/about`}>About</Link></li>
        <li><Link to={`/${locale}/contact`}>Contact</Link></li>
        <li><Link to={`/${locale}/notifications`}>Notifications</Link></li>
      </ul>
      <LanguageSwitcher />
    </nav>
  );
}

The navbar now reads the current locale from useLingoContext — the single source of truth for the active language. Every link is built with that locale, so navigating anywhere in the app keeps the URL and the translation in sync.

Now, you can restart your server by running:

npm run dev

You should see the changes in your URL as you switch between pages and locales.

Step 8: Translate JSON in your app

If you observe your app, you will notice that the notifications on the notifications page are not translated. This is because the Lingo.dev compiler does not yet support translating JSON format. To fix this, you can use the Lingo.dev CLI.

Follow these steps to properly translate your notifications.

Initialize the Lingo.dev CLI from your root directory:
```
npx lingo.dev@latest init
```
The command above will ask you a few questions, like:

- Your app’s primary language. Type “en” for this project,
- Your target languages. Type “es,de,fr” for this project,
- File format. Type “json” since you want to translate JSON format,
- If you want to  use (and create) the default path i18n/[locale].json. Type “y”.

You can skip any other questions it asks you or type “n”.

The command above will create an `i18n` folder and an `i18n.json` file in your root directory.

Update your i18n folder. This folder will contain an en.json file. Add your notifications object to this file as JSON:

{
  "0": {
    "id": 1,
    "user": "Alice Martin",
    "action": "joined the team",
    "date": "2025-11-03"
  },
  "1": {
    "id": 2,
    "user": "Bob Chen",
    "action": "left a comment on your post",
    "date": "2025-11-05"
  }
}

Run this command from your root directory:
```
npx lingo.dev@latest run
```
This command will generate your translations. You should see the following files in your i18n folder:

- `es.json`
- `fr.json`
- `de.json`

Now update your Notifications.tsx file to use the right translation when languages get switched:

// src/pages/Notifications.tsx
import "./Notifications.css";
import { useLingoContext } from "@lingo.dev/compiler/react";

import en from "../../i18n/en.json";
import es from "../../i18n/es.json";
import de from "../../i18n/de.json";
import fr from "../../i18n/fr.json";

const translations = { en, es, de, fr };

const dateFormatter = new Intl.DateTimeFormat(navigator.language, {
  year: "2-digit",
  month: "2-digit",
  day: "2-digit",
});

export function Notifications() {
  const { locale } = useLingoContext();
  const notifications = Object.values(translations[locale as keyof typeof translations],);

  return (
    <div className="notifications">
      <h1>Notifications</h1>
      <ul className="notification-list">
        {notifications.map((a) => (
          <li key={a.id} className="notification-item">
            <div className="notification-avatar">{a.user === "System" ? "S" : a.user[0]}</div>
            <div className="notification-body">
              <p><strong>{a.user}</strong> {a.action}</p>
              <span className="notification-date">{dateFormatter.format(new Date(a.date))}</span>
            </div>
          </li>
        ))}
      </ul>
    </div>
  );
}

Now, if you run npm run dev and view your notifications page, you will get the right translations:

Step 9: Remove the Lingo.dev widget

Congratulations! Your app is almost ready to go live. The last thing you should do is to remove the Lingo.dev widget at the bottom left of your app:

To do this, simply add the devWidget prop to your LingoProvider in the main.tsx file:

// src/main.tsx
<LingoProvider devWidget={{ enabled: false }}>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </LingoProvider>

Now, the widget should disappear, and your app should be ready to go:

Conclusion

Congratulations! You have successfully built a multilingual React application that speaks four languages. You can clone the project from the GitHub repository for reference.

As you have seen, localizing your React application does not require restructuring your code or changing how you write your components. The Lingo.dev Compiler handles everything at build time — every time you add new text, it gets picked up and translated automatically. Adding a new language is as simple as updating the targetLocales array in your config file.

When you are ready to take things further, you can integrate Lingo.dev into your CI/CD pipeline so translations are generated automatically on every deployment. You can also explore the Lingo.dev SDK for translating dynamic content like user-generated text that lives in your database rather than your code.

How to Build a CLI Tool to Auto-Translate OpenAPI Specifications

Ademola Thompson — Mon, 23 Feb 2026 15:34:59 +0000

APIs defined with the OpenAPI Specification make integration easier, but language can still be a barrier. Many API specs, descriptions, and examples are written in a single language, which limits accessibility for global developers.

In this article, you’ll learn how to build a CLI tool that automatically translates an OpenAPI specification into multiple languages, making your API documentation more accessible without maintaining separate versions manually.

What You Will Build

By the end of this tutorial, you'll have built a complete CLI application that:

Parses and manipulates OpenAPI/Swagger specs programmatically
Integrates with Lingo.dev for context-aware translations
Generates a dynamic React viewer with language switching

Prerequisites

Intermediate JavaScript/Node.js knowledge
Familiarity with React (for the frontend viewer portion)
Basic understanding of OpenAPI/Swagger specifications
A Lingo.dev account

How it Works

Trans-Spec operates as a three-stage pipeline that takes your OpenAPI specification and produces multilingual documentation with a browsable view.

The Process

1. Parse & Extract

Reads your OpenAPI spec
Identifies translatable content (descriptions, summaries)
Preserves technical terms (paths, parameter names, enums)

2. Set up Structure and Translate

Creates .trans-spec/i18n/ folder structure
Generates i18n.json configuration
Calls Lingo.dev to translate content
Saves translated specs per language

3. Serve

Copies the translated specs to the frontend public directory
Generates a dynamic Vite config with your languages
Translates the frontend UI using Lingo.dev Compiler
Starts the dev server at localhost:3000

Key Feature: Language switching updates both the API docs content AND the viewer UI simultaneously. When you select Spanish, you see Spanish API descriptions with Spanish UI labels.

Incremental Updates: Re-running generate only re-translates changed content and preserves existing translations.

Project Initialization and Setup

This project will be a monorepo that contains the CLI and the frontend viewer in a single parent folder.

Create a new folder for your project and initialize a NodeJS project:

# create a new folder (called trans-spec) and navigate into it
mkdir trans-spec && cd trans-spec

# Initialize root package.json
npm init -y

Create folders for your CLI logic and frontend viewer:
```
mkdir cli viewer
```
Set up your CLI:
```
# Setup CLI
cd cli && npm init -y

# install dependencies
npm install commander chalk ora

# create necessary directories and files
mkdir src && touch index.js src/auth.js src/setup.js src/config.js src/translate.js && cd ..
```
The above initializes a NodeJS application and installs:
- commander: to handle CLI commands and flags.
- chalk: to add colors in the terminal (makes output look nice).
- ora: for spinner/progress indicators while translations are running.
The command also creates an entry file called index.js and a folder called src. This folder is where most of your CLI logic will live.
Set up your viewer:
```
# Setup Viewer
cd viewer && npm install -g create-vite && npm create vite@latest . -- --template react

# install dependencies
npm install js-yaml @apidevtools/swagger-parser @lingo.dev/compiler tailwindcss @tailwindcss/vite react-dom react-markdown && cd ..
```
The commands above initialize a React application using Vite. They also install the following:
- js-yaml to read and write YAML structures in JavaScript for display.
- @apidevtools/swagger-parser to parse and validate OpenAPI/Swagger spec files, resolving all $ref references into a clean, workable object.
- @lingo.dev/compiler to handle translation for UI text.
- react-dom to render your React components in the browser.
- tailwindcss and @tailwindcss/vite for styling.
- react-markdown to handle markdown syntax.
NOTE: If the first command starts a React server, you can simply end the process with ctrl + c (command + c on Mac).
Finally, open your project in VSCode:
```
code .
```

Building a CLI Tool to Translate OpenAPI Specification Files

If you have completed the section above, your cli folder should look like this:

cli/
├── index.js
├── package.json
└── src/
    ├── auth.js
    ├── config.js
    └── setup.js
    └── translate.js

Now, you are ready to start this section.

Step 1. Create the Authentication Flow

In your src/auth.js file, start by importing necessary dependencies:
```
import { execSync, spawn } from "child_process";
import ora from "ora";
import chalk from "chalk";
```
The code above imports:
- execSync, which you can use to run a command and wait for it to finish before moving to the next process,
- spawn, which you can use to run a command in the background and react to events as they happen,
- ora for a loading spinner,
- chalk for colored terminal output.
Next, add a small helper that allows you to pause execution for a given number of milliseconds. This is useful when you need to wait for a response:
```
const MAX_RETRIES = 2;

function wait(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}
```
Now write the function that checks whether the user is already logged in to their Lingo.dev account, since this project uses Lingo.dev for translation:
```
function isAuthenticated() {
  try {
    const output = execSync("npx lingo.dev@latest auth 2>&1", {
      encoding: "utf-8",
      stdio: "pipe",
    });
    return output.includes("Authenticated as");
  } catch (err) {
    return false;
  }
}
```
The code above runs the Lingo.dev CLI auth command and checks the output for "Authenticated as". This check is because Lingo.dev does not return output like true or false in the auth command; instead, it returns a message like:
```
Authenticated as <your-email>
```
If anything goes wrong while running the command, the code simply returns false.
NOTE: The isAuthenticated() function uses 2>&1 because Lingo.dev writes the "Authenticated as" output to stderr instead of stdout. execSync only captures stdout by default.

Write a function to trigger login if the user authentication fails:

async function triggerLogin() {
  return new Promise((resolve, reject) => {
    const login = spawn("npx", ["lingo.dev@latest", "login"], {
      stdio: "inherit",
      shell: true,
    });

    login.on("close", (code) => {
      if (code === 0) {
        spinner.succeed("Login complete");
        resolve();
      } else {
        spinner.fail("Login failed");
        reject(new Error("Login process exited with code " + code));
      }
    });

    login.on("error", (err) => {
      spinner.fail("Login failed");
      reject(err);
    });
  });
}

NOTE: using stdio: 'inherit' lets the login process use the same terminal as your CLI tool, so the user can see what's happening.

Now, create and export a function that will run the full authentication process, using the code we already have:

export async function checkAuth() {
  const spinner = ora("Checking authentication").start();

  // Already authenticated, no need to login
  if (isAuthenticated()) {
    spinner.succeed(chalk.green("Authenticated"));
    return;
  }

  spinner.stop();

  // Not authenticated, trigger login once
  try {
    await triggerLogin();
  } catch (err) {
    console.log(chalk.red("✖ Login failed: " + err.message));
    process.exit(1);
  }

  // After login, wait and retry auth check up to MAX_RETRIES times
  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
    await wait(2000); // wait 2 seconds before checking

    if (isAuthenticated()) {
      console.log(chalk.green("✔ Successfully authenticated"));
      return;
    }

    if (attempt < MAX_RETRIES) {
      console.log(
        chalk.yellow(
          `Auth check failed. Retrying (${attempt}/${MAX_RETRIES})...`,
        ),
      );
    }
  }

  console.log(chalk.red("✖ Authentication failed"));
  console.log(
    chalk.white("Please run: npx lingo.dev@latest login manually and try again."
    ),
  );
  process.exit(1);
}

The spinner stops before triggerLogin() is called. If it kept running while the login process took over the terminal, the output would be garbled. After login, the function retries the auth check up to two times with a 2-second gap, giving credentials time to be written to disk before giving up.

Step 2: Prepare Your OpenAPI File for Translation

Before your CLI tool can translate anything, it needs to know where your OpenAPI spec file is and what language it's written in.

setup.js handles that initialization step. It takes your existing spec file, creates the .trans-spec folder structure, and copies the file into the right place so the rest of the tool knows where to find it.

If the spec file is in English, it creates a .trans-spec/i18n/en/your-file.yaml and copies your file there. If it is in French, it uses the fr folder instead of en. Later, you will get the language source from the user so your code can know which language code to use.

Copy this code into your src/setup.js file:

import fs from "fs";
import path from "path";
import chalk from "chalk";
import ora from "ora";

const TRANSSPEC_DIR = ".trans-spec";
const I18N_DIR = path.join(TRANSSPEC_DIR, "i18n");

export async function setup(specPath, sourceLanguage) {
  const spinner = ora("Setting up project...").start();

  try {
    const resolvedSpecPath = path.resolve(specPath);

    if (!fs.existsSync(resolvedSpecPath)) {
      spinner.fail(chalk.red(`Spec file not found: ${specPath}`));
      process.exit(1);
    }

    // Use source language folder
    const sourceDir = path.join(I18N_DIR, sourceLanguage);

    if (!fs.existsSync(TRANSSPEC_DIR)) {
      fs.mkdirSync(sourceDir, { recursive: true });
      spinner.text = "Created .trans-spec folder structure";
    }

    // Preserve the original filename
    const originalFilename = path.basename(resolvedSpecPath);
    const destPath = path.join(sourceDir, originalFilename);

    fs.copyFileSync(resolvedSpecPath, destPath);

    spinner.succeed(chalk.green("Project setup complete"));
  } catch (err) {
    spinner.fail(chalk.red("Setup failed: " + err.message));
    process.exit(1);
  }
}

Step 3: Generate the Lingo.dev Configuration

Lingo.dev needs a configuration file to know which languages to translate from and to. src/config.js generates that file and saves it at .trans-spec/i18n.json.

Open your src/config.js file and add your impors:

import fs from "fs";
import path from "path";
import chalk from "chalk";
import ora from "ora";

const TRANSSPEC_DIR = ".trans-spec";
const CONFIG_PATH = path.join(TRANSSPEC_DIR, "i18n.json");

Write a generateConfig function to generate the configuration Lingo.dev expects:

export async function generateConfig(languages, source = "en") {
  const spinner = ora("Generating config...").start();

  try {
    // Handles comma separated values: "es,fr,de"
    // Parse new languages if provided
    let newTargets = [];
    if (languages) {
      newTargets = languages
        .split(/[\s,]+/)
        .map((lang) => lang.trim())
        .filter(Boolean);
    }

    // Check if config already exists
    let existingTargets = [];
    if (fs.existsSync(CONFIG_PATH)) {
      const existingConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
      existingTargets = existingConfig.locale?.targets || [];
    }

    // Merge: existing + new, remove duplicates
    const allTargets = [...new Set([...existingTargets, ...newTargets])];

    if (allTargets.length === 0) {
      spinner.fail(chalk.red("No target languages provided"));
      process.exit(1);
    }

    const config = {
      $schema: "https://lingo.dev/schema/i18n.json",
      version: "1.12",
      locale: {
        source: source,
        targets: allTargets,
      },
      buckets: {
        yaml: {
          include: ["i18n/[locale]/*.yaml"],
        },
      },
    };

    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));

    if (newTargets.length > 0) {
      spinner.succeed(
        chalk.green(`Config updated: ${source} → ${allTargets.join(", ")}`),
      );
    } else {
      spinner.succeed(
        chalk.green(
      `Using existing config: ${source} → ${allTargets.join(", ")}`,
        ),
      );
    }
    return allTargets;
  } catch (err) {
    spinner.fail(chalk.red("Config generation failed: " + err.message));
    process.exit(1);
  }
}

The function accepts a languages string in any reasonable format, such as es,fr. If a configuration file already exists, the new languages are merged with the existing ones rather than overwriting them.
Wrapping in new Set handles duplicates, so running the command twice with the same languages won't bloat the file.

The buckets field is what Lingo.dev uses to find your files. The [locale] placeholder in i18n/[locale]/*.yaml gets replaced with each target language code at translation time, mapping directly to the folder structure you created in the previous step.

You can read the official Lingo.dev documentation for further understanding.

Finally, the function returns the targets array because the index.js file will need it later to tell the user where their translated files are.

Step 4: Call Lingo.dev for Translation

Now that you have created the configuration that Lingo.dev expects, you can perform the actual translation by programmatically calling lingo.dev run.

Open your src/translate.js and add your imports:

import { spawn } from "child_process";
import chalk from "chalk";
import ora from "ora";
import path from "path";

const TRANSSPEC_DIR = ".trans-spec";
const MAX_RETRIES = 2;

Now add the runTranslation function, which spawns the Lingo.dev CLI and watches the output:

async function runTranslation() {
return new Promise((resolve, reject) => {
let output = "";
let hasErrors = false;

const process = spawn("npx", ["lingo.dev@latest", "run"], {
  cwd: path.resolve(TRANSSPEC_DIR),
  shell: true,
  stdio: "pipe",
});

// Capture stdout
process.stdout.on("data", (data) => {
  const text = data.toString();
  output += text;
  console.log(text);
  // Check for failure indicators
  if (text.includes("❌") || text.includes("[Failed Files]")) {
    hasErrors = true;
  }
});

process.on("close", (code) => {
  if (code !== 0 || hasErrors) {
    reject(new Error("Translation had errors or failures"));
  } else {
    resolve();
  }
});

process.on("error", (err) => {
  reject(err);
});
});
}

Notice the cwd option:

cwd: path.resolve(TRANSSPEC_DIR)

This tells the spawn process to run from inside the .trans-spec/ folder. This is critical because lingo.dev run looks for i18n.json in the current working directory. Without this, it would look in the wrong place and fail.

The output is piped so the function can scan it in real time. A zero exit code alone isn't enough to confirm success. Lingo.dev can exit cleanly, but still report failed files in the output. So the function also watches for "❌" and "[Failed Files]", and treats those as errors.

Now, add the translate() function that ties it together:

export async function translate(targets) {
const spinner = ora("Translating...").start();
spinner.stop();

  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
try {
  await runTranslation();
  console.log(chalk.green("\n✔ Translation complete"));
  return;
} catch (err) {
  if (attempt < MAX_RETRIES) {
    console.log(
      chalk.yellow(
        `Translation failed. Retrying (${attempt}/${MAX_RETRIES})...`,
      ),
    );
  }
}
}

  console.log(chalk.red("Translation failed after 2 attempts."));
console.log(
chalk.white("Please try running manually: npx lingo.dev@latest run"),
);
process.exit(1);
}

If the first attempt fails, it retries once more before giving up. On final failure, it exits with a message pointing the user to run the command manually — the same pattern you used in auth.js.

Step 5: Create Your CLI Entry Point

The index.js file created earlier will serve as the entry point for your CLI tool. It uses Commander to define the commands and connect them to the functions you've built so far.

Paste your imports into index.js:

#!/usr/bin/env node

import { program } from "commander";
import chalk from "chalk";
import path from "path";
import { checkAuth } from "./src/auth.js";
import { setup } from "./src/setup.js";
import { generateConfig } from "./src/config.js";
import { translate } from "./src/translate.js";

const TRANSSPEC_DIR = ".trans-spec";

program
.name("trans-spec")
.description("Translate your OpenAPI spec into multiple languages")
.version("1.0.0");

Add the generate command:

program
.command("generate")
.description("Translate an OpenAPI spec into multiple languages")
.requiredOption("--spec <path>", "Path to your OpenAPI spec file")
.option("--languages <languages>", "Target languages e.g. es,fr,de")
.option("--source <language>", "Source language (default: en)", "en")
.action(async (options) => {
console.log(chalk.bold("\n🌍 Trans-Spec\n"));

await checkAuth();
await setup(options.spec, options.source);
const targets = await generateConfig(options.languages, options.source);
await translate(targets);

console.log(chalk.bold("\n✔ Done! Your translated specs are in:\n"));
targets.forEach((lang) => {
  console.log(chalk.cyan(`  ${TRANSSPEC_DIR}/i18n/${lang}/api.yaml`));
});
console.log(chalk.white("\nTo view your docs, run:"));
console.log(chalk.cyan("  npx trans-spec serve\n"));
});

Each step maps directly to a file you've built — checkAuth, setup, generateConfig, and translate run in sequence. When done, the command prints the path to each translated file and suggests the next step.

Now add the serve command that will allow the user generate a frontend to browse their API documentation:

This command does the following:
- It looks for a Lingo.dev API key. If it does not find it, it prompts the user for it, and the key is saved so they aren't asked again on the next run. This is because the Lingo.dev CLI and Compiler do not share auth state, so users need to authenticate for both scenarios.
- It generates a Vite configuration file (vite.config.generated.js) dynamically from i18n.json rather than being a static file. This means it always reflects the current language setup without the user having to touch any config manually. We'll cover the viewer itself in the next section.

If you have gotten to this section, congratulations! You now have a CLI tool that translates OpenAPI specification files. To test it, navigate to your cli directory and run this command:

node index.js generate --spec api.yaml --languages es,fr

NOTE: Ensure you have an api.yaml file in your directory. You should also update your package.json files as such:

 "type": "module"

Build a Frontend Interface to View any OpenAPI Specification File

With your translated YAML files ready, you need a way to actually view them. In this section, you'll build a lightweight React interface that reads your OpenAPI spec files and renders them into a readable API reference with language switching built in.

Step 1: Set Up the Viewer File Structure

Navigate to your viewer/src folder and create the folders and files you will work with.

# navigate
cd viewer/src

# create necessary folders
mkdir components utils

## create files
touch utils/specLoader.js components/Sidebar.jsx components/EndpointDetail.jsx components/LanguageSwitcher.jsx

The above creates the components and utils folders with associated files.

Step 2: Load and Parse the OpenAPI Spec Files

Before the UI can render anything, it needs to know what spec files are available and how to load them. specLoader.js handles all of that:

fetching the index
detecting the right language
parsing the YAML into a usable object.

Open your viewer/src/utils/specLoader.js file and paste this:

import SwaggerParser from "@apidevtools/swagger-parser";
import yaml from "js-yaml";

Now add the functions that fetch the available specs and languages:

/**
* Load the index to see what specs are available
*/
export async function getSpecIndex() {
const response = await fetch("/trans-spec/index.json");
return await response.json();
}

/**
 * Load and parse the i18n.json config to get available languages
 */
export async function getAvailableLanguages() {
try {
const response = await fetch("/trans-spec/i18n.json");
const config = await response.json();

return {
  source: config.locale.source,
  targets: config.locale.targets,
  all: [config.locale.source, ...config.locale.targets],
};
} catch (err) {
console.error("Failed to load i18n config:", err);
return { source: "en", targets: [], all: ["en"] };
}
}

getSpecIndex fetches the index.json file the CLI generated — a map of every language to its available spec files. getAvailableLanguages reads i18n.json and returns the source language, the target languages, and a combined list of all of them.

Next, add the language detection helpers:

export function getBrowserLanguage() {
// navigator.language returns like "en-US", "es-ES", etc.
const lang = navigator.language.split("-")[0]; // Get just "en", "es", etc.
return lang;
}

/**
 * Get default language based on browser preference
 */
export async function getDefaultLanguage() {
const browserLang = getBrowserLanguage();
const { all, source } = await getAvailableLanguages();

  // Use browser language if available, otherwise fallback to source
return all.includes(browserLang) ? browserLang : source;
}

getBrowserLanguage reads the browser's language preference. getDefaultLanguage then checks whether that language is actually available in the spec, falling back to the source language if not.

Finally, add the functions that pick the default spec and load it:

/**
* Get default spec (first one alphabetically)
*/
export async function getDefaultSpec() {
const index = await getSpecIndex();
const defaultLang = await getDefaultLanguage();
const specs = index[defaultLang] || [];
return specs[0] || null;
}

/**
 * Load and parse an OpenAPI spec for a specific language and filename
 */
export async function loadSpec(language, filename) {
try {
const response = await fetch(`/trans-spec/i18n/${language}/${filename}`);
const yamlText = await response.text();
const parsed = yaml.load(yamlText);

// Dereference all $refs for easier rendering
const dereferenced = await SwaggerParser.dereference(parsed);

return dereferenced;
} catch (err) {
console.error(`Failed to load spec ${filename} for ${language}:`, err);
throw err;
}
}

getDefaultSpec picks the first spec file alphabetically for the default language. This is useful if the user decides to generate more than one spec file. They will be able to toggle between them on the frontend.
loadSpec fetches the raw YAML, parses it with js-yaml, then passes the result through SwaggerParser.dereference. This resolves all $ref references in the spec, so every component is fully expanded and ready to render without any additional lookups.

Step 3: Build the App Component

App.jsx is the root of the viewer. It initializes the app, manages state, and wires the components together.

In src/App.jsx:

import { useState, useEffect } from "react";
import { useLingoContext } from "@lingo.dev/compiler/react";
import {
  getDefaultLanguage,
  getDefaultSpec,
  getAvailableLanguages,
  getSpecIndex,
  loadSpec,
} from "./utils/specLoader";
import Sidebar from "./components/Sidebar";
import EndpointDetail from "./components/EndpointDetail";
import LanguageSwitcher from "./components/LanguageSwitcher";

Now add the component:

function App() {
  const { locale: uiLocale, setLocale: setUILocale } = useLingoContext();

  const [spec, setSpec] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  const [currentSpecFile, setCurrentSpecFile] = useState(null);
  const [availableLanguages, setAvailableLanguages] = useState([]);
  const [availableSpecs, setAvailableSpecs] = useState([]);
  const [selectedEndpoint, setSelectedEndpoint] = useState(null);

useLingoContext gives you the current UI locale and a setter — this is how Lingo.dev's compiler knows which language to render UI text in. The rest of the state tracks the loaded spec, the selected endpoint, and what languages and spec files are available.

On mount, the app initializes everything in one go:

useEffect(() => {
    async function init() {
      try {
        setLoading(true);
        const defaultLang = await getDefaultLanguage();
        const defaultSpec = await getDefaultSpec();
        const languages = await getAvailableLanguages();
        const index = await getSpecIndex();

        setUILocale(defaultLang);
        setCurrentSpecFile(defaultSpec);
        setAvailableLanguages(languages.all);
        setAvailableSpecs(index[defaultLang] || []);

        const loadedSpec = await loadSpec(defaultLang, defaultSpec);
        setSpec(loadedSpec);

        if (loadedSpec.paths) {
          const firstPath = Object.keys(loadedSpec.paths)[0];
          const firstMethod = Object.keys(loadedSpec.paths[firstPath])[0];
          setSelectedEndpoint({ path: firstPath, method: firstMethod });
        }
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }
    init();
  }, [setUILocale]);

It detects the default language, loads the spec, and automatically selects the first endpoint so the UI has something to show right away.

Next, add two more effects to handle updates after initialization. One will reload the spec when the language changes, and the other will update the list of available spec files:

useEffect(() => {
    if (!uiLocale || !currentSpecFile) return;
    async function reload() {
      try {
        setLoading(true);
        const loadedSpec = await loadSpec(uiLocale, currentSpecFile);
        setSpec(loadedSpec);
        if (loadedSpec.paths) {
          const firstPath = Object.keys(loadedSpec.paths)[0];
          const firstMethod = Object.keys(loadedSpec.paths[firstPath])[0];
          setSelectedEndpoint({ path: firstPath, method: firstMethod });
        }
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }
    reload();
  }, [uiLocale, currentSpecFile]);

  useEffect(() => {
    if (!uiLocale) return;
    async function updateSpecs() {
      const index = await getSpecIndex();
      setAvailableSpecs(index[uiLocale] || []);
    }
    updateSpecs();
  }, [uiLocale]);

Finally, render your UI:

if (loading) return <div>Loading API documentation...</div>;
  if (error) return <div>Error: {error} — Make sure you've run trans-spec generate first.</div>;

  return (
    <div className="h-screen flex flex-col">
      <header className="border-b px-6 py-4 flex items-center justify-between">
        <div className="flex items-center gap-4">
          <h1 className="text-2xl font-bold">{spec?.info?.title || "API Documentation"}</h1>
          {availableSpecs.length > 1 && (
            <select value={currentSpecFile} onChange={(e) => setCurrentSpecFile(e.target.value)}>
              {availableSpecs.map((f) => <option key={f} value={f}>{f}</option>)}
            </select>
          )}
        </div>
        <LanguageSwitcher availableLanguages={availableLanguages} />
      </header>

      <div className="flex-1 flex overflow-hidden">
        <Sidebar spec={spec} selectedEndpoint={selectedEndpoint} onSelectEndpoint={setSelectedEndpoint} />
        <main className="flex-1 overflow-y-auto p-8">
          {selectedEndpoint && (
            <EndpointDetail spec={spec} path={selectedEndpoint.path} method={selectedEndpoint.method} />
          )}
        </main>
      </div>
    </div>
  );
}

export default App;

The header shows the API title and, if there are multiple spec files, a dropdown to switch between them. The LanguageSwitcher sits in the top right. Below that, the layout is a sidebar for navigation and a main area that renders the selected endpoint — both of which you'll build next.

Step 4: Update `main.jsx` to use `LingoProvider`

In your viewer/src/main.jsx file, paste this:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { LingoProvider } from '@lingo.dev/compiler/react'
import './index.css'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <LingoProvider>
      <App />
    </LingoProvider>
  </StrictMode>,
)

Step 5: Build a Language Switcher

Now, you should build a simple toggle that allows users to switch between languages:

import { useLingoContext } from "@lingo.dev/compiler/react";

export default function LanguageSwitcher({ availableLanguages }) {
  const { locale, setLocale } = useLingoContext();

  return (
    <div className="flex items-center space-x-2">
      <label htmlFor="language-select" className="text-sm text-gray-600">
        Language:
      </label>
      <select
        id="language-select"
        value={locale}
        onChange={(e) => setLocale(e.target.value)}
        className="px-3 py-2 border border-gray-300 rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
      >
        {availableLanguages.map((lang) => (
          <option key={lang} value={lang}>
            {lang.toUpperCase()}
          </option>
        ))}
      </select>
    </div>
  );
}

useLingoContext gives the component access to the current locale and the setLocale function. When the user picks a different language from the dropdown, setLocale updates the context, which triggers the useEffect in App.jsx that reloads the spec for the new language.

Step 6: Build the Sidebar

The sidebar lists all available endpoints grouped by tag, with a colored method badge and the endpoint path for each one.
Paste this in viewer/src/components/Sidebar.jsx:

export default function Sidebar({ spec, selectedEndpoint, onSelectEndpoint }) {
  if (!spec || !spec.paths) {
    return (
      <aside className="w-64 border-r p-4">
        <p className="text-sm">No endpoints found</p>
      </aside>
    );
  }

  const endpointsByTag = {};

  Object.entries(spec.paths).forEach(([path, pathItem]) => {
    Object.entries(pathItem).forEach(([method, operation]) => {
      if (method === "parameters" || method === "servers") return;

      const tags = operation.tags || ["Default"];
      tags.forEach((tag) => {
        if (!endpointsByTag[tag]) endpointsByTag[tag] = [];
        endpointsByTag[tag].push({ path, method, operation });
      });
    });
  });

  return (
    <aside className="w-80 border-r overflow-y-auto">
      <div className="p-4">
        <h2 className="text-xs font-semibold uppercase tracking-wider mb-4">Endpoints</h2>

        {Object.entries(endpointsByTag).map(([tag, endpoints]) => (
          <div key={tag} className="mb-6">
            <h3 className="text-sm font-semibold mb-2">{tag}</h3>
            <div className="space-y-1">
              {endpoints.map(({ path, method, operation }) => {
                const isSelected =
                  selectedEndpoint?.path === path &&
                  selectedEndpoint?.method === method;

                return (
                  <button
                    key={`${method}-${path}`}
                    onClick={() => onSelectEndpoint({ path, method })}
                    className={`w-full text-left px-3 py-2 rounded-md text-sm ${
                      isSelected ? "bg-blue-50 text-blue-700 font-medium" : "hover:bg-gray-50"
                    }`}
                  >
                    <div className="flex items-center gap-2">
                      <span className={`px-2 py-0.5 rounded text-xs font-semibold uppercase ${getMethodColor(method)}`}>
                        {method}
                      </span>
                      <span className="truncate">{path}</span>
                    </div>
                    {operation.summary && (
                      <p className="text-xs text-gray-500 mt-1 truncate">{operation.summary}</p>
                    )}
                  </button>
                );
              })}
            </div>
          </div>
        ))}
      </div>
    </aside>
  );
}

function getMethodColor(method) {
  const colors = {
    get: "bg-blue-100 text-blue-800",
    post: "bg-green-100 text-green-800",
    put: "bg-yellow-100 text-yellow-800",
    delete: "bg-red-100 text-red-800",
    patch: "bg-purple-100 text-purple-800",
  };
  return colors[method.toLowerCase()] || "bg-gray-100 text-gray-800";
}

Step 7: Build a Component to Visualize Endpoints
This will be the main content area. When the user selects an endpoint from the sidebar, this component renders everything about it: the method, path, parameters, request body, responses, and metadata.

Paste this into your viewer/scr/componente/EndpointDetail.jsx file:

import ReactMarkdown from "react-markdown";

export default function EndpointDetail({ spec, path, method }) {
  if (!spec || !path || !method) return null;

  const operation = spec.paths[path]?.[method];
  if (!operation) return null;

  return (
    <div className="p-8 max-w-4xl space-y-8">

      {/* Header */}
      <div>
        <div className="flex items-center gap-3 mb-3">
          <span className={`px-3 py-1 rounded text-sm font-semibold uppercase ${getMethodColor(method)}`}>{method}</span>
          <code className="text-lg font-mono bg-gray-100 px-3 py-1 rounded">{path}</code>
        </div>
        {operation.summary && <h1 className="text-2xl font-bold mb-2">{operation.summary}</h1>}
        {operation.description && <ReactMarkdown>{operation.description}</ReactMarkdown>}
      </div>

      {/* Parameters */}
      {operation.parameters?.length > 0 && (
        <div>
          <h2 className="text-lg font-semibold mb-3">Parameters</h2>
          <table className="w-full text-sm border rounded-lg overflow-hidden">
            <thead className="bg-gray-50 text-left">
              <tr>
                {["Name", "Type", "In", "Required", "Description"].map((h) => (
                  <th key={h} className="px-4 py-2 text-xs uppercase font-semibold">{h}</th>
                ))}
              </tr>
            </thead>
            <tbody className="divide-y">
              {operation.parameters.map((param, idx) => (
                <tr key={idx}>
                  <td className="px-4 py-2"><code className="text-blue-600">{param.name}</code></td>
                  <td className="px-4 py-2 font-mono text-xs">{param.schema?.type || "any"}</td>
                  <td className="px-4 py-2"><span className="px-2 py-0.5 bg-blue-50 text-blue-700 rounded text-xs">{param.in}</span></td>
                  <td className="px-4 py-2">
                    {param.required
                      ? <span className="px-2 py-0.5 bg-red-100 text-red-700 rounded text-xs">Required</span>
                      : <span className="text-gray-400 text-xs">Optional</span>}
                  </td>
                  <td className="px-4 py-2 text-gray-600">{param.description || "-"}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      )}

      {/* Request Body */}
      {operation.requestBody && (
        <div>
          <h2 className="text-lg font-semibold mb-3">Request Body</h2>
          <div className="border rounded-lg p-4 space-y-2">
            {operation.requestBody.required && (
              <span className="px-2 py-0.5 bg-red-100 text-red-700 rounded text-xs">Required</span>
            )}
            {operation.requestBody.description && (
              <ReactMarkdown>{operation.requestBody.description}</ReactMarkdown>
            )}
            {operation.requestBody.content && (
              <div className="flex gap-2 flex-wrap">
                {Object.keys(operation.requestBody.content).map((type) => (
                  <code key={type} className="px-2 py-1 bg-gray-50 border rounded text-xs">{type}</code>
                ))}
              </div>
            )}
          </div>
        </div>
      )}

      {/* Responses */}
      {operation.responses && (
        <div>
          <h2 className="text-lg font-semibold mb-3">Responses</h2>
          <div className="space-y-3">
            {Object.entries(operation.responses).map(([code, response]) => (
              <div key={code} className="border rounded-lg p-4">
                <div className="flex items-center gap-3">
                  <span className={`px-2 py-1 rounded text-sm font-bold ${getStatusColor(code)}`}>{code}</span>
                  <span>{response.description}</span>
                </div>
              </div>
            ))}
          </div>
        </div>
      )}

      {/* Metadata */}
      {(operation.operationId || operation.tags?.length > 0) && (
        <div className="pt-6 border-t flex gap-4 text-sm text-gray-500 flex-wrap">
          {operation.operationId && (
            <span>Operation ID: <code className="bg-gray-100 px-2 py-0.5 rounded">{operation.operationId}</code></span>
          )}
          {operation.tags?.map((tag) => (
            <span key={tag} className="px-2 py-0.5 bg-blue-50 text-blue-700 rounded">{tag}</span>
          ))}
        </div>
      )}

    </div>
  );
}

function getMethodColor(method) {
  const colors = { get: "bg-blue-100 text-blue-800", post: "bg-green-100 text-green-800", put: "bg-yellow-100 text-yellow-800", delete: "bg-red-100 text-red-800", patch: "bg-purple-100 text-purple-800" };
  return colors[method.toLowerCase()] || "bg-gray-100 text-gray-800";
}

function getStatusColor(status) {
  const code = parseInt(status);
  if (code >= 200 && code < 300) return "bg-green-100 text-green-800";
  if (code >= 400 && code < 500) return "bg-yellow-100 text-yellow-800";
  if (code >= 500) return "bg-red-100 text-red-800";
  return "bg-gray-100 text-gray-800";
}

The component is split into four sections:

parameters
request body
responses
metadata

Each is only rendered if the operation actually has that data. getStatusColor maps HTTP status code ranges to colors so 2xx responses look green, 4xx yellow, and 5xx red at a glance.

Step 8: Update CSS and Configure the Entry Point

Now, replace your viewer/src/index.css file so the project can use Tailwind CSS:
```
@import "tailwindcss";
```
Next, open your viewer/src/main.jsx file and add this at the top:
```
import { Buffer } from "buffer";
window.Buffer = Buffer;
```
The Buffer polyfill comes first, so it's available before any other imports load. Buffer is a Node.js built-in that isn't available in the browser by default. @apidevtools/swagger-parser relies on it internally, so without this polyfill, it would throw an error in the browser.
Importing it from the buffer package and assigning it to window.Buffer makes it globally available before anything else runs.

Congratulations! You have successfully built a CLI tool that translates OpenAPI specification files into multiple languages and provides a frontend to browse the documentation.

To test it, navigate to your cli folder and run this command:

node index.js serve

What Comes First When Writing Documentation—The Product or The Users?

Ademola Thompson — Sat, 31 May 2025 09:24:35 +0000

Many times when I’ve had to visit product documentation for clarity or an introduction to a product, I ended up spending far more time than I intended. Why? Because finding the information I needed was unnecessarily difficult.

Some documentation does a great job of explaining all the features of a product. But that’s all they do. It’s obvious they didn’t consider how users might actually interact with the product. Their goal was simply to write as much product information as possible, without bothering to ask how the user might need to use their product or how that should influence the design and development of the documentation.

On the other end of the spectrum, I’ve seen documentation that focused on users, but did it poorly. These docs often skimped on critical details. Important reference materials were missing. I once had to dig through a GitHub issue to find an answer that should have been right there in the docs.
Sure, navigation was clean and beginner guides were well done—but once you moved past the basics, there was very little value for experienced users who needed more technical depth or architectural insights.

In the first case, the writers probably thought: “Let’s list all our features so the users know everything about us.” But their navigation was weak, and the language they used was overly technical or niche.
Importantly, they ignored the core principle that technical writing is about breaking down complex ideas, not stacking them. But of course, one can’t expect much from an unstructured information wall attempting to play the role of documentation.

In the second case, the writers understood the importance of considering users, but didn’t identify which users. They treated all visitors the same, tailoring their docs to only one or two user types. Everyone else had to scavenge for information elsewhere.

How I would recommend solving either of these issues

First, writers need to understand that the first step to writing effective documentation is understanding the product. You can't help people effectively understand what you don't understand yourself.

The next step, however, IS NOT writing, nor is it deciding what documentation framework to use. The ideal next step should be understanding your users. This is the part where you do enough research about the prospective users of your product. Here, you need to take your time to develop user personas. Ask questions like:

Who is visiting my docs, and what do they need?
Who needs this specific feature, and how can I help them find it easily?
How do I support different user types within a single documentation system?

These questions matter. They help shape how your documentation actually serves people.

Only after understanding your users should you start thinking about frameworks and structure. As Fabrizio Ferri-Benedetti pointed out in a blog post, documentation frameworks are just content types. What matters more is the people you're creating that content for.

Documentation must be tailored to suit users' needs. I believe this is an absolute truth.

A Practical Guide to Translating & Localizing Your Web App: Using i18n and Lingo.dev

Ademola Thompson — Fri, 28 Feb 2025 18:19:25 +0000

When building web applications for a global audience, it is important to consider localization—the process of presenting your web application's content in the local language or dialect of your visitors. This can be achieved using i18n frameworks. However, relying solely on i18n frameworks can be overwhelming to manage, especially in fast-paced environments where features and content are frequently shipped.

Lingo.dev is an AI-powered localization tool that enables us to set up localization once and have it run on autopilot.

In this tutorial, we will build a simple web page in English and translate it to 2 other languages using Lingo.dev and i18next.

Prerequisites

To follow along with this tutorial, you should install NodeJS, and have a solid understanding of at least one front-end framework or library.

Setting Up Localization in a React Web App

In order to demonstrate how Lingo.dev works in this tutorial, we will build a simple landing page that translates from English to French and Spanish. You can find a demo of the finalized app on Netlify.

Since React is the most popular frontend framework, we’ll use it to build the demo. However, the same steps can be replicated across different frameworks.

1. Create a React Application

To create the React application in the demo, we’ll follow these steps:

Create a React project with Vite by running this command in your Command Line Interface (CLI):
```
 npm create vite@latest localization-app -- --template react
```
Next, run the following commands one after the other:
```
cd localization-app
npm install
```
Now, open up your project in VScode (or your preferred editor):
```
code .
```

Next, open your src/App.jsx file and replace it with the code below. It is a simple React component with some Tailwind CSS classes.

// src/App.jsx
export default function App() {
  return (
    <div className="font-sans text-gray-900 bg-gray-50 w-screen">
      {/* Hero Section */}
      <section className="bg-gradient-to-r from-blue-600 to-indigo-600 text-white text-center py-24 px-6">
        <h1 className="text-5xl font-extrabold">Deploy Faster, Pay Less</h1>
        <p className="mt-4 text-lg max-w-2xl mx-auto">
          A scalable, developer-friendly cloud hosting platform with seamless
          deployments.
        </p>
        <button className="mt-6 bg-white text-blue-600 hover:bg-gray-200 px-8 py-3 rounded-lg font-semibold shadow-md transition">
          Get Started
        </button>
      </section>

      {/* Features Section */}
      <section className="py-20 px-6 text-center bg-gray-900 text-white">
        <h2 className="text-3xl font-bold mb-8">Why Choose Us?</h2>
        <div className="grid md:grid-cols-3 gap-10">
          <div className="p-8 bg-gray-800 rounded-lg shadow-lg">
            <h3 className="text-2xl font-semibold">🚀 Fast Deployments</h3>
            <p className="mt-3 text-gray-300">
              Deploy your apps in seconds with zero downtime.
            </p>
          </div>
          <div className="p-8 bg-gray-800 rounded-lg shadow-lg">
            <h3 className="text-2xl font-semibold">💰 Affordable Pricing</h3>
            <p className="mt-3 text-gray-300">
              Pay only for what you use, with no hidden fees.
            </p>
          </div>
          <div className="p-8 bg-gray-800 rounded-lg shadow-lg">
            <h3 className="text-2xl font-semibold">
              📈 Scalable Infrastructure
            </h3>
            <p className="mt-3 text-gray-300">
              Seamless auto-scaling to handle any workload.
            </p>
          </div>
        </div>
      </section>

      {/* Pricing Section */}
      <section className="bg-gray-100 py-20 px-6 text-center">
        <h2 className="text-3xl font-bold mb-8">Pricing Plans</h2>
        <div className="grid md:grid-cols-3 gap-10">
          <div className="p-8 bg-white rounded-lg shadow-md border border-gray-200">
            <h3 className="text-2xl font-semibold">Basic</h3>
            <p className="mt-3 text-gray-700 text-lg">$5/month</p>
          </div>
          <div className="p-8 bg-white rounded-lg shadow-md border border-gray-200">
            <h3 className="text-2xl font-semibold">Pro</h3>
            <p className="mt-3 text-gray-700 text-lg">$15/month</p>
          </div>
          <div className="p-8 bg-white rounded-lg shadow-md border border-gray-200">
            <h3 className="text-2xl font-semibold">Enterprise</h3>
            <p className="mt-3 text-gray-700 text-lg">Custom Pricing</p>
          </div>
        </div>
      </section>
    </div>
  );
}

Now it is time to install and configure Tailwind CSS for styling. Run the following command in your CLI to install Tailwind CSS:

npm install tailwindcss @tailwindcss/vite

Open up vite.config.js in your text editor and replace it with the following:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

Next, we’ll include this at the top of our src/index.css file:

@import "tailwindcss";

Now we can visit our page in the browser. Run the following command and visit http://localhost:5173/ to view the web page:
```
npm run dev
```
Your web page should look like the image above.

Now that we have our React application, it is time to modify it for localization and translations.

2. Install Localization Dependencies

In this section, we will translate our previous web page to French and Spanish. The first step to achieve this is to install the i18next and react-i18next packages. i18next is an internationalization framework that makes localization possible for JavaScript, and react-i18next is specifically for React.

Run the following command in your CLI to install the dependencies:

npm install react-i18next i18next

3. Create Translation Files

After installing our dependencies (i18next and react-i18next), we need to create translation files. Translation files allow us to store key-value pairs for different languages. They basically contain the same information in different international languages. For example, we might have:

en.json for English translations
fr.json for French translations

To create translation files we should do the following:

Create a i18n folder in our root directory.
Open the i18n folder and create the following files:

a. en.json

b. fr.json

c. es.json

Follow the steps below to add the right JSON objects to your translation files:

Paste the following JSON object in your en.json file:

{
  "hero": {
    "title": "Deploy Faster, Pay Less",
    "subtitle": "A scalable, developer-friendly cloud hosting platform with seamless deployments.",
    "cta": "Get Started"
  },
  "features": {
    "title": "Why Choose Us?",
    "fastDeploy": {
      "title": "🚀 Fast Deployments",
      "description": "Deploy your apps in seconds with zero downtime."
    },
    "affordablePricing": {
      "title": "💰 Affordable Pricing",
      "description": "Pay only for what you use, with no hidden fees."
    },
    "scalableInfra": {
      "title": "📈 Scalable Infrastructure",
      "description": "Seamless auto-scaling to handle any workload."
    }
  }
}

The JSON object represents key-value pairs for the content in our web page. For example, to write “Deploy Faster, Pay Less“ on our web page, we will access it with hero.title.

Now, we’ll paste the same JSON object for French and Spanish in their respective files.

For French (i18n/fr.json), paste the following:

{
  "hero": {
    "title": "Déployez plus vite, payez moins",
    "subtitle": "Une plateforme d'hébergement cloud évolutive et conviviale pour les développeurs, avec des déploiements fluides.",
    "cta": "Commencer"
  },
  "features": {
    "title": "Pourquoi nous choisir ?",
    "fastDeploy": {
      "title": "🚀 Déploiements rapides",
      "description": "Déployez vos applications en quelques secondes sans temps d'arrêt."
    },
    "affordablePricing": {
      "title": "💰 Prix abordables",
      "description": "Payez uniquement ce que vous utilisez, sans frais cachés."
    },
    "scalableInfra": {
      "title": "📈 Infrastructure évolutive",
      "description": "Mise à l'échelle automatique fluide pour gérer toute charge de travail."
    }
  }
}

For Spanish (i18n/es.json), paste the following:

{
  "hero": {
    "title": "Despliega más rápido, paga menos",
    "subtitle": "Una plataforma de alojamiento en la nube escalable y amigable para desarrolladores con implementaciones sin problemas.",
    "cta": "Comenzar"
  },
  "features": {
    "title": "¿Por qué elegirnos?",
    "fastDeploy": {
      "title": "🚀 Despliegues rápidos",
      "description": "Despliega tus aplicaciones en segundos sin tiempo de inactividad."
    },
    "affordablePricing": {
      "title": "💰 Precios asequibles",
      "description": "Paga solo por lo que usas, sin cargos ocultos."
    },
    "scalableInfra": {
      "title": "📈 Infraestructura escalable",
      "description": "Escalado automático sin problemas para manejar cualquier carga de trabajo."
    }
  }
}

4. Initialize and Configure i18next For Translations

We need to configure i18next in our React app for translations to happen.

First, we must create a file called i18n.js for configuration. Second, we need to modify our main.jsx file to use the I18nextProvider. The following steps will help us achieve this.

In our root directory, let’s create a i18n.js file to handle translations and initialise it with React. Paste this code into your i18n.js file:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";

// import translation files
import en from "./i18n/en.json";
import fr from "./i18n/fr.json";
import es from "./i18n/es.json";

i18n.use(initReactI18next).init({
  resources: {
    en: { translation: en }, // this tells it to use our en.json file (imported as en) for English translations.
    fr: { translation: fr },
    es: { translation: es },
  },
  lng: "en",
  fallbackLng: "en",
  interpolation: { escapeValue: false }, // this helps to avoid unnecessary HTML escaping
});

export default i18n;

Open your main.jsx file and replace it with this code:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import { I18nextProvider } from "react-i18next";
import i18next from "i18next";
import App from "./App.jsx";
import "../i18n.js"

createRoot(document.getElementById("root")).render(
  <StrictMode>
    <I18nextProvider i18n={i18next}>
      <App />
    </I18nextProvider>
  </StrictMode>
);

5. Modify Your React Component For Translations

We need to update our React component to use the translation configurations we set up in previous steps. Since our component is in the App.jsx file, open up the file and follow the steps below:

Import the useTranslation hook into your App.jsx file:

import { useTranslation } from "react-i18next";

Initialize the useTranslation as shown below:
```
const { t } = useTranslation();
```

Now we can use the JSON object we created in our translation files. For the hero title, we will do this:

<h1 className="text-5xl font-extrabold">{t("hero.title")}</h1>

We will use a similar pattern for other text content in our component. The final result of our code will look like this:

import { useTranslation } from "react-i18next";

export default function App() {
  const { t } = useTranslation();
  return (
    <div className="font-sans text-gray-900 bg-gray-50 w-screen">
      {/* Hero Section */}
      <section className="bg-gradient-to-r from-blue-600 to-indigo-600 text-white text-center py-24 px-6">
        <h1 className="text-5xl font-extrabold">{t("hero.title")}</h1>
        <p className="mt-4 text-lg max-w-2xl mx-auto">{t("hero.subtitle")}</p>
        <button className="mt-6 bg-white text-blue-600 hover:bg-gray-200 px-8 py-3 rounded-lg font-semibold shadow-md transition">
          {t("hero.cta")}
        </button>
      </section>

      {/* Features Section */}
      <section className="py-20 px-6 text-center bg-gray-900 text-white">
        <h2 className="text-3xl font-bold mb-8">{t("features.title")}</h2>
        <div className="grid md:grid-cols-3 gap-10">
          <div className="p-8 bg-gray-800 rounded-lg shadow-lg">
            <h3 className="text-2xl font-semibold">
              {t("features.fastDeploy.title")}
            </h3>
            <p className="mt-3 text-gray-300">
              {t("features.fastDeploy.description")}
            </p>
          </div>
          <div className="p-8 bg-gray-800 rounded-lg shadow-lg">
            <h3 className="text-2xl font-semibold">
              {t("features.affordablePricing.title")}
            </h3>
            <p className="mt-3 text-gray-300">
              {t("features.affordablePricing.description")}
            </p>
          </div>
          <div className="p-8 bg-gray-800 rounded-lg shadow-lg">
            <h3 className="text-2xl font-semibold">
              {t("features.scalableInfra.title")}
            </h3>
            <p className="mt-3 text-gray-300">
              {t("features.scalableInfra.description")}
            </p>
          </div>
        </div>
      </section>
    </div>
  );
}

Save your files, restart your server by running npm run dev, and view your page in the browser. It will still look the same. This is because we set the primary language to English in our i18n.js file. Let us change this to French.

Open your i18n.js file and look for this line of code:

lng: "en",

Change it to this:

lng: "fr",

Now, save your file and refresh your page on the web browser. Your page will look like this:

Congrats! You have successfully localized your web app to French. To translate it to Spanish, you can update your i18n.js file like this:

lng: "es",

6. Switch Languages Dynamically

To improve the user experience of our app, we will create a simple language switcher to allow users to switch languages at will.

In your src folder, create a new file and call it LanguageSwitcher.jsx.

Open the new file and paste this code in it:

import { useTranslation } from "react-i18next";

const LanguageSwitcher = () => {
  const { i18n } = useTranslation();

  return (
    <select onChange={(e) => i18n.changeLanguage(e.target.value)}>
      <option value="en">English</option>
      <option value="fr">Français</option>
      <option value="es">Español</option>
    </select>
  );
};
export default LanguageSwitcher;

The piece of code is a dropdown button. It sets the language by using i18n.changeLanguage

Open your App.jsx file and add this import statement:

import LanguageSwitcher from "./LanguageSwitcher";

Still in your App.jsx file, add this piece of code right before the hero section:

{/* Language switcher */}
      <div className="p-4 text-right">
        <LanguageSwitcher />
      </div>

Now save your file, restart your server, and view the page on the browser. It will look like this:

You can test the language switcher by selecting different languages. If you face any issues, you can go back a few steps to catch your error.

Localizing & Translating a Web Application With Lingo.dev

From the example above, it is clear that we will run into maintenance problems if we decide to scale our app or to support more languages.

We will quickly get overwhelmed if we have to manage multiple translation files for the same project. With Lingo.dev, we only need to manage one translation file. Lingo will handle the translation to different languages while preserving the context of the original language. In this section, we will learn how to localize our React app with Lingo.

1. Create an Account on Lingo.dev

Visit Lingo.dev’s official website to create a hobby account and log in. This account will allow you to translate up to 10,000 words per month, for free.

2. Delete Tranlation Files

Since Lingo will handle automatic file translations, we no longer need to manually manage the fr.json and es.json files. Open your i18n folder and delete them.

3. Authenticate Your React App With Lingo

For Lingo to work in our React app, we need to perform authentication by running the command in a CLI:

npx lingo.dev@latest auth --login

When you run the command above for the first time, it will request to install Lingo, type “y” into the CLI to proceed. After that, you should follow the instructions in the CLI to continue the login process.

If you follow the instructions, the page below should open in your browser. Click the Grant access button to complete the process.

If you are on a Windows machine, the above command might not work for you because npx lingo.dev@latest auth --login will try to run a bash script, which can cause problems on Windows.

To fix this issue, you should try running the command inside the Git Bash terminal or Windows Subsystem for Linux (WSL). Ensure that you run it from your project directory.

For WSL, open up your WSL instance and navigate to your project directory like this:

cd /mnt/c/Users/yourUsername/path/to/project

Once you are in, you can run the authentication command above.

4. Initialize Lingo.dev in Your React App

Now, we need to initialize Lingo.dev in our project. We can do that by running the command below:

npx lingo.dev@latest init

The command above will ask you a series of questions listed below:

Source locale: Type “en” to select English.
List of target locales: You should type “fr es” for Lingo to translate to French and Spanish.
Type of bucket: Select JSON for this option
Select the path to use: Type space to select our i18n folder and then enter to proceed.

Lingo will ask if you want to configure it for CI/CD. Type “n” to select no. It will also give you the option to view the official Lingo.dev documentation.

If you view your project in VScode, you will notice that Lingo.dev has created a new file called i18n.json in your root directory. This file is important for Lingo.dev to work properly.

5. Run Lingo.dev

Now that we are done with the configurations, we can run Lingo.dev in our project. Run the command below in your terminal:

npx lingo.dev@latest i18n

The command above will create all our translation files. If you open the i18n folder, you will find the es.json and fr.json files back in it. So whenever we need to update our app, we only need to do it in one file and run the above command.

You can view the web page on the browser. The result will be the same, but we achieved it with less effort.

Conclusion

Congratulations! You have successfully created a web page and translated it to both French and Spanish by using Lingo.dev.

Lingo.dev has a lot of potential and features. I recommend taking some time to understand the platform and try building cool things with it.

Resources

You can use the following resource(s) to keep learning:

If you end up building something cool with Lingo, be sure to tag me. Cheers!

[Boost]

Ademola Thompson — Thu, 09 Jan 2025 12:52:45 +0000

Understanding User Needs in Technical Writing: How Frameworks Like Diátaxis Help

Ademola Thompson ・ Jan 8

#techtalks #documentation #writing #diataxis

Understanding User Needs in Technical Writing: How Frameworks Like Diátaxis Help

Ademola Thompson — Wed, 08 Jan 2025 12:07:47 +0000

Success in technical documentation is often measured by how helpful a document is to the end user (or reader). Many technical documents have a section on each page for users to give feedback and suggestions on improving the document. This shows that the primary focus of any technical documentation should be the user.

In this article, we will explore why the end user is so important, how to put their needs first when writing, and how the Diátaxis principle is helpful in such cases.

Understanding User Needs in Technical Documentation

In technical documentation, it is important to understand the needs of your users because your ability to meet these needs will have an impact on the overall success of your documentation.

Put broadly, your users are individuals who use or consume your documentation to gain a better understanding of your product, which may include developer tools, APIs, consumer apps, or even hardware products. These users' needs consist of everything that contributes to helping them understand the documentation and use it to achieve some goals. This can be anything from navigation to the content of the documentation itself.

Despite the broad definition of users above, it is very important to define your target audience and categorize them into primary, secondary, and tertiary targets (or users) and create their user personas as the case may be. Doing this will allow you to think about the possible needs of each category and attempt to solve them.

The needs of your users can also be linked to their intent. Some might only be interested in reference materials, while others might be interested in how-to guides and tutorials. It is very important to create a distinction between these and organize them in easy-to-find ways for your users.

What Is Diátaxis and How Can It Satisfy User Needs

Diátaxis is a framework that focuses on building documentation around the user’s needs. The principles of Diátaxis divide documentation into four categories: tutorials, how-to guides, explanations, and references.

Diátaxis provides solutions related to documentation content, the style or approach to writing the content, and how to organize it for users to find easily.

Many documentation mixes tutorials with how-to guides and places them in places that appear random to the user. This can sometimes make it difficult for the user to navigate the documentation and find answers to their questions.

Diátaxis proposes a solution to this problem by suggesting that you should organize documentation based on the four main categories: tutorials, how-to guides, explanations, and references. This means that all forms of tutorials should be organized together, same with reference materials and the others.

Diátaxis is gaining popularity fast, and many organizations like Canonical have adopted it for their documentation.

Applying Diátaxis for Your Documentation

At its core, Diátaxis defines four categories of documentation: tutorials, how-to guides, explanations, and references. Once you understand how Diátaxis defines and differentiates these categories, you should be able to apply them when building your documentation.

Tutorials

According to Diátaxis, the aim of any tutorial is to help the reader acquire skills and knowledge through practical learning. It is much more about what the reader learns than what they do during the tutorial. For example, if you have to write a tutorial on building a CRUD API in Golang, your aim will most likely be to help the reader learn CRUD as a concept; Golang is just a way for you to help them visualize it.

As much as Diátaxis emphasizes that tutorials should be about what the readers learn and not necessarily what they are doing during the tutorial, it clearly states that you should avoid over-explaining. This is a trap many writers fall into, including myself.

In tutorials, you should aim to give the readers clear, specific instructions and avoid going too deep into concepts that are not directly tied to the aim of the tutorial. If there are multiple ways of doing the same thing, a tutorial is not the best place to say that. Simply focus on giving clear instructions to achieve a goal.

When writing a tutorial, you should also aim to give the readers clear expectations. For instance, at the beginning of your tutorial, you might say something like, “In this tutorial, we will learn how to Deploy a Django application to an AWS EC2 instance“. Declaring this tells your reader exactly what to expect.

Also, in tutorials, you should try to give your readers a sense of doing. You can do this by showing them clear, expected outputs based on some previous steps. This will help them know if they are on the right path or need to repeat a previous step.

How-To Guides

Diátaxis explains that how-to guides are wholly distinct from tutorials. Although they have many similarities, the difference lies in the user needs they serve.

Tutorials focus on helping the user learn and acquire basic competence by giving step-by-step instructions to accomplish a specific goal. On the other hand, how-to guides focus on helping the already competent user achieve a specific goal.

How-to guides usually assume that the user has a good knowledge of the product or technology so it cuts out the noise and focuses squarely on showing the user how to accomplish a task.

How-to guides understand that things won’t always go smoothly for the user in a real-world scenario, so they are usually adaptable to multiple situations. A how-to guide should be useful and applicable in different scenarios and not just a single scenario.

A good title for a how-to guide might be How to Configure a MySQL Database for a Flask Application. This title goes straight to the point. It is safe to assume that the user knows how to use Flask and has configured a different database for it before. The guide can safely cover multiple ways to configure the database without worrying about other unnecessary details like setting up a Flask application from scratch.

Reference Guides

Reference guides are usually information-oriented. They often contain technical details or descriptions of the product.

The Diátaxis documentation likens a reference guide to a map. When you look at a map, it might immediately tell you about a lake in some place, but it doesn’t give you too much information such as how the lake got there or if a Mr. John has a building close to it. The map simply shows you the layout of the landscape to help you efficiently navigate it.

Reference guides such as API references should be like a map. They should mention the necessary details such as the endpoints, required and option fields, response examples, etc but other explanations should be kept for a different guide.

Explanations

The goal of explanation guides is to impart the user with understanding of a product or tool. An explanation guide is at liberty to explain how a part of your product connects to another or how a specific part of your tool works under the hood. The idea is to help your users truly understand what the product does on a technical level

For example, if you have a payment platform, you can have explanation materials to explain how your transfer system works under the hood and what the developer needs to do in order to properly integrate it. Things like creating a recipient or a quote to properly make a transfer should come under explanations.

Conclusion

The Diátaxis framework is a really useful tool if you can apply it properly to your documentation. It can get confusing really quickly when you follow the principles for the first time, but you should be good after a few attempts.

Can you guess what kind of article this is? Reference, explanation, tutorial or how-to? Let’s discuss it in the comments!

Resources

You might find the following resources useful in your journey to understand Diátaxis and apply its principles:

Cover Image Credit: Diátaxis’ official documentation

Python Telegram Bot Starter Kit: Your Express Route to Bot Development

Ademola Thompson — Mon, 02 Sep 2024 01:25:40 +0000

This is a submission for the Neon Open Source Starter Kit Challenge : Ultimate Starter Kit
image credit: Gemini AI

My Kit

My kit is a Telegram Bot Starter Kit built in Python. It provides a robust foundation for developers to quickly create Telegram bots with advanced features and optional database integration.

Key Features

These are some of the key feature of the Telegram Bot Starter Kit.

Modular Architecture: The kit is structured for easy extension and maintenance, allowing developers to add new features without interfering with existing functionality.
Optional Database Integration: Built-in support for SQLAlchemy, allowing developers to easily integrate database functionality when needed. The database can be toggled on/off via an environment variable.
Command Handling: Pre-built command handlers for common functions like /start, with an easy-to-follow pattern for adding new commands.
Logging and Decorators: The kit I=includes a custom decorator for logging command usage, enhancing debugging and user analytics.
Echo Functionality: Built-in echo handler for non-command messages, providing a base for building conversational bots.

This Telegram Bot Starter Kit empowers developers to focus on creating unique bot functionalities rather than worrying about boilerplate code and architecture.
Whether you're building a simple echo bot or a complex application with database integration, this kit provides the perfect starting point for your Telegram bot journey.

Link to Kit

You can find the Telegram Bot Starter Kit in my GitHub repository:
Telegram Bot Starter Kit

My Journey

The idea for this Telegram Bot Starter Kit came from a very practical place - my own struggles with creating and structuring a Telegram bot. I was working on a personal bot project, and found myself grappling with questions about project structure, best practices, and how to integrate various features, especially because it was my first time. At the end of the project, my code was very messy, so I decided to build something to help with future Telegram bot projects.

I chose to build this kit in Python for a couple of key reasons:

Personal Comfort: Python is a language I'm comfortable with, which made it easier to focus on the bot-specific challenges rather than language intricacies.
Gap in Resources: While searching for help, I noticed that there were starter kits available for other languages like JavaScript, but I couldn't find a comprehensive one for Python.

Lessons Learned

Some of the things I learned while building the kit.

Bot Structure: I gained a deep understanding of how to structure a Telegram bot project for maintainability and extensibility. This included organizing handlers, utilities, and configuration in a logical manner.
Database Integration: Implementing optional database functionality taught me how to create flexible architectures that can accommodate different user needs - from simple bots to more complex, data-driven applications.

Challenges

One of the most challenging aspects was deciding what features to include in the starter kit. I wanted to provide enough functionality to be immediately useful, while keeping it simple enough for easy customization. This required carefully considering what elements are essential for most Telegram bots.

Conclusion

This project, while relatively straightforward, taught me a lot about the process of creating a bot from scratch. It helped me organize my thoughts and approach to bot development, and I hope it will do the same for others.

A Practical Approach to Unit Testing in Django REST Framework

Ademola Thompson — Fri, 05 Apr 2024 10:27:24 +0000

More often than not, you would encounter a bug when your app is in production. Sometimes the bug is easy to fix, sometimes it’s not. But many times, after shipping the fix, you realize that a different part of your app is broken.

This is very common for developers. However, it is possible to automate your code to catch new errors that might arise from fixing different errors. You do this by writing tests.

In programming, writing tests is a way to ensure that your code works as expected, and when it doesn’t work as expected, you will have all the information you need to track down the bug without wasting time.

Django REST Framework is a high-level Python framework that allows you to write REST APIs with relatively minimal stress. When you build APIs, it is important to write tests that will ensure your endpoints behave as expected.

In this tutorial, you will learn about the different types of testing, and how to write unit tests; the most basic form of tests.

As a developer, you should learn how to write tests because they improve the quality of your code.

Prerequisites

This article assumes that you already have adequate knowledge of the following concepts:

Python and general programming concepts
Django concepts such as apps, projects, folder structure, etc.
Concepts of Django REST Frameworks such as views, serializers, and URLs.

Types of Tests in Software Development

In software development, there are different types of tests that you can write. Each one serves its purpose. It is important to understand the different types of tests so you can decide which one to write given a particular scenario.

Generally speaking, there are two broad categories of tests in software development:

Functional tests: These types of tests help you ensure the functionalities of your app are working well. For example, you might want to test whether an API endpoint returns the right status code or response body. You might also want to test if your custom model methods are working properly.
Non-functional tests: These tests focus on other important parts of your app such as performance, usability, and security.

This tutorial focuses mainly on functional tests. These are some of the most popular functional tests in software development. While there are other types of tests, these are very popular among developers and software teams.

Unit Tests

Unit tests are the most basic forms of functional testing. Writing unit tests involves testing the individual components or units of your application to ensure they exhibit expected behavior.

In unit testing, your focus will be to ensure that your app's individual parts (or units) do their jobs as expected. You don’t have to worry about how they interact with each other. A unit can be anything from a function to a class in your program.

Integration Tests

Integration tests check if two or more components or modules of your application relate to each other properly. For example, in an e-commerce application, you will have multiple modules such as the product catalog, shopping cart, and payment gateway.

An integration test for this scenario will be to ensure that when a product is added from the product catalog, it reflects properly in the user’s shopping cart.

Regression Tests

Regression tests aim to prevent your code from breaking after you make changes to it. For instance, if you update a certain feature, a regression test will check to ensure this update does not affect other features of your app.

End-to-End Tests

End-to-end tests aim to test every aspect of your software from beginning to end. This kind of test aims to simulate a user’s interaction with your software or app and ensure there are no errors.

For instance, if you have a social media application, an end-to-end test will test the entire flow from user onboarding to creating posts and interacting with other people’s posts.

How to Write Unit Tests in Django REST Framework

There are multiple ways to write unit tests in Django REST Framework (DRF). One way is to use the built-in testing architecture provided by DRF. Although this method is effective, it does not offer much ability for customization. This means if you have a unique testing requirement, you might face some problems getting it done easily.

Another way to write unit tests in DRF is by using a 3rd party framework such as pytest-django. It offers more flexibility than DRF’s built-in test modules. The official documentation talks about why you should use pytest-django over DRF’s test modules.

The next steps will show you how to write unit tests using pytest-django and explain some of its concepts and features.

NOTE: All the code used in this tutorial is available on GitHub

Step 1: Install and Configure Pytest-Django for Your Project

Use this command to install pytest-django in your virtual environment:

pip install pytest-django

The command above will install pytest-django and all its dependencies into your project’s virtual environment. You don’t need to add anything to your installed apps in Django settings. After installation, you should follow these steps to configure your project for pytest-django:

Create a pytest.ini file. This file should be at the root of your project directory (where your manage.py file is located). The pytest.ini file is a configuration file that allows you to define the behavior or configurations of each test whenever you run them. Without a configuration file, you will have to define things like environment variables and whether or not you want to log information about your tests whenever you run them individually. This is time-wasting, so ensure you use the pytest.ini file.

For this tutorial, paste this code into your pytest.ini file:
```
[pytest]
DJANGO_SETTINGS_MODULE = core.settings
# -- recommended but optional:
python_files = tests.py test_*.py *_tests.py
log_cli = 1
log_cli_level = INFO
log_cli_format = %(asctime)s %(levelname)s %(message)s
log_cli_date_format = %Y-%m-%d %H:%M:%S
```
The code above defines the settings module that pytest-django should use for testing. It also defines the Python files for tests. Lastly, it defines how information should be logged during tests.

NOTE: Change the value of DJANGO_SETTINGS_MODULE to your project’s settings module.
Create a conftest.py file. The conftest.py file should be in the test directory of your app. You typically use this file to share something called fixtures, across different unit tests. Fixtures are functions that provide consistent and reusable setups for your tests. For instance, if you want to write multiple tests that involve creating user data, you can use fixtures to create the user data once and use it in any test file you want. The conftest.py file is not mandatory, but it is very necessary and effective.

Step 2: Adjust Your Project’s Folder Structure

After you set up pytest-django, you should adjust your project structure for ease. There are multiple ways to do this, and you can decide what works for you.

Django’s default folder structure looks similar to this:

project/
├─ manage.py
├─ project/
├─ app1/
│  ├─ tests.py
│  └─ ...
├─ app2/
│  ├─ tests.py
│  └─ ...
└─ ...

The structure above shows that Django provides a single test file within each app. You can decide to stick with this approach but it isn’t the best approach when you have a lot of scenarios and units to test. If you have to make changes to your test code, you might find yourself scrolling endlessly due to the large amount of code in the file. It’s better to look into more organized approaches.

One way to structure your project for tests is to have a base test folder at the same level as your manage.py file. This method is very useful when you have common utility functions that your different apps share. It also makes it easier to create test scenarios that require units from different apps. This is what such a structure will generally look like:

project/
├─ manage.py
├─ pytest.ini
├─ project/
├─ app1/
├─ app2/
├─ tests/
│  ├─ conftest.py
│  ├─ app1_tests.py
│  ├─ app2_tests.py

This method also has its disadvantages because the tests folder might become larger and more complex to maintain as your project grows. If you’re comfortable with this method, you can use it to structure your project for tests.

Another method to structure your project for tests is by creating a test folder inside each app. Your folder structure will look like this:

project/
├─ manage.py
├─ pytest.ini
├─ project/
├─ app1/
│  ├─ tests/
│  │  ├─ conftest.py
│  │  ├─ test_views.py
│  │  ├─ test_models.py
│  │  └─ ...
├─ app1/
│  ├─ tests/
│  │  ├─ conftest.py
│  │  ├─ test_views.py
│  │  ├─ test_models.py
│  │  └─ ...

The obvious advantages of this structure are modularity and isolation because each application has its unique tests within it and this allows for better code organization overall.

On the flip side, this structure will be limited if you have common utility functions to share between apps. You might have to rewrite the same logic multiple times.

The folder structure you should choose should always depend on your project needs. It is also important to take programming principles such as DRY into account.

Lastly, it is possible to create a combination of both structures in the same project if you have to. This way, app-specific tests are written within the apps, and tests that involve multiple apps are written outside the apps.

Whatever approach you choose, ensure you include a __init__.py file within the folder so it's treated as a Python package.

Step 3: Write Tests for Your Models

When writing tests, one of the questions you will often ask is, “What do I test?”, especially if you’re using a framework like DRF that has a lot of boilerplates and built-in features. The simple answer is to test every aspect of your own code, excluding functionalities provided as part of the Django REST Framework.

Consider this model for a project management API:

from django.db import models
from django.contrib.auth import get_user_model

User = get_user_model()

class Project(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField()
    start_date = models.DateField()
    end_date = models.DateField()
    team_members = models.ManyToManyField('auth.User', related_name='projects')

    def __str__(self):
        return self.name

    def get_project_duration(self):
        duration = self.end_date-self.start_date
        return duration.days

    def get_team_members_count(self):
        return self.team_members.count()

In the model above, you don’t need to write tests to ensure the name field is saved as a CharField or the start_date is saved as a date field, because they are built-in features of Django. You can be assured they will work as expected.

However, you should write a test to ensure the name field does not exceed 100 characters because it is your custom implementation. You should also write tests to ensure the custom methods in the model return the expected values.

These steps will show you how you can write tests for the model above:

Create a test_models.py file in your tests folder. This file will contain all the tests related to your models.

Create fixtures in your conftest.py file. In pytest-django, you define fixtures with the @pytest.fixture decorator. Here are two simple fixtures you can create:

# conftest.py
import pytest
from datetime import date
from django.contrib.auth import get_user_model
from projects.models import Project

User = get_user_model()

# create a user object
@pytest.fixture
def user() -> User:
    return User.objects.create_user(username="testuser", password="testpassword")

# create a project object
@pytest.fixture
def project() -> Project:
    return Project.objects.create(
        name='Test Project',
        description='Test project description',
        start_date=date(2024, 3, 1),
        end_date=date(2024, 4, 1),
    )

The code snippet above contains two fixtures. The first fixture is called user and it simply returns a newly created user instance.

The second fixture is called project and it creates a new object of the project model above.

NOTE: When you define a pytest fixture, you can pass the fixture as a parameter to any of your test functions. For instance, if you have a test that checks the get_project_duration method in your model, you can pass the project fixture as a parameter to your test function like this:

def test_get_project_duration(project) -> None: # use the project fixture as a parameter
    # write your code logic
    pass

Write tests to test the custom methods of your model. In testing, one of your primary assignments is to ensure that your methods or endpoints return the expected value or output. To write tests for the custom methods in the Project model, you should create a scenario that calls these methods with specific values, and then compare the output you get to the output you’re expecting. Here is a simple example:
```
# test_models.py
import pytest

@pytest.mark.django_db
def test_project_duration(project) -> None: # use the project fixture as a param
    assert project.get_project_duration() == 31

@pytest.mark.django_db
def test_team_members_count(project, user) -> None:
    project.team_members.add(user)
    assert project.get_team_members_count() == 1
```
In the above code snippet, the test_project_duration function uses the project fixture. This means it does not have to create a new project instance. Finally, it checks to see if the get_project_duration method returns the expected value of 31 since 2024-03-01 minus 2024-04-01 is 31 days (as defined in the project fixture).

If you’re having trouble grasping this, try revisiting the Project model and the project fixture to understand the logic.

The test_team_members_count function uses both the project and the user fixtures. First, it adds the created user as a team member and then it checks to ensure the count function returns 1 as the output since you have added only one user as a team member.

NOTE: The pytest.mark.django_db decorator simply tells pytest that the test requires a database to be set up.
Write a test for the character limit on the CharField. You want to ensure that the character limit of your name field is enforced by Django. This test is a bit tricky, so I suggest you try to write it on your own first to see how well you can get it done. Here’s a code snippet to test the character limit of the name field:
```
# test_models.py
import pytest

from django.core.exceptions import ValidationError
from projects.models import Project

@pytest.mark.django_db
def test_project_name_character_count(project) -> None:
    project.name = 'A' * 256  # update project name to exceed max_length constraint

    with pytest.raises(ValidationError) as e:
        project.full_clean()

    assert 'Ensure this value has at most 100 characters' in str(e.value)
```
Before explaining the code, you should understand how Django performs validation for character fields. Django performs validation with the full_clean method. If there is a violation of the character limit, it raises a ValidationError to alert you. The validation error often contains a message like, “Ensure this value has at most {max_length} characters”

The code snippet above attempts to recreate this scenario. First, it updates the project name to exceed the character limit. Next, it calls the full_clean method and raises a validation error if it fails. Finally, it checks the message of the validation error to confirm that it contains the right message. With these measures in place, your tests should work as expected.
Run your tests. You only need to type this command in your CLI to run your tests:
```
pytest
```
With that command, pytest-django will search for all the test files with the formats you have specified in your pytest.ini file:
```
python_files = tests.py test_*.py *_tests.py
```
If you have followed the above steps, you should see something like this in your terminal:

Step 4: Write Tests for Your POST and GET Endpoints

After writing tests for your models, you should write your views and test them properly. Here is a simple view for creating and listing projects:

from rest_framework.generics import GenericAPIView
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework import status

from .models import Project
from .serializers import ProjectSerializer

class ProjectListCreateView(GenericAPIView):
    serializer_class = ProjectSerializer

    def get(self, request:Request):
        projects = Project.objects.all()
        serializer = self.serializer_class(instance=projects, many=True)
        response = {
            "message":"successful",
            "data":serializer.data
        }
        return Response(data=response, status=status.HTTP_200_OK)

    def post(self, request:Request):
        serializer = self.serializer_class(data=request.data)

        if serializer.is_valid():
            serializer.save()
            response = {
                "message":"successful",
                "data":serializer.data
            }
            return Response(data=response, status=status.HTTP_201_CREATED)

        response = {
            "message":"failed",
            "data":serializer.errors
        }
        return Response(data=response, status=status.HTTP_400_BAD_REQUEST)

The code above is self-explanatory, so it's best to jump into writing tests for it. Ensure you create an appropriate serializer and URL pattern for your view. You can revisit the code on GitHub if you need to.

These steps will show you how to write the tests for the view above:

Open your conftest.py file, and paste these fixtures in it:

# conftest.py
from rest_framework.test import APIClient # new import

@pytest.fixture()  
def api_client() -> APIClient:  
    """  
    Fixture to provide an API client  
    """  
    yield APIClient()

@pytest.fixture
def project_payload(user) -> dict: # uses the user fixture
    return {
        "name": "New project",
        "description": "Test project description",
        "start_date": "2024-01-01",
        "end_date": "2024-02-01",
        "team_members": [user.id]
    }

The first fixture initializes the APIClient class in Django. This means you don’t have to manually initialize it whenever you want to test a new endpoint. The APIClient is a class that DRF provides to make testing easier.

The second fixture is called project_payload. It takes the user fixture as a parameter and returns sample data that you can use for testing operations such as POST requests.

Create a file called test_views.py to contain the tests related to your views. The approach to writing a test for the view defined earlier is pretty simple. First, you should send a POST request to the endpoint with data to create a new project. After doing this, you should check if your project has been created by comparing the received status code with the expected status code. You should also compare the fields from the project that gets created with the ones from your raw data. For instance, you can compare the name of the project. Finally, you should send a GET request to the right endpoint and repeat the same steps. Here’s what your test should look like:
```
# test_views.py
import pytest
import logging

logger = logging.getLogger(__name__)

@pytest.mark.django_db
def test_create_project(api_client, project_payload) -> None:
    # create a new project
    response_create = api_client.post('/api/project/', data=project_payload, format="json")
    logger.info(f"{response_create.data}")
    assert response_create.status_code == 201 
    assert response_create.data['data']['name'] == project_payload['name']

    # read the newly created project
    response_read = api_client.get('/api/project/', format="json")
    assert response_read.status_code == 200
    assert response_read.data['data'][0]['name'] == project_payload['name']
```
The test above utilizes both the api_client and project_payload fixtures.

The function makes a POST request to the endpoint using the data returned by the paroject_payload. It logs the information about the data created. After that, it compares the status code with the expected status code. In the view, a status code of 201 is sent after a successful POST request.

Next, it compares the name field of the newly created project with the name field of the data returned by the project_payload fixture. They have to be the same for the test to pass. The exact syntax you will use to access your fields depends on your API structure. For instance, the ProjectListCreateView defines the API structure like this:
```
{
    "message":"successful",
    "data": serializer.data
}
```
Therefore, to access any field, you should access the “data” key first. Here’s an example:
```
response_create.data['data']['name']
```
After confirming the POST action works as expected, the test sends a GET request and asserts both the status code and name field of the data in a similar fashion as done in the POST request.

Step 5: Write Tests for Your Update Endpoints

Writing tests for your update and delete endpoints follows a similar pattern as the previous tests. You should start by writing an appropriate view for your endpoint:

# views.py
class ProjectRetrieveUpdateDeleteView(GenericAPIView):
    serializer_class = ProjectSerializer

    def get(self, request:Request, project_id:int):
        project = get_object_or_404(Project, id=project_id)

        serializer = self.serializer_class(instance=project)
        response = {
                "message":"successful",
                "data":serializer.data
            }
        return Response(data=response, status=status.HTTP_200_OK)

    def patch(self, request:Request, project_id:int):
        project = get_object_or_404(Project, id=project_id)

        serializer = self.serializer_class(instance=project, data=request.data, partial=True)
        if serializer.is_valid():
            serializer.save()
            response = {
                "message":"successful",
                "data":serializer.data
            }
            return Response(data=response, status=status.HTTP_201_CREATED)
        response = {
            "message":"failed",
            "info":serializer.errors
        }
        return Response(data=response, status=status.HTTP_400_BAD_REQUEST)

    def delete(self, request:Request, project_id:int):
        project = get_object_or_404(Project, id=project_id)
        project.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

Ensure you have your URL pattern and serializer set up properly.

After creating your endpoint, you should start by writing tests for the update endpoint. The logic behind this is to first create a project like you did in the test_create_project test. After you create the project, you should update a part of your payload and then send a PATCH request with this updated payload. Next, you should assert things like the status code and the value of the updated payload.

Finally, you should write a test for the case where the URL returns a 404 error.

Here’s what your code will look like:

# test_views.py

@pytest.mark.django_db
def test_update_project(api_client, project_payload) -> None:
    # create a project
    response_create = api_client.post('/api/project/', data=project_payload, format="json")
    project_id = response_create.data["data"]["id"]
    logger.info(f"Successfullly created project with ID {project_id}")
    assert response_create.status_code == 201 
    assert response_create.data['data']['name'] == project_payload['name']

    # update the project
    project_payload["name"]="Updated project name"
    response_update = api_client.patch(f'/api/project/modify/{project_id}/', data=project_payload, format="json")
    new_title = response_update.data['data']['name']
    logger.info(f"Successfullly updated project with ID {project_id}")
    logger.info(f"new project title is {new_title}")
    assert response_update.status_code == 201 
    assert response_update.data['data']['name'] == project_payload['name']

    # project not found
    response_update = api_client.patch(f'/api/project/modify/{project_id+20}/', data=project_payload, format="json")
    assert response_update.status_code == 404
    logger.info(f"Cound not find project with id {project_id+20}")

Step 6: Write Tests for Your Delete Endpoint

The final endpoint to test is the delete endpoint. The logic behind this test is simple.

First, you create a new project using the project_payload fixture. Next, you delete the project by sending a DELETE request to the endpoint.

After you send the DELETE request, you should compare the outputs such as the status code. Next, you should check if the project was deleted by sending a GET request to retrieve the deleted project. This should return a 404 if everything works well.

Finally, you can decide to write a test for a scenario where the project was never found.

Here’s what the code will look like:

# test_views.py

@pytest.mark.django_db
def test_delete_project(api_client, project_payload):
    # create a project
    response_create = api_client.post('/api/project/', data=project_payload, format="json")
    project_id = response_create.data["data"]["id"]
    logger.info(f"Successfullly created project with ID {project_id}")
    assert response_create.status_code == 201 

    # delete project
    response_delete = api_client.delete(f"/api/project/modify/{project_id}/", data=project_payload, format="json")
    logger.info(f"Deleted task with ID {project_id}")
    assert response_delete.status_code == 204

    # Read the project to ensure it was deleted
    response_read = api_client.get(f"/api/project/modify/{project_id}/", format="json")
    assert response_read.status_code == 404

    # project not found
    response_delete = api_client.delete(f'/api/project/modify/{project_id+20}/', data=project_payload, format="json")
    assert response_delete.status_code == 404
    logger.info(f"Cound not find project with id {project_id+20}")

If you type the pytest command in your CLI, your tests will run and you should see something similar to this:

If you have followed this guide until now, congratulations! You should now have basic knowledge about writing unit tests in DRF. With some practice, you should be able to reproduce these steps easily.

How to Write Unit Tests For Endpoints That Require Permission

So far, this guide has taught you how to write tests for CRUD endpoints without any permission level. However, it is a good idea to know how to write tests for endpoints that require permissions.

To do this, edit the ProjectListCreateView view to include a permission class:

# views.py

from rest_framework.permissions import IsAuthenticatedOrReadOnly # new import

class ProjectListCreateView(GenericAPIView):
    serializer_class = ProjectSerializer
    permission_classes = [IsAuthenticatedOrReadOnly]

    ...

This new update means only authenticated users can send POST requests to the endpoint.

In your test, you have to find a way to authenticate a user whenever you create a post request. The easiest way to do this is by using the force_authenticate method available in the APIClient class DRF provides. Here’s an example of how your test should look like:

@pytest.mark.django_db
def test_create_project_authenticated(api_client, project_payload, user):
    # authenticate the user
    api_client.force_authenticate(user=user)

    # send a post request with the authenticated user
    response_create = api_client.post('/api/project/', data=project_payload, format="json")
    assert response_create.status_code == 201

In the above test, the force_authenticate method allows your test function to simulate a situation whereby an authenticated user is making the request. To run this test in isolation, you can use this command in your CLI:

pytest path/to/test_file.py::test_create_project_authenticated

If you’re using the code in the Github repo, your command should be this:

pytest projects/tests/test_views.py::test_create_project_authenticated

Now that you know how to write tests for endpoints with permissions, you can update your other test methods accordingly.

Conclusion

Writing tests for your code can be a bit challenging if you’re new to it. However, with regular practice and research, you should get comfortable with it after a while. This article has explained how to write unit tests for basic CRUD applications. You should build on this knowledge to write more complex tests.

When you write tests, always try to maintain good programming principles such as DRY, and SOLID. Ensure you avoid writing “dirty” test code at all costs.

Additional Reading

The following articles will help broaden your knowledge about writing tests in DRF with pytest-django:

How to build a Flask app with Neon serverless database

Ademola Thompson — Wed, 07 Feb 2024 16:09:53 +0000

Using a serverless database eliminates the common pain points related to server management, configuration, and scalability. With a serverless database, you can focus solely on building your app while a service manages your database.

Neon is a fully managed serverless Postgres, offering many innovative features, including branching and bottomless storage. Neon offers a generous free tier that allows you to create more than one database and up to ten branches of each database.

In this tutorial, we’ll use Neon and SQLAlchemy, an object-relational mapper (ORM) that allows you to create SQL queries directly without writing SQL codes. Since Neon supports many technologies, including SQLAlchemy, you can integrate both to build your Flask application. Let’s get started!

Why do you need a serverless database?

The most obvious advantage is that it gives you a seamless experience when setting up a database for your application. This is because you don’t have to bother setting up a database manually, giving you a more straightforward and user-friendly process.
With a serverless database, you can save time and focus on important aspects of your application. Some other advantages include the following:

Scalability: Serverless databases are equipped to handle the scaling of resources based on your application’s demands. This means that as your application grows, the database will handle the increased workload without manual intervention from you.
Cost efficiency: Using serverless databases can help you cut costs, as you only pay for what you use, unlike traditional databases that charge a fixed amount for resources you might not use.
Reduced operational overhead: Serverless databases remove the need for you to manually manage database infrastructure. This reduces the operational burden on developers since they don’t have to worry about database updates, backups, and scaling.

How to set up a serverless database for your Flask application

You can find the code used in this tutorial on GitHub.

The following steps will show you how to set up a Neon serverless database for your Flask app.

Step 1: Signup on Neon

Navigate to Neon’s sign-up page and create an account. Signing up with your GitHub account is better because it allows you to automatically grant Neon access to your GitHub repositories. Neon needs this access to work properly.

Step 2: Create a new project and database

After you sign up, Neon will prompt you to create a project and database. The page should look like this:

You should fill out the fields with names for your project and database. You can also select a Postgres version and server location of your choice. Once you’re done, click on Create project.

Step 3: Get your database credentials from Neon

After you create a project on Neon, you will see a page where you can obtain your database credentials. Neon has different syntax for the frameworks it supports, but it is preferable to stick to the default database URL for easy integration for your Flask app. Copy the database URL to a safe place.

After you get your database credentials, you can create a Flask project and connect it to your Neon database.

How to connect a Flask application to Neon serverless database

These next steps will show you how to create and connect a Flask application to a Neon database.

Step 1: Install Flask and other dependencies

To use Flask and Neon together, you’ll need to install three significant dependencies. You can install them by typing the following command in your command line interface (CLI):

pip install flask sqlalchemy psycopg2-binary

NOTE: You can install psycopg2 as an alternative to psycopg2-binary, especially for Mac and Linux OS.

Step 2: Create a Flask app

Create a new directory for your project, and create a file called app.py to serve as the base file for your project. Inside your new file, initiate your Flask application. Here’s a simple code snippet you can use:



#app.py
from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return "Home Page!"

You can run the above code by typing this command in your CLI:

flask --app app run --debug

The command above will work if your file name is app.py. Otherwise, you should follow this syntax:

flask --app your_file_name run --debug

If you run into any trouble, check out the official documentation for Flask.

Step 3: Connect your Flask app to Neon using SQLAlchemy

There are three steps involved in connecting your Flask app to Neon:

Import SQLAlchemy into your project.
Add your database URL to your app configuration.
Create a model and migrate it to the database.

Here’s what the code should look like:



#app.py
# Import SQLAlchemy
from flask_sqlalchemy import SQLAlchemy

# Add your database URL to create a database object.
app.config["SQLALCHEMY_DATABASE_URI"]= "your_database_url_from_neon"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
db = SQLAlchemy(app)

# Create a simple model
class Book(db.Model):
    book_id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String)

# Commit your model (table) to the database
with app.app_context():
    db.create_all()

The above code snippet configures the app to use your Neon database. It also creates a model called Book with only two fields, the ID and title, and commits them to the database.

NOTE: The value of app.config["SQLALCHEMY_DATABASE_URI"] should be the database URL you copied from Neon earlier. Also, remember that the database URL has your password encoded in it! While it’s fine to hardcode the connection string to get started quickly, you’ll want to store the database URL in an environment variable and import it like:

app.config["SQLALCHEMY_DATABASE_URI"]=os.environ.get('DATABASE_URL_ENV_VAR", "")

Neon will create a new table for your model with the new modification to your code. To view your new database table, follow the steps below:

Navigate to your project dashboard. Neon will redirect you to this page immediately after you create a project.
Click on the “Tables” option on the left pane.
Your new table will be on the page you get redirected to.

You can create another model if you want. It will appear on Neon in the same manner.

Step 4: Create an endpoint to populate your table

You can test your new table by creating an endpoint that performs operations on the table. An example is an endpoint that adds new objects to the table:



# app.py
from flask import request, jsonify # New imports

@app.route('/add_book', methods=['POST'])
def add_book():
    if request.method == 'POST':
        data = request.get_json()

        # Validate if the required fields are present in the request
        if 'title' not in data:
            return jsonify({'error': 'Missing title'}), 400

        title = data['title']

        # Create a new Book instance and add it to the database
        new_book = Book(title=title)
        db.session.add(new_book)
        db.session.commit()
        return jsonify({'message': 'Book added successfully'}), 201

The above code snippet creates a new endpoint (/add_book/) for your app. This endpoint takes the title of a new book and creates a new book instance in the database.

You can test this endpoint with a tool like Postman. Navigate to http://127.0.0.1:5000/add_book and make a post request, as shown in this image:

Next, check on Neon to confirm that your database has new data in it:

You can add as many items as you want. You can create other endpoints to edit, delete, or perform other actions on your database objects. Neon will help you visualize those changes directly.

How to branch your database in Neon

Neon allows you to branch your database like a repository on GitHub. This feature allows you to create a copy of your database and use it for testing purposes.

With branching, you can assign a copy of your database to different developers during the development phase of your app. This will make your work more organized and prevent database conflicts. It will also save you the cost of paying for different database services. The following steps will show you how to create and use a database branch in Neon:

Step 1: Create a new branch

Select Branches from the left pane of the Neon interface. After that, click on New Branch.

Next, fill out the form with the necessary information, such as the name of your branch. When you’re done, click on Create a branch.

Step 2: Test your branched database

After you create a new branch, you will see a modal containing the database credentials for your newly branched database. Copy the database URL:

Next, replace your database URL with the new one. This is the line of code you need to modify:
app.config["SQLALCHEMY_DATABASE_URI"]="your_new_database_url_from_neon"

Next, you can add items to the database with the endpoint you created earlier. To view your new item(s), navigate to the Tables section and switch to your new branch.

If you switch back to your first branch, it won’t contain the new data you added. This is useful for developers to work with their test data during development.

Streamline your Flask development with Neon

Building a Flask application will always be easier if you don’t have to worry about a custom database infrastructure. With a tool like Neon, you can use a Postgres database without requiring extensive configuration and manual setup. Depending on your project's requirements, you also get the luxury of writing little to no SQL queries.

The branching feature of Neon can also boost productivity if you are working with other team members who want to test out different data in the database.

Continue development on the Flask app to match your use case!

References

You can learn more about Flask, Neon, and SQLalchemy through these links:

Memory Management In Python

Ademola Thompson — Tue, 21 Feb 2023 15:23:51 +0000

Memory management means allocating and de-allocating memory resources for your data in a computer program. It is essential to software development because it affects your code or program's overall performance and efficiency.

In this article, you will learn Python's inner workings of memory management. You will understand concepts like Python memory manager, garbage collection, and reference counting. Whether you're a beginner in Python or an experienced developer, this article will provide a comprehensive overview of memory management in Python and help you make better decisions to optimize your code.

Importance Of Memory Management.

In programming, memory management allows your codes or programs to run effectively. Proper memory management will prevent your code from crashing or having memory leaks. Memory management is helpful for the following reasons:

Allocating memory for newly created objects.
De-allocating memory for objects that have been used. Once your program gets executed, the memory used will be de-allocated.

Simple mistakes like forgetting to de-allocate memory or which memory is currently in use can cause your program to lag and have serious performance issues. This is because the memory will be too full to run at top speed.

The Python Approach to Memory Management

Early programming languages like C and C++ required developers to manage memory by manually allocating and de-allocating memory when coding. This method is inefficient because sometimes, developers can unconsciously skip one of the processes and have problems with their program.

In Python, memory management is handled automatically by the Python memory manager. Similarly to other languages, the Python memory manager uses stack and heap memory.

Stack Memory: Stack memory stores temporary data, function calls, and references to objects stored in the heap memory. Read more about stack memory here.
Heap Memory: Heap memory stores objects and data that need to be in memory longer than stack memory. This article speaks more about heap memory.

This image gives a basic overview of what each memory stores in Python.

In Python, whenever a variable is created, the Python memory manager will check if there is an object with that same value in memory. If there is, the newly created variable will point to the existing object in memory instead of creating an entirely new object. For instance, consider the code snippet below:

age = 20
score = 20

In the program above, you'll expect both variables to have unique memory spaces because they serve different purposes. The Python memory manager will, however, not do this. Since both variables have the same value, the memory manager will create one object representing both references. This image gives a clear view:

To confirm this, make use of the id() function in Python like so:

From the code above, you can see that both variables have the same ID. It confirms the fact that they both reference the same object in memory. If another variable with the same value is created, it will reference the same object in memory. This approach is better than creating a new object in memory for each variable.

There are some things to note about this approach:

If one of the variables gets reassigned, it is moved to a different memory location. However, if its new value already has an object in memory, it is moved to that memory address.
Mutable data types such as lists are assigned different objects even if they contain the same items. This is because changes to one of such lists will affect the other list(s) if they are in the same memory location.

Garbage Collection in Python

Garbage collection is when objects not in use are removed from the memory periodically. The garbage collector automatically does garbage collection. The two ways to implement garbage collection in Python are:

Reference counting
Generational garbage collection

Reference Counting in Python.

Reference counting is an approach in memory management that keeps track of the number of times an object is referenced in memory. You reference an object whenever you assign a variable. Whenever you reference an object, the reference count increases by 1. This example will shed more light:

x = "This is my house!"
y = "This is my house!"
z = x

Since variables x, y, and z refer to the same values, they have the same memory location. However, the reference count of the variable x increases with every new assignment. You can get an object's reference count by using the sys.getrefcount() function available in the sys module. You can verify the reference count of the above code snippet below:

Some of the things you should note are:

The sys.getrefcount() function adds an extra reference to the count. This means if the initial reference of an object is 1, sys.getrefcount() will return 2.
If one of the variables is reassigned, the reference count will decrease by 1.
When the reference count reaches 0, the object is deallocated from memory.

You should read this article and this article for more information on reference counting.

Generational Garbage Collection

Generational garbage collection was a feature added in Python 2.0. Before this, Python used only reference counting to manage memory, but it needed a more efficient method to solve the issue of reference cycles.

When two objects in memory hold references to each other, it is called a reference cycle. If this happens, the reference count of the objects will not reach 0, and the memory not be free. The following is an example of how an object can get stuck in a reference cycle:

superheroes = ["Captain America","Superman","Batman"]

sidekicks = ["Bucky", "Jimmy Oslen", "Robin"]

superheroes.append(sidekicks)
sidekicks.append(superheroes)

del superheroes

print(sidekicks[-1])

In the code above, even after the variable, superheroes is deleted, it still has a reference in the memory. You can confirm this when you print the last element of the variable, sidekicks. The same thing will happen if sidekicks was deleted or if both variables get deleted. You can run the above code here:

The garbage collector is used to fix this issue. The garbage collector is a mechanism that detects reference cycles in Python and removes them.

The garbage collector cannot run always run because of the following reasons:

Nothing else in the program can run whenever the garbage collector is running until it is done. This behavior can make your code slow.
The garbage collector usually has no work to do because reference cycles are mostly observed in large projects only.

To use the garbage collector, you need to import it like this:

import gc

The garbage collector classifies Python objects into three categories called generations. Each of these generations has an object threshold count. The threshold count for each generation can be seen by using the gc.get_threshold() command.

import gc
print(gc.get_threshold())

After running this command, you will get three values. Each of these values represents the threshold count for each generation. In the image below, the first generation has a threshold of 700.

All objects start their lives in the first generation. The garbage collector is activated whenever the number of objects in any generation exceeds its threshold. This is the only time the garbage collector runs automatically.

If objects in a particular generation are not cleaned up because they still have references, they are pushed to the next generation. To manually activate the garbage collector, use the gc,collect() function.

import gc
gc.collect()

Conclusion.

You have learned about how Python handles memory management. Although Python automatically handles memory management, the garbage collector can slow down your program if you have a large script and many objects are being created.

To prevent this from happening, you should learn to optimize your code and manually call the garbage collector at intervals. You can learn more about memory management in Python with these links:

Heap memory - https://www.geeksforgeeks.org/what-is-a-memory-heap/
Stack memory - https://www.sciencedirect.com/topics/engineering/stack-memory
Garbage collector - https://docs.python.org/3/library/gc.html
Reference counting - https://betterprogramming.pub/a-guide-to-reference-counting-in-python-27334fc2e3c1
Reference counting - https://towardsdatascience.com/understanding-reference-counting-in-python-3894b71b5611

For more content like this, follow me on Hashnode and Twitter.

Solidity Arrays: How To Use Them In Your Smart Contracts.

Ademola Thompson — Sun, 01 Jan 2023 17:53:52 +0000

Overview

In programming, arrays are a fundamental type of data structure. When it comes to Solidity, they differ significantly from what you may be accustomed to in other programming languages.

In this article, we'll look at how to use both fixed and dynamic arrays in Solidity. We will examine the declaration, initialization, and manipulation of Solidity arrays as well as some of the key distinctions between Solidity arrays and those found in other programming languages. This lesson will arm you with the skills you need to use arrays successfully in your smart contracts, regardless of your level of Solidity experience.

What Is an Array?

An array in Solidity is a group of data of the same kind that are kept in orderly list form. There are two main ways to declare an array in Solidity. They are as follows:

Fixed Arrays
Dynamic Arrays

Fixed Arrays

In a fixed array, the size of the array is determined during its declaration. This size cannot be modified after the array has been created. This means that if you create an array to take in 5 values (i.e., the size of the array is 5), you cannot have 4 items or 6 items in the array. It has to be exactly five items.

Declaring or Initializing Fixed Arrays

Fixed arrays are declared or initialized in the following format: dataType = [arraySize in numbers] arrayName; Here are a few examples:

uint8[3] scores; //AN ARRAY OF 3 UNSIGNED 8-BIT INTEGERS
string[6] names; //AN ARRAY OF 6 STRINGS
bool[2] isJumping; //AN ARRAY OF TWO BOOLEANS

To add items to the initialized arrays, the simple format of arrayName[index] = value; is used.

NOTE: Indexes are used to access the values of arrays. Think of indexes as positions. The first index of an array in Solidity is 0.

As an example, consider the following:

scores[0] = 10; //ASSIGNS THE VALUE 10 TO THE FIRST ELEMENT OF THE ARRAY
scores[1] = 25; //ASSIGNS THE VALUE 25 TO THE SECOND ELEMENT OF THE ARRAY
scores[2] = 15; //ASSIGNS THE VALUE 15 TO THE THIRD ELEMENT OF THE ARRAY

In the above example, 3 values were added to the array, scores. Another way to assign values to fixed arrays is to add the values at the point of initialization. By making use of the above scores array, this is demonstrated below:

uint8[3] scores = [10, 25, 15];

What Makes Both Methods Different?

The first method of adding items to an array actually serves more than one purpose. It can be used to modify the values of the array as well. The second method simply serves as a way of adding initial values to the array. These values can still be modified by using the first method. Any of the methods can be used, depending on your use case.

NOTE: The values inside the arrays can be modified. This is not the same for the size of the array. It is constant.

When To Use Fixed Arrays.

Fixed arrays are to be used when the values of the array are already known and are constant. Only use them when you know the exact size of the array in advance.

Dynamic Arrays

As opposed to fixed arrays, dynamic arrays are not restricted to a particular size at compile time. The sizes of dynamic arrays can be changed at runtime without running into any issues. The sizes can easily be modified by making use of the push and pop methods. These methods cannot be used with fixed arrays.

Declaring Dynamic Arrays

To initialize a dynamic array, the data type of the array needs to be specified, but not the size of the array. The size of the dynamic array is stored as a separate variable. This is because the size of the array can grow or shrink when needed, during runtime.

When a dynamic array is created, Solidity allocates a block of memory to store the elements of the array, and also allocates a separate variable to store the size of the array. The size of the array is stored as a separate variable, rather than as part of the array itself.

To initialize a dynamic array, use the following format dataType[] arrayName;. Here is an example for reference:

string[] fruits; //CREATES AN ARRAY OF STRINGS

Modifying Dynamic Arrays

As mentioned earlier, dynamic arrays can be increased or decreased in size by making use of the push and pop methods. Let us see how they work.

`push` Method:

This method is used to add elements to an array, which ultimately increases its size. The push method takes in one parameter - the value that will be added to the array. This method can only be used to add items to the end of an array. Here is how it works:

fruits.push("Apples"); //ADDS THE VALUE, "Apples" TO THE END OF THE ARRAY
fruits.push("Bananas"); //ADDS THE VALUE, "Bananas" TO THE END OF THE ARRAY

//RESULTING ARRAY
fruits = ["Apples", "Bananas"];

Since the push method only adds items to the end of the array, a way has to be devised to modify values at specific positions. This is done by simply accessing the array by an index and giving it a value. Here is an example:

fruits[2] = "Pineapples"; //ADDS "Pineapples" TO THE THIRD POSITION OF THE ARRAY
fruits[0] = "Lemons"; //CHANGES THE FIRST VALUE OF THE ARRAY TO "Lemons"

//RESULTING ARRAY
fruits = ["Lemons", "Bananas","Pineapples"];

`pop` Method

This method is used to remove the last item of an array, which causes the array to reduce in size. Unlike the push method, it does not take any parameter. This makes sense because it only removes the last item of an array. Using the above fruits array, let us consider the following example:

fruits.pop(); //REMOVES THE LAST VALUE FROM THE FRUITS ARRAY

//RESULTING ARRAY
fruits = ["Lemons", "Bananas"];

fruits.pop() //REMOVES THE LAST VALUE FROM THE FRUITS ARRAY

//RESULTING ARRAY
fruits = ["Lemons"];

Just like with the push method, the pop method doesn’t give the flexibility to remove values at specific positions. This can be done with the delete keyword.

`delete` Keyword

The delete keyword is used to remove items from an array at a specified index or position. It can also be used to delete an entire array. Consider the following examples:

//DELETING ENTIRE ARRAY
string fruits[] = ["Lemons", "Bananas","Pineapples"]; //CREATE DYNAMIC ARRAY OF STRINGS
delete fruits; //DELETES ALL ITEMS FROM THE ARRAY

//DELETING ONE PART OF THE ARRAY
string fruits[] = ["Lemons", "Bananas","Pineapples"]; //CREATE DYNAMIC ARRAY OF STRINGS
delete fruits[1]; //DELETES THE SECOND ITEM IN THE ARRAY(INDEX 1)
//RESULTING ARRAY
fruits = ["Lemons", "Pineapples"];

Things To Note About The `delete` Keyword

Although the delete keyword reduces the size of the array by removing an item from it, it does not clear out the memory used by the item. This means that when you try to access the element by using the index, it will return its original value i.e. fruits[1]; will return "Bananas" which was previously deleted. The deleted item will continue to retain its memory unless it is overwritten.
Another thing to note is that the delete keyword only works on a dynamic array. Using it on a fixed array will yield some errors. 3.While using the delete keyword can get rid of items or arrays that we want, it can also cause fragmentation in the memory heap, leading to reduced performance and increased gas fees. The memory heap is a block of memory that is used to store data structures in Solidity. Fragmentation of the memory heap refers to gaps or holes in the heap as a result of the deletion of data structures such as arrays. It leads to increased gas fees and reduced performance because Solidity has to search for available blocks of memory when allocating new data structures.

Initializing Arrays With The `public` Access Modifier

In Solidity, declaring a variable or a function as public means that it should be visible and callable from outside the contract it was defined in. Using the public access modifier automatically creates a getter function for the variable that can be called from outside the contract to retrieve the value of the variable.

When you declare an array with the public access modifier, it looks like this: uint[] public a;. This type of declaration automatically creates a dynamic array of unsigned integers stored in memory and also creates a public getter function for the array that can be called from outside the contract to retrieve the value of the array.

Initializing an array with uint[] a; will create a dynamic array of unsigned integers but will not create a getter function for the array because state variables in solidity are private by default unless specified otherwise.

Differences Between Arrays In Solidity and Other Programming Languages.

Solidity arrays are stored in memory: In Solidity, arrays are stored in memory, not on the stack like in some other languages. This means that the memory layout of an array in Solidity is different from the memory layout of an array in a language like C or C++. In particular, the elements of an array in Solidity are not necessarily stored consecutively in memory, as they are in C or C++.
Solidity arrays are not always contiguous: In Solidity, the elements of an array may not always be stored consecutively in memory. For example, if you have a dynamic array of structs, the structs may be scattered throughout memory, with pointers to each struct stored in the dynamic array. This is because Solidity does not guarantee that the elements of an array will be stored consecutively in memory, as it does in languages like C or C++.
Solidity arrays are not always indexed by integers: In Solidity, you can create arrays that are indexed by any type of data, not just integers. For example, you can create an array of strings indexed by bytes32, or a mapping from uint to bool. This is different from languages like C or C++, which only allow arrays to be indexed by integers.

Conclusion.

In this article, we have been able to see the different types of arrays in Solidity and thing to consider when making use of them. We have also seen how arrays in Solidity differ from arrays in other programming languages. Feel free to like and comment your opinion or suggestions below. If you need any help, reach out via Twitter.

What does a tech stack mean?

Ademola Thompson — Sat, 06 Aug 2022 11:31:00 +0000

As a beginner starting in tech, it is easy to get confused about the issue of tech stacks. You don't grasp the concept properly despite hearing it from experienced individuals. Is it just front-end, back-end, and full-stack? Let's discuss that in this article.

What Is A Tech Stack?

A tech stack is a combination of technologies used to build an application. It is also known as a solutions stack.
A tech stack is usually a combination of programming languages, frameworks, libraries, databases, and other technologies needed to build an application. Most tech stacks combine front-end and back-end technologies to develop full-stack applications.
Web stacks can belong to one of three tech stacks. We have the front-end stack, the back-end stack, and the full-stack stack.

Front-end Stack

The front end of an application is the UI of the application when you look at it from a basic level. It is also called the client-side of an application.
It is the part of an application that users see and interact with. Things such as clickable buttons, comment boxes, e.t.c. are part of the front end of an application.
The front-end stack is the combination of technologies used to build the client-side of the application.

On a basic level, the front-end stack consists of HTML, CSS, and JavaScript. However, technologies such as ReactJS, AngularJS, VueJS, e.t.c. have been introduced to make the work easy and more scalable.

Back-end Stack

In an application, the back-end refers to the server side, responsible for providing data to the front end on request (this can be as 'simple' as clicking a button). Users do not have access to the back-end of the application.

Full-stack Stack

The full-stack stack is a combination of the front-end stack and the back-end stack. Most applications are full-stack applications.

You should notice already that a front-end stack isn't the same as a front-end role. It is also different from the definition of the front end of an app. The same thing goes for a back-end stack. Does this mean that choosing a front-end or back-end role isn't the same as picking your stack? You bet it does! Keep reading.

Are There Pre-defined Tech Stacks?

Now that you know what tech stacks are, you're probably wondering how to decide on a tech stack. To solve this, several efficient stack models exist for developers to decide on a tech stack for themselves. Let's discuss some of these stack models in this article.

1. MERN Stack: MERN is a short form for MongoDB, ExpressJS, ReactJS, and NodeJS.

MongoDB: This is the database in the stack. It is a NoSQL database and can store data in JSON format.
Express Js:: This is the back-end technology in the stack. It runs on NodeJS.
React JS: React JS is a JavaScript library used to create front-end or user interface components of Single Page Applications (SPAs).
NodeJS: This is a runtime environment capable of running JavaScript on a machine.

This stack is quite popular among developers around the world.

Advantages of the MERN Stack

Open Source: All of the technologies used in the MERN stack are open source. It means they are constantly improved. It also means the technologies have large communities that can aid your learning process.
Easy To Use: Because most of the technologies used in this stack already have community support, it is relatively easy to learn them. Most of these technologies also have good documentation and articles written about them.
Flexibility and Performance: The MERN stack is known to be used to create high-performance apps. It is also relatively easy to maintain apps built with this stack.

Other stacks similar to the MERN stack are the MEAN stack and MEVN stack.
Both of these stacks use the same technologies as the MERN stack. Their differences lie in the front-end technology they use.
The MEAN stack uses AngularJS, while the MVEN stack uses VueJS as their respective front-end technologies.

2. Python-Django Stack: The Python-Django stack is a web stack built on the Python programming language.

It makes use of Django as the back-end technology.
It uses Apache or Nginx as the server.
It can make use of MySql as the database. However, The choice of the database depends on the project you are building.

Advantages of the Python-Django Stack

Easy to learn: The Python-Django stack uses python as the programming language. Python is a language that is very easy and simple to grasp. It is as well the most human-readable language. Learning python is a good start for beginners.
Scalability: Django is a highly scalable framework. It can handle applications that have millions of users. Django can be used to build full-stack solutions (together with HTML and CSS) and can also be used to create APIs for front-end technologies like ReactJS to call.
Cost Effective: Due to its high scalability, Django makes it easy to reduce the cost of web hosting and maintenance. You can read more about the advantages of Django in this article.

3. LAMP Stack: LAMP is an acronym for Linux, Apache, MySQL, and PHP/Python/Perl. It is a back-end stack that is secure, flexible, and customizable.

It makes use of Linux as the operating system.
It makes use of Apache as the server.
It uses MySQL as the database.
It also uses PHP, Python, or Perl as the programming language(s).

Advantages of the LAMP Stack

Easy customization: The LAMP stack uses the Linux operating system. It makes it easy for users to customize components and make them suitable for their projects.
Open source: Like other tech stacks mentioned in this article, the LAMP stack is an open-source tech stack with a great community.
This article explains the LAMP stack in detail.

Another stack similar to the LAMP stack is the WAMP stack. The only difference is the operating system. WAMP makes use of Windows OS as the operating system.

Conclusion.

In this article, we discussed what tech stacks are, some of the different tech stacks available, and examples of tech stack models.
Let me know in the comments if this article was helpful to you in any way.

DEV Community: Ademola Thompson

How to make your React app multilingual

Prerequisites

Building a React application

Step 1: Initialize a React project

Step 2: Install dependencies and configure your project

Step 3: Build your navbar and footer components

Step 4: Create components for your pages

How to Localize a Website

Step 1: Install the Lingo.dev compiler

Step 2: Update your app’s configuration for localization

Step 3: Configure your API key

Step 4: Connect your app to the translation compiler

Step 5: Add a language switcher

Step 6: Test your translations

Step 7: Handle locale-based routing

Step 8: Translate JSON in your app

Step 9: Remove the Lingo.dev widget

Conclusion

How to Build a CLI Tool to Auto-Translate OpenAPI Specifications

What You Will Build

Prerequisites

How it Works

The Process

Project Initialization and Setup

Building a CLI Tool to Translate OpenAPI Specification Files

Step 1. Create the Authentication Flow

Step 2: Prepare Your OpenAPI File for Translation

Step 3: Generate the Lingo.dev Configuration

Step 4: Call Lingo.dev for Translation

Step 5: Create Your CLI Entry Point

Build a Frontend Interface to View any OpenAPI Specification File

Step 1: Set Up the Viewer File Structure

Step 2: Load and Parse the OpenAPI Spec Files

Step 3: Build the App Component

Step 4: Update main.jsx to use LingoProvider

Step 5: Build a Language Switcher

Step 6: Build the Sidebar

Step 8: Update CSS and Configure the Entry Point

What Comes First When Writing Documentation—The Product or The Users?

How I would recommend solving either of these issues

A Practical Guide to Translating & Localizing Your Web App: Using i18n and Lingo.dev

Prerequisites

Setting Up Localization in a React Web App

1. Create a React Application

2. Install Localization Dependencies

3. Create Translation Files

4. Initialize and Configure i18next For Translations

5. Modify Your React Component For Translations

6. Switch Languages Dynamically

Localizing & Translating a Web Application With Lingo.dev

1. Create an Account on Lingo.dev

2. Delete Tranlation Files

3. Authenticate Your React App With Lingo

4. Initialize Lingo.dev in Your React App

5. Run Lingo.dev

Conclusion

Resources

[Boost]

Understanding User Needs in Technical Writing: How Frameworks Like Diátaxis Help

Ademola Thompson ・ Jan 8

Understanding User Needs in Technical Writing: How Frameworks Like Diátaxis Help

Understanding User Needs in Technical Documentation

What Is Diátaxis and How Can It Satisfy User Needs

Applying Diátaxis for Your Documentation

Tutorials

How-To Guides

Reference Guides

Explanations

Conclusion

Resources

Python Telegram Bot Starter Kit: Your Express Route to Bot Development

My Kit

Key Features

Link to Kit

My Journey

Lessons Learned

Challenges

Conclusion

A Practical Approach to Unit Testing in Django REST Framework

Step 4: Update `main.jsx` to use `LingoProvider`

`push` Method:

`pop` Method

`delete` Keyword

Things To Note About The `delete` Keyword

Initializing Arrays With The `public` Access Modifier