DEV Community: LukeZ

How to Localize your Discord Bot in 2026

LukeZ — Thu, 02 Apr 2026 08:51:00 +0000

Discord bots reach users across the globe. If your bot replies in English-only (or whatever language you choose), you're leaving a huge portion of your audience with a worse experience.
Discord even provides a locale field on every interaction, so you already know what language each user prefers - you just need to use it.

This guide walks through building a localized Discord bot using li18n, a compile-time i18n library for TypeScript that turns your JSON message files into fully type-safe functions with zero runtime overhead.

I've already wrote a guide on this some months ago, but that was with a different package - which is not designed for such stuff and also had some bugs.

Why li18n?

Most i18n libraries follow the same pattern: load a big JSON file at runtime, look up a string by key, interpolate variables. This works, but it has downsides:

No type safety - mistyped keys and missing variables are silent bugs
Runtime parsing cost on every message lookup
Locale switching requires extra plumbing per request

li18n takes a different approach. You define your messages in JSON, run li18n build, and get plain TypeScript functions - one per message key.
The generated code is just functions and switch statements. There's nothing to parse at runtime, and your editor knows exactly which parameters each message requires.

Installing

bun add @the-lukez/li18n

The CLI is li18n. Run li18n init to scaffold your project:

bun li18n init

This creates a li18n.config.json and a messages/ directory with example locale files.

Project layout

my-bot/
├── messages/
│   ├── en.json
│   └── de.json
├── src/
│   ├── i18n/          ← generated, don't edit
│   ├── commands/
│   └── index.ts
├── li18n.config.json
└── index.ts

Configuration

li18n.config.json tells the compiler where your messages live and where to write the output:

{
  "locales": ["en", "de"],
  "defaultLocale": "en",
  "messagesDir": "./messages",
  "outputDir": "./src/i18n"
}

Defining messages

Messages live in messages/<locale>.json. Every locale file must have the same keys - li18n will tell you if anything is missing or mismatched when you run li18n check.

messages/en.json (expand)

{
  "ping": {
    "reply": "Pong! Latency: {latency}ms",
    "error": "Could not measure latency."
  },

  "role": {
    "assigned": "You've been given the {role} role.",
    "removed": "The {role} role has been removed from you.",
    "adminOnly": "This command is only available to admins."
  },

  "remind": {
    "set": "Got it! I'll remind you in {minutes} minutes.",
    "fire": "Hey {username}, here's your reminder:\n&gt; {message}",
    "tooShort": [
      {
        "var": { "num": "minutes" },
        "cases": {
          "=== 0": "You need to give me at least 1 minute.",
          "else": "That's too short - minimum is 1 minute."
        }
      }
    ]
  },

  "status": {
    "online": "Bot is online.",
    "version": "Running version {version}.",
    "shards": [
      {
        "var": { "num": "count" },
        "cases": {
          "=== 1": "1 shard connected.",
          "else": "{count} shards connected."
        }
      }
    ]
  }
}

messages/de.json (expand)

{
  "ping": {
    "reply": "Pong! Latenz: {latency}ms",
    "error": "Latenz konnte nicht gemessen werden."
  },

  "role": {
    "assigned": "Du hast die Rolle {role} erhalten.",
    "removed": "Die Rolle {role} wurde dir entfernt.",
    "adminOnly": "Dieser Befehl ist nur für Admins verfügbar."
  },

  "remind": {
    "set": "Verstanden! Ich erinnere dich in {minutes} Minuten.",
    "fire": "Hey {username}, hier ist deine Erinnerung:\n&gt; {message}",
    "tooShort": [
      {
        "var": { "num": "minutes" },
        "cases": {
          "=== 0": "Du brauchst mindestens 1 Minute.",
          "else": "Das ist zu kurz - Minimum ist 1 Minute."
        }
      }
    ]
  },

  "status": {
    "online": "Bot ist Online.",
    "version": "Version: {version}.",
    "shards": [
      {
        "var": { "num": "count" },
        "cases": {
          "=== 1": "1 Shards verbunden.",
          "else": "{count} Shards verbunden."
        }
      }
    ]
  }
}

