Why I Changed the Blog i18n Architecture Mid-Project

Let me tell you about a refactor I did today that I should have done six months ago.

The Problem with 3 Files Per Post

My blog had a clean enough structure on paper: /en/post-slug/, /ja/post-slug/, /zh/post-slug/. Three directories, three files, three languages. Easy to understand.

But here's what actually happened: when I wrote a new post, I'd create the English version, hit publish, and... the Japanese and Chinese pages just showed English content. I kept telling myself "I'll translate it later." Later never came.

Six months later, I had 8 posts with Japanese content that was just a copy-paste of English with some characters swapped. The language switcher looked broken. Visitors clicking to Japanese got English content with weird half-translated frontmatter.

The Fix: One File, All Locales

The new architecture puts everything in a single MDX file:

---
slug: post-name
date: 2026-05-21

en:
  title: English Title
  content: |
    English body...

ja:
  title: 日本語タイトル
  content: |
    日本語の本文...

zh:
  title: 中文标题
  content: |
    中文正文...
---

Now there's no "later" — all three languages must exist in the same file. If you add English, you're adding Japanese and Chinese at the same time. The schema enforces completeness.

Key Lessons

Was it painful to migrate 10 posts? Yes. Do I regret it? No. Now when someone clicks the language switcher, they get actual translated content. That's worth the refactor.