Bilingual FR/EN blog in pure PHP: architecture without framework or database

This blog was built in pure PHP, no CMS, no database. First article in the series, already published. At some point the question comes up: is it worth adding English support? Short answer: yes, and it's less complicated than it looks. Long answer: here's how I did it, with the traps that come with it.

No gettext, no i18n library, no database for translations. Just separate PHP files per language, a restructured JSON file, and three layers of routing. The whole thing fits in a few dozen lines of code spread across files you already have.

Why translate a developer blog

Two concrete reasons, no philosophy.

The English-speaking SEO market is 10 to 50 times larger. A query like "php blog without framework" has a search volume that has nothing to do with the French equivalent. If you write about technical topics that interest English-speaking developers — and you probably do if you're reading this — not having an EN version means missing an existing audience without the overhead being that large once the architecture is in place.

It shows recruiters you're bilingual. A portfolio available in English, with properly written technical content, is a strong signal. No need to mention it in your CV — the site speaks for itself. An international recruiter who lands on your article via Google EN immediately sees that you can work in English.

There's a third reason that's not easy to admit but real: writing the same article in two languages forces you to restructure explanations. It often improves the original version in the process.

Architecture decisions

URL structure

The main constraint: don't break existing URLs. All already-published articles live at /blog/slug. These URLs don't move. English versions live at /en/blog/slug.

/blog/blog-multilingue-php-sans-framework      # FR (default)
/en/blog/blog-multilingue-php-sans-framework   # EN

The /en/ prefix is simple to detect, to generate in links, and to route server-side. No ?lang=en parameter, no cookie, no automatic browser language detection — the URL is the source of truth. This is the only model that works correctly for SEO (search engines index distinct URLs) and respects the principle of least surprise for the user.

One PHP file per language

For each article, two files:

blog/posts/
├── my-slug.php       # French version
└── my-slug.en.php    # English version

The alternative — a single file with translation arrays — looks like this in real life:

<?php
$texts = [
    'fr' => [
        'intro' => 'Ce blog a été construit en PHP pur...',
        'section1' => 'Les choix d\'architecture...',
        // 800 lines of content inside quotes with escaping everywhere
    ],
    'en' => [
        'intro' => 'This blog was built in pure PHP...',
        // 800 more lines
    ],
];
echo $texts[$lang]['intro'];

It's unreadable, unmaintainable, and you spend half your time managing apostrophes and quotes. One file per language is more verbose in terms of file count, but each file is simple to read and modify independently. That's the right trade-off for a blog.

Bonus: if an article doesn't have an English version, the .en.php file simply doesn't exist. The router returns a clean 404. No complex fallback logic needed.

Restructured posts.json

Before adding multilingual support, the JSON was flat:

{
  "slug": "my-slug",
  "date": "2026-03-15",
  "title": "Article title",
  "category": "Lessons learned",
  "tags": ["php", "blog"],
  "excerpt": "Short summary."
}

After migration, language-dependent fields are nested inside fr and en objects:

{
  "slug": "my-slug",
  "date": "2026-03-15",
  "fr": {
    "title": "Titre de l'article",
    "category": "Retour d'expérience",
    "tags": ["php", "blog"],
    "excerpt": "Résumé court."
  },
  "en": {
    "title": "Article title",
    "category": "Lessons learned",
    "tags": ["php", "blog"],
    "excerpt": "Short summary."
  }
}

The date stays at root level — it's language-independent. So is the slug — it's the same for both versions.

Migrating existing data is done with a one-shot PHP script (see below). Don't do it by hand for 30+ articles.

template.php receives $lang

The blog_header() signature already had a $lang parameter set up but unused. It becomes functional:

<?php
function blog_header(
    string $title,
    string $description,
    string $canonical_url,
    ?string $og_image = null,
    ?array $article_data = null,
    string $lang = 'fr'
): void {

This parameter drives: the lang attribute on <html>, og:locale, hreflang tags, breadcrumbs, navigation, and the language toggle. One parameter, no global variable.

The three routing layers

The routing architecture is the trickiest part. It has three layers that must stay consistent with each other, otherwise you end up with a site that works in production but not in development, or vice versa.

Layer 1: .htaccess for Apache

The clean FR blog URLs already existed in .htaccess. The EN addition comes down to two lines:

# Blog EN: /en/blog/slug → blog/posts/slug.en.php
RewriteRule ^en/blog/([a-z0-9-]+)/?$ blog/posts/$1.en.php [L,QSA]

# Blog listing EN: /en/blog/ → blog/index.php with lang=en
RewriteRule ^en/blog/?$ blog/index.php?lang=en [L,QSA]

Two rules. That's it. The existing routing already handles FR URLs. The EN article rule must be added before the FR rules to avoid pattern conflicts — Apache rules apply in declaration order.

Layer 2: router.php for the built-in PHP server

The built-in PHP server (php -S localhost:8000 router.php) doesn't execute .htaccess files. The router.php simulates the same rewrites:

<?php
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$uri = rtrim($uri, '/');

// EN blog articles
if (preg_match('#^/en/blog/([a-z0-9-]+)$#', $uri, $m)) {
    $file = __DIR__ . '/blog/posts/' . $m[1] . '.en.php';
    if (file_exists($file)) {
        require $file;
        return true;
    }
    // Fallback 404
    http_response_code(404);
    require __DIR__ . '/404.php';
    return true;
}

// EN blog listing
if ($uri === '/en/blog') {
    $_GET['lang'] = 'en';
    require __DIR__ . '/blog/index.php';
    return true;
}

The structure is identical to the Apache logic, translated to PHP. The classic trap here: forgetting to set $_GET['lang'] = 'en' before including index.php. If you test locally and the EN listing displays FR articles, that's where the bug lives.

Layer 3: detection in template.php

The template can receive $lang as a parameter (from articles), but it can also detect the language from the URL (for dynamic pages that don't go through blog_header()):

<?php
// Language detection from URL (fallback if $lang not provided)
function detect_lang(): string {
    $uri = $_SERVER['REQUEST_URI'] ?? '';
    return str_starts_with($uri, '/en/') ? 'en' : 'fr';
}

In practice, articles always pass $lang explicitly. Automatic detection primarily serves the listing and pages that don't have article context.

Template changes

html lang and og:locale

The most visible and simplest change:

<!DOCTYPE html>
<html lang="<?= $lang ?>">
<head>
    ...
    <meta property="og:locale" content="<?= $lang === 'en' ? 'en_US' : 'fr_FR' ?>">

hreflang tags

The hreflang tags tell search engines about alternative versions of a page. They go in the <head> and are generated from the article slug:

<?php if (!empty($article_data['slug'])): ?>
<link rel="alternate" hreflang="fr"
      href="<?= SITE_URL ?>/blog/<?= $article_data['slug'] ?>">
<link rel="alternate" hreflang="en"
      href="<?= SITE_URL ?>/en/blog/<?= $article_data['slug'] ?>">
<link rel="alternate" hreflang="x-default"
      href="<?= SITE_URL ?>/blog/<?= $article_data['slug'] ?>">
<?php endif; ?>

x-default points to the FR version — that's the site's default language. If a user arrives from a country without a localized version, they see FR. Google uses x-default for pages not geographically targeted.

Important: these tags must be reciprocal. The FR page must point to the EN page, and the EN page must point to the FR page. If you miss one direction, Google ignores both.

Adapted breadcrumbs

The breadcrumb changes depending on language — not just the text, but also the URLs:

<?php
$home_url   = $lang === 'en' ? SITE_URL . '/en' : SITE_URL;
$blog_url   = $lang === 'en' ? SITE_URL . '/en/blog' : SITE_URL . '/blog';
$home_label = $lang === 'en' ? 'Home' : 'Accueil';
$blog_label = 'Blog';
?>
<ol class="breadcrumb">
    <li><a href="<?= $home_url ?>"><?= $home_label ?></a></li>
    <li><a href="<?= $blog_url ?>"><?= $blog_label ?></a></li>
    <li class="active"><?= htmlspecialchars($title) ?></li>
</ol>

Language toggle with SVG flags

The navigation toggle shows the flag for the target language (not the current language — the other one). This avoids the paradox of "FR" displayed on a page already in French.

<?php
$toggle_url  = $lang === 'fr'
    ? SITE_URL . '/en/blog/' . ($article_data['slug'] ?? '')
    : SITE_URL . '/blog/'    . ($article_data['slug'] ?? '');
$toggle_lang = $lang === 'fr' ? 'EN' : 'FR';
$toggle_flag = $lang === 'fr' ? '🇬🇧' : '🇫🇷';
// Or SVG inline if emoji rendering is inconsistent
?>
<a href="<?= htmlspecialchars($toggle_url) ?>" class="lang-toggle"
   title="<?= $lang === 'fr' ? 'Read in English' : 'Lire en français' ?>">
    <?= $toggle_flag ?> <?= $toggle_lang ?>
</a>

If you prefer inline SVGs instead of emoji (more reliable on older OS/browsers), here's a compact example:

<?php if ($lang === 'fr'): ?>
<a href="<?= $toggle_url ?>" class="lang-toggle" title="Read in English">
    <svg width="18" height="12" viewBox="0 0 60 40" xmlns="http://www.w3.org/2000/svg">
        <rect width="60" height="40" fill="#012169"/>
        <path d="M0,0 L60,40 M60,0 L0,40" stroke="#fff" stroke-width="8"/>
        <path d="M0,0 L60,40 M60,0 L0,40" stroke="#C8102E" stroke-width="5"/>
        <path d="M30,0 V40 M0,20 H60" stroke="#fff" stroke-width="12"/>
        <path d="M30,0 V40 M0,20 H60" stroke="#C8102E" stroke-width="8"/>
    </svg>
    EN
</a>
<?php else: ?>
<a href="<?= $toggle_url ?>" class="lang-toggle" title="Lire en français">
    <svg width="18" height="12" viewBox="0 0 90 60" xmlns="http://www.w3.org/2000/svg">
        <rect width="30" height="60" fill="#002395"/>
        <rect x="30" width="30" height="60" fill="#EDEDED"/>
        <rect x="60" width="30" height="60" fill="#ED2939"/>
    </svg>
    FR
</a>
<?php endif; ?>

Migrating posts.json: the one-shot script

If you have existing articles with the flat structure, here's the migration script. Run it once from the project root:

<?php
// migrate-posts.php — delete after use
$json = file_get_contents('blog/posts.json');
$posts = json_decode($json, true);

$migrated = [];
foreach ($posts as $post) {
    // Already migrated?
    if (isset($post['fr'])) {
        $migrated[] = $post;
        continue;
    }

    $migrated[] = [
        'slug' => $post['slug'],
        'date' => $post['date'],
        'fr'   => [
            'title'    => $post['title'],
            'category' => $post['category'],
            'tags'     => $post['tags'],
            'excerpt'  => $post['excerpt'],
        ],
        'en'   => [
            'title'    => $post['title'],    // Translate manually
            'category' => $post['category'], // idem
            'tags'     => $post['tags'],
            'excerpt'  => $post['excerpt'],  // idem
        ],
    ];
}

file_put_contents(
    'blog/posts.json',
    json_encode($migrated, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
);
echo count($migrated) . " articles migrated.\n";

The script copies FR fields into EN as placeholders. You then rework the EN fields manually. Don't forget to delete migrate-posts.php after you're done — it's not an endpoint you want exposed in production.

Blog listing (index.php)

The listing reads posts.json in JavaScript and filters articles by current language. Two main changes.

Reading the current language

// Determine language from URL
const BLOG_LANG = window.location.pathname.startsWith('/en/') ? 'en' : 'fr';

Fetch with absolute path

This is the most common trap. Using a relative path to fetch posts.json:

// ❌ Relative path — PROBLEM on /en/blog/
fetch('posts.json')
  .then(r => r.json())

On /blog/, this fetch resolves to /blog/posts.json — correct. But on /en/blog/, it resolves to /en/blog/posts.json — 404. The file only exists in one place.

// ✅ Absolute path — works from any URL
fetch('/blog/posts.json')
  .then(r => r.json())
  .then(posts => renderPosts(posts, BLOG_LANG));

This was the first bug I hit after deploying the EN listing. Everything worked locally (router.php serves from the root, so relative paths happened to resolve correctly), but broke immediately on the real URL structure. Absolute paths are the only correct answer here.

Language filter in JS

function renderPosts(posts, lang) {
    // Filter articles that have a version in this language
    const filtered = posts.filter(post => post[lang] && post[lang].title);

    filtered.forEach(post => {
        const data = post[lang];
        const url  = lang === 'en'
            ? `/en/blog/${post.slug}`
            : `/blog/${post.slug}`;

        // Build card with data.title, data.excerpt, data.category, data.tags
        renderCard({ ...data, slug: post.slug, date: post.date, url });
    });
}

This means an article without an EN version simply doesn't appear in the EN listing. That's the correct behaviour — it's not a missing feature, it's the expected result of having a .en.php file as the gating condition.

Category filter translation

Category filter buttons change label depending on language. The FR → EN mapping is a simple constant:

// Categories are read dynamically from posts.json
// The labels come from the nested lang object, so no mapping needed:
// post.fr.category = "Retour d'expérience"
// post.en.category = "Lessons learned"
// They're already translated at the data level.

const categories = [...new Set(
    posts
        .filter(p => p[BLOG_LANG])
        .map(p => p[BLOG_LANG].category)
)].sort();

// Dynamically build filter buttons — no hardcoded list
categories.forEach(cat => {
    const btn = document.createElement('button');
    btn.className = 'btn-category';
    btn.dataset.category = cat;
    btn.textContent = cat;
    filterContainer.appendChild(btn);
});

Because category names are stored in posts.json per language, the buttons are already translated at the data level. No extra mapping layer needed.

Sitemap with hreflang

The XML sitemap must declare alternative URLs for each bilingual page. The xhtml namespace is required for xhtml:link tags:

<?php
$posts = json_decode(file_get_contents(__DIR__ . '/posts.json'), true);
header('Content-Type: application/xml; charset=utf-8');
echo '<?xml version="1.0" encoding="UTF-8"?>' . "\n";
?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
<?php foreach ($posts as $post): ?>
    <?php if (!empty($post['fr'])): ?>
    <url>
        <loc><?= SITE_URL ?>/blog/<?= $post['slug'] ?></loc>
        <lastmod><?= $post['date'] ?></lastmod>
        <changefreq>monthly</changefreq>
        <priority>0.8</priority>
        <xhtml:link rel="alternate" hreflang="fr"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <?php if (!empty($post['en'])): ?>
        <xhtml:link rel="alternate" hreflang="en"
                    href="<?= SITE_URL ?>/en/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="x-default"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <?php endif; ?>
    </url>
    <?php endif; ?>
    <?php if (!empty($post['en'])): ?>
    <url>
        <loc><?= SITE_URL ?>/en/blog/<?= $post['slug'] ?></loc>
        <lastmod><?= $post['date'] ?></lastmod>
        <changefreq>monthly</changefreq>
        <priority>0.7</priority>
        <xhtml:link rel="alternate" hreflang="fr"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="en"
                    href="<?= SITE_URL ?>/en/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="x-default"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
    </url>
    <?php endif; ?>
<?php endforeach; ?>
</urlset>

EN article priority (0.7) is slightly lower than FR articles (0.8) — the site defaults to French, FR articles are the source of truth. It's a convention, not a strict rule.

The "related articles" section at the bottom of a post must link to articles in the same language. If you're reading an EN article and the suggestions point to FR URLs, that's a bad experience.

The existing similarity calculation (see the dedicated article) is extended to filter by language before scoring:

<?php
function get_related_posts(
    string $current_slug,
    array $current_tags,
    string $current_category,
    string $lang = 'fr',
    int $limit = 3
): array {
    $posts = json_decode(file_get_contents(__DIR__ . '/../posts.json'), true);
    $scores = [];

    foreach ($posts as $post) {
        if ($post['slug'] === $current_slug) continue;

        // Filter: article must exist in the target language
        if (empty($post[$lang])) continue;

        $data  = $post[$lang];
        $score = 0;

        // Score by category
        if ($data['category'] === $current_category) $score += 3;

        // Score by shared tags
        $common = array_intersect($data['tags'] ?? [], $current_tags);
        $score += count($common) * 2;

        if ($score > 0) {
            $url = $lang === 'en'
                ? '/en/blog/' . $post['slug']
                : '/blog/'    . $post['slug'];

            $scores[] = [
                'url'   => $url,
                'title' => $data['title'],
                'score' => $score,
            ];
        }
    }

    usort($scores, fn($a, $b) => $b['score'] - $a['score']);

    return array_slice(
        array_map(fn($s) => ['url' => $s['url'], 'title' => $s['title']], $scores),
        0,
        $limit
    );
}

Called from article files:

<?php
// In my-slug.php (FR)
blog_footer(
    get_related_posts('my-slug', ['php', 'blog'], 'Retour d\'expérience', 'fr'),
    'my-slug',
    'fr'
);

// In my-slug.en.php (EN)
blog_footer(
    get_related_posts('my-slug', ['php', 'blog'], 'Lessons learned', 'en'),
    'my-slug',
    'en'
);

What you don't need

List of things I considered and decided against:

An i18n library (gettext, Symfony Translation, etc.) — For a blog, interface strings fit on two hands: "Read more", "Home", "min read". Two ternary operators in the template is sufficient. An i18n library with .po or .yaml files would be pure over-engineering.
Automatic language detection — Detecting Accept-Language and redirecting automatically is a bad idea. It breaks link sharing, surprises users, and causes indexation problems. The URL is the source of truth.
Database for translations — If your content is PHP files, your translations are PHP files. Architectural consistency has value in itself.
A single file with switch($lang) — Covered above. Unreadable once articles go past 200 lines.
Automatic translation (DeepL API, etc.) — Technically possible. But a technically dense blog article translated automatically is obvious to any developer. And it doesn't convince a recruiter that you can work in English. If the goal is demonstrating bilingualism, you actually have to write in English.

Summary of changed files

For an already-running blog, the exhaustive list of changes:

.htaccess — 2 RewriteRule lines for EN URLs
router.php — 2 corresponding PHP routing blocks
blog/template.php — blog_header() uses $lang for html[lang], og:locale, hreflang, breadcrumbs, nav, toggle; blog_footer() receives $lang to filter related articles
blog/posts.json — migrated to nested fr/en structure (one-shot script)
blog/index.php — absolute fetch /blog/posts.json, BLOG_LANG detection from URL, language filter, adapted URLs
blog/sitemap.php — added xhtml namespace and xhtml:link tags
For each existing article: blog/posts/slug.en.php to create

No new configuration files, no new dependencies, no stack change. All modifications are localized in files you're already maintaining.

In practice

This blog has been running with this architecture since the restructuring. Existing FR URLs haven't moved — no redirects to manage, no impact on already-indexed articles' rankings. EN versions are indexable as soon as they're created.

The only real cost is writing time: translating a 1000-word article takes between 30 minutes and an hour depending on technical density. That's the cost that can't be compressed — not the architecture.

If you already have a PHP blog without a framework and you're hesitating to add bilingual support because you think it's complex: the code isn't the hard part.

Bilingual FR/EN blog in pure PHP: architecture without framework or database

Why translate a developer blog

Architecture decisions

URL structure

One PHP file per language

Restructured posts.json

template.php receives $lang

The three routing layers

Layer 1: .htaccess for Apache

Layer 2: router.php for the built-in PHP server

Layer 3: detection in template.php

Template changes

html lang and og:locale

hreflang tags

Adapted breadcrumbs

Language toggle with SVG flags

Migrating posts.json: the one-shot script

Blog listing (index.php)

Reading the current language

Fetch with absolute path

Language filter in JS

Category filter translation

Sitemap with hreflang

What you don't need

Summary of changed files

In practice

Related articles

Comments (0)

Bilingual FR/EN blog in pure PHP: architecture without framework or database

Why translate a developer blog

Architecture decisions

URL structure

One PHP file per language

Restructured posts.json

template.php receives $lang

The three routing layers

Layer 1: .htaccess for Apache

Layer 2: router.php for the built-in PHP server

Layer 3: detection in template.php

Template changes

html lang and og:locale

hreflang tags

Adapted breadcrumbs

Language toggle with SVG flags

Migrating posts.json: the one-shot script

Blog listing (index.php)

Reading the current language

Fetch with absolute path

Language filter in JS

Category filter translation

Sitemap with hreflang

Related articles filtered by language

What you don't need

Summary of changed files

In practice

Related articles

Comments (0)