A few things to notice:

Nested keys - messages can be nested arbitrarily deep. The compiler flattens them into dot-separated keys (ping.reply, role.assigned, etc).
Variables - {latency} becomes a required typed parameter latency: string (or number/boolean when you use the typed syntax).
Conditionals - the remind.tooShort and status.shards keys use numeric conditionals. The compiler turns these into ternary expressions, not runtime lookups.

See the message format reference for more details on the syntax and features available in message files.

Compiling

bun li18n build

The src/i18n/ directory is now populated with generated TypeScript. You can also run li18n watch during development to recompile on every save.

To validate that all locales are consistent without writing any files:

bun li18n check

The generated API

After compilation, your entry point is src/i18n/index.ts:

export * as m from "./messages/_index.ts";
export { getLocale, overwriteGetLocale, withLocale, locales, baseLocale } from "./runtime.ts";
export type { Locale, MaybePromise } from "./runtime.ts";

Import m for messages and withLocale for locale-scoped handlers. Every message function accepts an optional explicit locale as its last argument - but when you use withLocale, you rarely need to pass it manually.

import { m, withLocale } from "./src/index.ts";

m.pingReply({ latency: 42 }); // uses current locale
m.pingReply({ latency: 42 }, "de"); // explicit override
m.statusShards({ count: 3 }); // number conditional, no locale arg needed

TypeScript will catch you if you forget a required parameter or pass the wrong type.

Wiring it into Discord.js

Here's where li18n really shines. Discord sends a locale string with every interaction (e.g. "en-US", "de", "fr"). We want each interaction handler to automatically use the right locale without passing it around everywhere.

withLocale wraps any async function and stores the locale in AsyncLocalStorage. Every m.* call inside the handler reads it automatically.

Resolving the locale

Discord uses IETF language tags like en-US, but your locales are likely en, de, etc. - So you need to write a small resolver:

import { locales, type Locale } from "./i18n/index.ts";
import type { Interaction } from "discord.js";

export function resolveLocale(interaction: Interaction): Locale {
  const tag = interaction.locale; // e.g. "en-US", "de", "pt-BR"
  const lang = tag.split("-")[0] as Locale;
  return (locales as readonly string[]).includes(lang) ? lang : "en";
}

Ping Command

src/commands/ping.ts

import { SlashCommandBuilder } from "discord.js";
import type { ChatInputCommandInteraction } from "discord.js";
import { m, withLocale } from "../i18n/index.ts";
import { resolveLocale } from "../i18n/locale.ts";

export const data = new SlashCommandBuilder()
  .setName("ping")
  .setDescription("Check the bot latency");

const execute = withLocale(async (interaction: ChatInputCommandInteraction) =&gt; {
  const sent = await interaction.reply({ content: "Pinging…", fetchReply: true });
  const latency = sent.createdTimestamp - interaction.createdTimestamp;

  await interaction.editReply(m.pingReply({ latency }));
}, resolveLocale);

export { execute };

No locale argument anywhere in the handler body - m.pingReply calls getLocale() internally and gets the right value from the AsyncLocalStorage context that withLocale set up.

Role Command

src/commands/role.ts

import { SlashCommandBuilder, PermissionFlagsBits } from "discord.js";
import type { ChatInputCommandInteraction } from "discord.js";
import { m, withLocale } from "../i18n/index.ts";
import { resolveLocale } from "../i18n/locale.ts";

export const data = new SlashCommandBuilder()
  .setName("role")
  .setDescription("Toggle a role")
  .addRoleOption((option) =&gt;
    option.setName("role").setDescription("The role to toggle").setRequired(true),
  );

const execute = withLocale(async (interaction: ChatInputCommandInteraction) =&gt; {
  if (!interaction.memberPermissions?.has(PermissionFlagsBits.ManageRoles)) {
    await interaction.reply({ content: m.roleAdminOnly(), ephemeral: true });
    return;
  }

  const role = interaction.options.getRole("role", true);
  const member = await interaction.guild!.members.fetch(interaction.user.id);
  const hasRole = member.roles.cache.has(role.id);

  if (hasRole) {
    await member.roles.remove(role.id);
    await interaction.reply(m.roleRemoved({ role: role.name }));
  } else {
    await member.roles.add(role.id);
    await interaction.reply(m.roleAssigned({ role: role.name }));
  }
}, resolveLocale);

