🌐 Bridging the World: KairosLab’s Multilingual Magic Revealed

August 1, 2025

👋 Hey there! Welcome back to our Lab Journal!

Last time we talked about the technical heart of KairosLab. Today, we’re diving into something even cooler—how we turned our website into a “global citizen,” making everyone feel at home no matter what language they speak.

Our dream is to create a space where people from all over the world can share and create together. To make that happen, the website itself needs to be a language genius! And that’s way more than just translating some text—it requires a smart, scalable architecture. So let’s pull back the curtain and reveal the magic!


🧠 Design Philosophy: One Brain to Rule Them All

Our biggest fear? Chaos. Imagine if adding a new language meant engineers had to play “Where’s Waldo” across the codebase—madness! And a recipe for bugs.

So we made a simple rule: everything language-related goes into one central command center—src/i18n/config.ts.

export const SUPPORTED_LOCALES = ["en", "es", "zh-tw", "zh-cn"];

export const DEFAULT_LOCALE = "en";

export const LanguageNames = {
  en: "English",
  es: "EspaĂąol",
  "zh-tw": "繁體中文",
  "zh-cn": "简体中文",
};

export const DateLocaleMap: { [key: string]: string } = {
  en: "en-US",
  es: "es-ES",
  "zh-tw": "zh-TW",
  "zh-cn": "zh-CN",
};

This file is the brain of our multilingual system, and it handles a few key responsibilities:

  • SUPPORTED_LOCALES: Our “supported languages” list
    A public declaration that says, “Hey! These are the languages we speak!” Astro will only build pages for these languages—no half-baked orphan pages allowed.

  • DEFAULT_LOCALE: Our default “global greeting”
    If a new visitor arrives and we’re not sure what language they speak, we greet them in English (our default). This also tells Google that among all our language versions, English is our “main storefront.”

  • LanguageNames & DateLocaleMap: Our cultural consultants

    • The former ensures that language options are shown in familiar terms (like “繁體中文” instead of “Traditional Chinese”)
    • The latter ensures dates are displayed in culturally appropriate formats (e.g., “2025ĺš´8㜈11日” vs. “August 11, 2025”)

Centralizing all settings means that adding a new language (say, German de) only requires updating this one file—and voilà, the whole site speaks German. Efficient and elegant!


📦 Content Management: Let the Right People Do the Right Things

A multilingual site’s content generally falls into two categories:

  1. Fragmented UI text (buttons, headings, etc.)
  2. Structured long-form content (blog posts, etc.)

🧱 UI Text: LEGO Blocks in JSON Drawers

We store all fragmented UI text—like “Submit” on a button or “About Us” in the nav—in neatly categorized .json drawers:

  • common.json: Shared blocks across the site
  • main.json: Homepage-specific blocks
  • categories.json: Blocks for blog categories

This setup means translators can simply open the right drawer and swap out a block—no need to touch the code. Super convenient!

✍️ Long-Form Content: A Distraction-Free Writing Zone

For blog posts and other long-form content, we rely on Astro’s powerful Content Collections feature:

  • Writers use Markdown and save files in the src/content/ folder
  • We use Zod as a “quality inspector” to validate article formats (like title and date)

This ensures that published content is flawless.
Separating content from code makes collaboration smooth and efficient!


🧭 Smart Routing: A Language Experience That Feels Personal

We want our site to feel like a thoughtful guide—one that understands you. So we designed a combo system:

✈️ First Impressions Matter: Airport Greeter (Vercel Edge Middleware)

When you visit for the first time, our “airport greeter” checks your passport (browser language settings) before you even step through the gate. Then—whoosh!—you’re redirected to the most appropriate language page before you even notice.

  • So fast you won’t feel a thing—just “Wow, this site really gets me!”
  • Great for SEO—Google sees the correct page right away!

🔄 Switch Anytime: Friendly Waiter (JavaScript)

When you click the language switcher, our “friendly waiter” jumps into action:

  1. Saves your language preference in a cookie (like stamping your membership card)
  2. Instantly redirects you to the new language page so you see the content you want

🧱 Final Thoughts: Laying Every Brick for Borderless Dialogue

Building a powerful multilingual site is a serious undertaking—but totally worth it. Because it means we genuinely want to connect with the world.

Thanks to this solid foundation, we can confidently say:

KairosLab is a platform born for global dialogue—a place where you feel at home, no matter where you are.

We’ve laid every brick for this borderless journey, and now, we can’t wait for you to join us!


📢 Next Up: We’ll talk about how to make Google fall in love with us—stay tuned!