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.
Related articles filtered by language
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
.poor.yamlfiles would be pure over-engineering. - Automatic language detection — Detecting
Accept-Languageand 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— 2RewriteRulelines for EN URLs -
router.php— 2 corresponding PHP routing blocks -
blog/template.php—blog_header()uses$langforhtml[lang],og:locale,hreflang, breadcrumbs, nav, toggle;blog_footer()receives$langto filter related articles -
blog/posts.json— migrated to nestedfr/enstructure (one-shot script) -
blog/index.php— absolute fetch/blog/posts.json,BLOG_LANGdetection from URL, language filter, adapted URLs -
blog/sitemap.php— addedxhtmlnamespace andxhtml:linktags - For each existing article:
blog/posts/slug.en.phpto 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.