export { execute };

Reminder Command

src/commands/remind.ts

import { SlashCommandBuilder } from "discord.js";
import type { ChatInputCommandInteraction } from "discord.js";
import { m, withLocale } from "../i18n/index.ts";
import { resolveLocale } from "../i18n/locale.ts";

export const data = new SlashCommandBuilder()
  .setName("remind")
  .setDescription("Set a reminder")
  .addIntegerOption((o) =&gt;
    o.setName("minutes").setDescription("Minutes from now").setRequired(true),
  )
  .addStringOption((o) =&gt;
    o.setName("message").setDescription("What to remind you of").setRequired(true),
  );

const execute = withLocale(async (interaction: ChatInputCommandInteraction) =&gt; {
  const minutes = interaction.options.getInteger("minutes", true);
  const message = interaction.options.getString("message", true);

  if (minutes &lt; 1) {
    // The conditional picks the right case based on the value of `minutes`
    await interaction.reply({ content: m.remindTooShort({ minutes }), ephemeral: true });
    return;
  }

  await interaction.reply(m.remindSet({ minutes }));

  setTimeout(async () =&gt; {
    await interaction.followUp(m.remindFire({ username: interaction.user.username, message }));
  }, minutes * 60_000);
}, resolveLocale);

export { execute };

src/index.ts - the main bot file

import { Client, GatewayIntentBits, Collection } from "discord.js";
import type { ChatInputCommandInteraction } from "discord.js";
import * as ping from "./src/commands/ping.ts";
import * as role from "./src/commands/role.ts";
import * as remind from "./src/commands/remind.ts";

const client = new Client({ intents: [GatewayIntentBits.Guilds] });

const commands = new Collection([
  [ping.data.name, ping],
  [role.data.name, role],
  [remind.data.name, remind],
]);

client.on("interactionCreate", async (interaction) => {
  if (!interaction.isChatInputCommand()) return; // We only got slash commands in this example, so ignore other interactions

  const command = commands.get(interaction.commandName);
  if (!command) return;

  try {
    await command.execute(interaction as ChatInputCommandInteraction); // type inference on withLocale ensures the function has the same params as the handler
  } catch (err) {
    console.error(err);
  }
});

client.login(process.env.DISCORD_TOKEN);

If you got a lot of commands with the same locale resolver, you can create a helper class that wraps withLocale and hardcodes the resolver, so you don't have to repeat it everywhere.

Example interaction handler class

import { withLocale } from "./src/i18n/index.ts";
import { resolveLocale } from "./src/locale.ts";
import type { Client, Collection, ClientEvents } from "discord.js";

export class InteractionHandler {
  #client: Client;
  #commands: Collection Promise }&gt;;
  #components: Collection Promise }&gt;;

  constructor(
    client: Client,
    commands: Collection Promise }&gt;,
    components: Collection Promise }&gt;,
  ) {
    this.#client = client;
    this.#commands = commands;
    this.#components = components;
  }

  handler(): (...args: ClientEvents["interactionCreate"]) =&gt; void {
    return withLocale(async (interaction) =&gt; {
      if (interaction.isChatInputCommand()) {
        const command = this.#commands.get(interaction.commandName);
        if (command) await command.execute(interaction);
      } else if (interaction.isButton()) {
        const component = this.#components.get(interaction.customId);
        if (component) await component.execute(interaction);
      }
    }, resolveLocale); // All interactions go through the same locale resolver
  }
}

// In your index.ts

const handler = new InteractionHandler(client, commands, components);

client.on("interactionCreate", handler.handler());

In your command handlers, you can now use m.* without worrying about withLocale or the resolver - it's all handled by the InteractionHandler class.

import type { ChatInputCommandInteraction } from "discord.js";
import { m } from "../i18n/index.ts";

export async function execute(interaction: ChatInputCommandInteraction) {
  await interaction.reply(m.pingReply({ latency: 42 }));
}

How concurrent requests stay isolated

Because withLocale uses AsyncLocalStorage under the hood, two simultaneous interactions never see each other's locale. If a German user and an English user both trigger /ping at the same moment, each withLocale call creates its own isolated storage slot. There's no global state to race on.

This also means you can override the locale mid-handler if needed. Say you want to log something in English regardless of the user's locale:

import { overwriteGetLocale } from "../i18n/index.ts";

const execute = withLocale(async (interaction) => {
  // Responds in the user's language
  await interaction.reply(m.pingReply({ latency: 42 }));

  // Switch to English just for this log message
  overwriteGetLocale(() => "en");
  console.log(m.pingReply({ latency: 42 })); // always in English
}, resolveLocale);

overwriteGetLocale only affects the current withLocale context - other concurrent handlers are unaffected.

Development workflow

# Watch for changes and recompile as you edit message files
bunx li18n watch

# Verify all locales are in sync before committing
bunx li18n check

# One-shot compile for CI/CD
bunx li18n build

Since the output directory is auto-generated, add it to .gitignore (li18n does this automatically) and rebuild as part of your deployment step.

With watch mode, it is recommended to change your save behavior in your editor to "save on focus change" or increase the debounce delay, to avoid triggering a build on every keystroke (this could result in bugs).

What you get

Full type safety - every message function's parameters are inferred from the JSON. Forget { latency } and TypeScript tells you before you ship.
Zero runtime parsing - compiled messages are plain functions. No JSON loaded, no key lookups, no format-string parsing per call.
Per-interaction locale isolation - withLocale handles the plumbing via AsyncLocalStorage. No locale prop-drilling. This should even work in serverless environments where multiple requests share the same instance - however you might need to enable nodejs_compat for example, if you're on Cloudflare Workers.
Numeric and boolean conditionals - pluralization and conditional text compile to ternary chains, not runtime switch tables.

How to make a localized Discord Bot with Paraglide.js

LukeZ — Wed, 29 Oct 2025 09:23:15 +0000

Banner by Leonardo Toshiro Okubo on Unsplash

If you want to make a Discord bot that speaks multiple languages, the question is inevitable: "HOW?"

I’ve done it the hard way - my own JSON loader, manual locale passing, require("./en.json"), string lookups everywhere. It worked. Barely.

But what if you didn’t have to manage the locale yourself every single time you needed a translation?

You write:

m.greeting({ user: "Alex" })

And it just works - in the user’s language, with correct grammar, plurals, and more.

Let’s set it up!

Paraglide JS

Paraglide is a lightweight, type-safe internationalization (i18n) library for JavaScript and TypeScript projects, designed to make multi-language support effortless and scalable. Built by the inlang team, it eliminates the boilerplate of traditional translation systems by generating optimized code from your translation files at build time. No more manual locale management, runtime JSON parsing, or error-prone string interpolation—Paraglide handles it all with zero runtime overhead.

Unlike my old-school JSON-based translation handler (which basically boiled down to require("path/to/translations/en.json") and manual locale juggling every time), Paraglide lets you focus on your bot's logic. You define translations once in simple .json files, run a quick build step, and get fully typed functions for every message. Want to fetch a greeting in French? Just call m.greeting({ user: 'Pierre' }) - it (kind of) auto-detects the locale from your Discord user's settings and returns the translated string. Types ensure no typos or missing params, catching errors at compile time.

Inlang Message Format

Inlang's message format even provides a very nice solution for built-in variants, pluralization and more!

See their docs for more info.

Using it, I can easily do this:

"greetUsers": [
  {
    "declarations": ["input count", "local countPlural = count: plural"],
    "selectors": ["countPlural"],
    "match": {
      "countPlural=one": "Say hello to {count} user!",
      "countPlural=other": "Say hello to {count} users!"
    }
  }
],

Paraglide Setup

Before we can really start, we need to initialize paraglide.

In my example I have the following project structure:

project/
└── src/
    ├── commands/
    │   └── someCommand.ts
    ├── components/
    │   └── someComponent.ts
    ├── events/
    │   └── messageCreate/
    │       └── index.ts
    └── index.ts

I have my own solution for loading all commands, components and events, but that isn't important here. More on that later.

Now we need to run the init wizard.

# npm
npx @inlang/paraglide-js@latest init
# pnpm
pnpx @inlang/paraglide-js@latest init
# bun (I use bun in my project, but that doesn't matter)
bunx @inlang/paraglide-js@latest init

It will ask you some stuff and you should do the following:

Where should the compiled files be placed? ./src/paraglide (default)
Do you want to set up machine translations? If you want, yes. It will add a script in your package.json for that.

This will create

project/messages for translations
- Locale files for messages look like en.json or de-DE.json in this directory.
- This has the message example_message in it by default
project/project.inlang for settings
project/src/paraglide/ the directory for compiled translations ("messages")
A script to compile translations for runtime called build (you can change that if you want - I changed it to compile-translations
A script to run machine translations: machine-translate More on that later.

DON'T FORGET TO RUN npm i AFTER INIT! (or whatever your package manager is)

Discord.js Bot Setup

There is no big difference for handling interactions and events, however we need to add a sort of middleware.

Paraglide can't detect the locale just by itself. But it supports AsyncLocalStorage which we will use here. AsyncLocalStorage enables you to store data (like primitives or objects) that remains accessible throughout an asynchronous call stack, automatically propagating the context across awaits and callbacks without manual passing. It’s ideal for tracking per-request state, such as locales, in async-heavy environments like Discord bots.

// project/src/index.ts
import { type ClientEvents } from "discord.js";
import { baseLocale, locales, overwriteGetLocale, type Locale } from "./paraglide/runtime.js";

const localeStorage = new AsyncLocalStorage<Locale>({ name: "locales" });

// We need to determine the locale when calling the "get message" function in an interaction
overwriteGetLocale(() => {
  return localeStorage.getStore() ?? baseLocale;
});

// ...

// Wrapper for an interaction handler
function interactionMiddleware(
  interaction: ClientEvents["interactionCreate"][0],
  next: (interaction: ClientEvents["interactionCreate"][0]) => Promise<void>,
) {
  const locale = interaction.locale.slice(0, 2) as Locale; // simplify discord's locale to something more basic (this is not needed, you can also use discord's locale-system which has more languages but is more of a headache to localize)
  const validLocale = locales.includes(locale) ? locale : baseLocale;
  return localeStorage.run(validLocale, () => next(interaction));
}

It is important to note, when loading interaction handlers from their respective file, we need to wrap them in interactionMiddleware to get it working.

// project/src/index.ts
// Very basic example, you want to integrate this into your own loading logic!
import { execute } from "./commands/someCommand.js"

client.on("interactionCreate", async (interaction) => {
  await interactionMiddleware(interaction, execute)
});

Localizing event handlers is also possible, but requires a more complex setup. More on that later.

Now you can use paraglide's compiled messages in your command handler!

// project/src/commands/someCommand.js
import { type ChatInputCommandInteraction } from "discord.js";
import { m } from "../paraglide/messages.js";

// Command declaration here...

export async function execute(interaction: ChatInputCommandInteraction) {
  await interaction.reply({
    flags: 64, // Ephemeral
    content: m.example_message({ username: interaction.user.username })
  });
}

Now you're good to go! You have localized your Discord bot interactions!

Localizing Event Handlers

You can apply the same pattern to event handlers (e.g., messageCreate, guildMemberAdd), but you’ll need to determine the locale manually since most events don’t include interaction.locale.

Strategies:

In-guild events: Use guild.preferredLocale (if available).
User-specific events: Store user language preferences in your database and cache it to avoid unnecessary latency and database queries.
Fallback: Default to baseLocale.

Example Middleware for `messageCreate`:

// src/middleware/eventLocale.ts
import { AsyncLocalStorage } from "async_hooks";
import { baseLocale, locales, type Locale } from "../paraglide/runtime.js";

export const localeStorage = new AsyncLocalStorage<Locale>();

// Reuse the same instance everywhere
export function withEventLocale<T extends any[]>(
  event: any,
  handler: (...args: T) => Promise<void>,
  getLocaleFromEvent: (event: any) => Locale | undefined
) {
  const locale = getLocaleFromEvent(event);
  const validLocale = locale && locales.includes(locale) ? locale : baseLocale;
  return localeStorage.run(validLocale, () => handler(event));
}

It is important, that the same AsyncLocalStorage instance is used for all middlewares because we have overridden the get-logic before!

Then in your event-loading-logic:

// wherever you're loading your events
// Very basic implementation - adjust for your own loading-logic
import { default as handleMessage } from "./events/messageCreate/index.js";
import { withEventLocale } from "./middleware/eventLocale.ts";
import { baseLocale } from "./paraglide/runtime.js";

client.on("messageCreate", (message) =>
  withEventLocale(message, handleMessage, (msg) => {
    if (msg.guild?.preferredLocale) {
      return msg.guild.preferredLocale.slice(0, 2) as Locale;
    }
    // Optional: check user DB, etc.
    return baseLocale;
  })
);

My WordPress Disaster: A Cautionary Tale (and a Lesson I Swear I’ve Learned Before)

LukeZ — Mon, 25 Aug 2025 13:54:15 +0000

They say you should never change a running system. Today, I can confirm that "they" are absolutely right. And that I, apparently, have the memory of a goldfish.

Let me set the scene. I’m a newbie in the WordPress world, getting my feet wet with a local development environment. I had MAMP running, which came with its own version of PHP and MySQL. Everything was humming along nicely, and I was making progress styling and editing the child-theme of a theme we bought.

Then, a new project came along. A different project, one that didn't need MAMP (with Symfony). So, in a fit of efficiency (or, as it turns out, pure hubris), I decided to delete MAMP and install PHP and MySQL separately using Homebrew. "Clean," I thought. "Efficient," I thought. "What could possibly go wrong?" I thought.

What could go wrong, indeed. Turns out, WordPress isn’t just a pile of files and themes. It's a clingy little digital creature that stores its entire existence - every page, every setting, every glorious bit of config - inside a MySQL database. And where did MAMP, in its infinite wisdom, keep that precious database? Right there in its folder in the Application directory. The same directory I proceeded to “pulverize” (my new favorite word for this kind of digital annihilation) when I deleted MAMP.

Fast forward to today. Time to show off our progress! I installed XAMPP, thinking it would be a quick fix. (Spoiler: It was not.) After an hour of pulling my hair out, the terrible truth dawned on me. The database. It was gone. Wordpress didn't find the database connection. All of it. Poof. Vanished. The only thing left were the theme files, like a ghostly, empty skeleton of a website.

So, here I am, about to rebuild an entire homepage from scratch. But hey, at least I got a valuable life lesson out of it. One that I've learned about 50 times already, and will probably learn again many more times.

Lesson of the day, kids: Never. Change. A. Running. System. EVER.

Now, if you’ll excuse me, I have a date with a blank WordPress dashboard.

I'll definitely use this

LukeZ — Mon, 16 Jun 2025 10:04:34 +0000

DevOps Daily

Jun 16 '25

How to Structure Your DevOps Side Project for Real-World Deployments

#devops #docker #beginners #cicd

Comments

3 min read

My Late-Night Server Migration Saga

LukeZ — Mon, 16 Jun 2025 10:01:41 +0000

A Tale of "Simple" Tasks That Spiral Out of Control

Disclaimer: I replaced the real domain and names in this post with placeholders because it doesn't matter; I also enhanced some paragraphs of my tale with AI because my English sentence structures are weird sometimes.

Yesterday evening, a seemingly "little bit" of refactoring for my Discord Bot's homepage turned into an unexpected adventure. My goal was straightforward: to adapt the existing codebase to new database types and fix a few minor bugs. After a quick push to the server, all seemed well.

Or so I thought.

The First Mistake

In the typical fashion of a late-night coding session, I completely overlooked a crucial detail: I had tweaked the /stats API endpoint, a change that, unbeknownst to me, directly impacted my bot's homepage, residing in an entirely separate project. A swift fix to the endpoint URL and the homepage was back in action. Crisis averted, or so it appeared.

But then, the clock ticked past 11 p.m. A dangerous hour for developers, where a fleeting thought can blossom into an ambitious project.

"It's still early," I reasoned, "plenty of time for more changes."

My long-standing desire to clean up my VPS servers resurfaced with newfound urgency. "Let's tackle that now!"

The "Simple" Plan

A brief examination of my server landscape revealed a surprising fact: I could retire an expensive server entirely by migrating the homepage service to a less utilized machine. Sounds easy, right? ...Right? The simplicity of the idea was almost alluring.

I quickly pieced together a "master plan" that seemed incredibly straightforward:

Create a new user account on the target server and grant necessary sudo permissions
Set up Node.js and Nginx
Clone the website repository
Configure the essential .env file for credentials
Start the damn thing

"This sounds pretty straight forward and really simple," I mused. "What could possibly go wrong?"

The Spiral of "Simple" Tasks

Right after creating that new user, a thought hit me: this server would be publicly accessible, so securing my login with an SSH key was a must! I'd done this before, many times, so I figured it'd be a quick win. I was, of course, wrong yet again.

SSH Key Hell

It had been months since I last generated an SSH key, and my memory of the exact command was, predictably, fuzzy. A quick search for a guide cleared that up. But, being me, I then decided to ditch the guide and "wing it." In hindsight, that was a mistake.

Getting the key onto the server was easy enough. The real headache started when I tried to configure Termius (my SSH client) to use this new key. Despite having done it before, it was a total nightmare. Termius kept asking for a passphrase I never set and spat out a frustrating "pubkey failed" error. Why?! I was sure I'd done everything the same way as last time... or had I?

To this day, I'm not entirely sure what the magic fix was. After regenerating the keys, reconfiguring Termius, and even recreating the user account, it just... worked. Somehow.

By then, 30 minutes had vanished – it was already around 11:30 p.m. – and things were feeling far less "straightforward" than my initial plan suggested.

The Point of No Return

Then, for reasons only the universe knows, I decided to deviate from my original plan. I took the old homepage offline before the new one was even close to running. Thankfully, I'd activated a maintenance page on my status monitoring, so at least I wouldn't be barraged with error notifications.

With the old system down, I went to clone the website repo on the new server only to realize: nothing was installed yet! No Node.js, no npm. A quick visit to the Node.js homepage for their install scripts, and I was back on track. Repository cloned, I thought, "You know what, I can quickly migrate this project from npm to pnpm. I've done it a few times recently; it'll be fast."

And surprisingly, it was quick, taking about five minutes. I pulled the changes to the server, feeling a small surge of victory.

Then another thought came into my mind: NGINX wasn't configured yet.

The Missing Server

My immediate thought was to just copy the config file, SSL certificate, and key from the old server. Easy, right?

Wait... where did the old server go?

Turns out, in my late-night haze, after taking down the old system, I'd also deleted its host entry from Termius. I had no idea where I'd saved those SSH credentials, and finding them now would take too long. But, I knew what a basic NGINX config looked like, so I quickly wrote it from scratch:

# thedomain.dev.conf
server {
    listen [::]:80;
    server_name thedomain.dev;
    return 301 https://$host$request_uri;
}

server {
    listen [::]:443 ssl;
    server_name thedomain.dev;

    ssl_certificate /etc/ssl/thedomain.dev/cert.pem;
    ssl_certificate_key /etc/ssl/thedomain.dev/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    error_log /var/log/nginx/thedomain.dev.error.log;
    access_log /var/log/nginx/thedomain.dev.access.log;

    location / {
        proxy_pass http://localhost:6060;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

But then, the chilling realization: I'd need to generate new SSL certificates and reconfigure Cloudflare for the new server. Double crap.

The Midnight Panic

The homepage had now been down for about 30 minutes, and the clock showed midnight. Stress was building, and sleepiness was setting in fast.

I raced through deleting and creating a new Cloudflare certificate for the domain, then switched Cloudflare to Development mode so DNS and SSL changes would propagate in seconds, not minutes. I slapped the new certificates onto the server, updated the DNS record to point to the new IP, and held my breath. Everything seemed fine.

The Vanishing Code

Next, I wanted to test the website locally one last time. I went to open the website project on my computer, but... where was it? The folder wasn't where it had been just 30 minutes ago. Please don't be deleted...

The only explanation: I must have accidentally deleted the folder a few minutes earlier while clearing out my trash bin. This wasn't just losing the code; it meant the .env files were gone too. I had no environment variables left – the ones on the server were gone because I deleted the connection, and now my local copies were nuked.

Panic started to set in. I tried to regain control over the whole situation, to map out the disaster I'd created.

Write new .env files based on what variables the project needed
???

Because it was already very late I couldn't think more than one step at a time - so I just started doing stuff.

After cloning the repo locally again, I recreated the .env files. It took another five minutes to find all the necessary variables.

The Cloudflare Catastrophe

One final local test, and then I saw it: the stats on the website were showing the old fallback data. How could that be?

It turns out, I'd messed up even more things – mistakes that could have been avoided if I hadn't done all this in the middle of the night and just waited for the next day.

On Cloudflare's side, I'd done two crucial things:

Deleted and created a new certificate
Updated the IP for the new server

The massive oversight? I did both of these for api.thedomain.dev instead of thedomain.dev (@)!

This meant the bot's API endpoints now had:

❌ Invalid SSL certificates
❌ Misconfigured DNS record

This was why the website couldn't access live data.

It took me another 15 minutes to finally fix the DNS record to the correct IP and move the SSL certificates from the new server back to the original server where the bot and its API are running.

Now it was already 1:00 a.m. The website had been down for over an hour, and the bot was limping because it relies on Discord's OAuth2 login flow, which uses the api.thedomain.dev origin.

My phone, meanwhile, was buzzing non-stop. The monitoring worker I'd set up to notify me via Telegram was doing its job, reminding me every 10 minutes of my boneheaded decisions for every service that was having issues. But I couldn't stop. I had to fix this mess, and quickly.

The Finish Line (and More Headaches)

Finally, I checked api.thedomain.dev one last time, and it was working perfectly again! With that behind me, I focused back on the new server. I generated the new SSL certificates needed for the main domain and put them in place. Then, I configured the DNS for the new server, confident I was almost done.

But just when I thought I was in the clear, I hit another snag: for some reason, IPv6 just wasn't playing nice. Not for the DNS record, and not even for SSH connections when I tested it. After all this, I just accepted it. I decided to stick to IPv4 for everything for now, making a mental note to dive into the IPv6 mystery later.

By now, it was 1:30 a.m. and I was seriously wiped out. All I wanted was my bed.

The Final Facepalm

Then, another facepalm moment: I realized I had also configured NGINX for the wrong origin earlier, setting it up for api.thedomain.dev instead of thedomain.dev. Thankfully, that was a quick fix, sorted out in about five minutes.

With NGINX finally pointing correctly, I built the SvelteKit app and started it up. It was finally running!

But... https://thedomain.dev was... timing out? What now?!

I double-checked the NGINX config yet again. That's when it hit me: out of habit, I had only configured it to listen on IPv6. I'd been so used to working with IPv6 previously that I completely forgot to add the standard IPv4 listeners. The magical lines listen 80; and listen 443; were quickly added to the NGINX configuration and after I restarted the service, everything was finally was working.

Lessons Learned

After all that, it was 2:00 a.m. What was supposed to be a "quick" task had turned into a three-hour saga of unforeseen errors, frantic debugging, and a growing sense of desperation.

It was a harsh reminder that even the simplest-sounding IT tasks can unravel into a full-blown nocturnal adventure, especially when fatigue sets in.

I should also note that Claude.ai helped me a lot when finding the issues - I couldn't waste time for scraping websites so I used Claude to crawl the websites for giving me hints on what could be the cause and also some steps for configuration of NGINX.

Lessons learned, the hard way, in the middle of the night.

Next time, I'm going to bed at 11 p.m. and tackling server migrations in the morning with a fresh cup of coffee and a clear head.