https://komeil.me/feeds/fa.xml 2026-06-01T00:00:00Z komeil https://komeil.me/fa/writing/bilingual-metadata 2026-04-22T00:00:00Z 2026-06-01T00:00:00Z

Hope is not a localization strategy.

<p>Bilingual sites fail quietly. An English page ships without a Persian alternate. A <code>lang</code> attribute lies. A feed mixes languages. Search indexes conflate scripts. Users adapt; SEO does not.</p><p>This site models language <strong>explicitly</strong>:</p><h2>translation_key</h2><p>Every post and page carries a <code>translation_key</code> shared across languages. English and Persian versions of the same essay use the same key. The build groups by key and requires exactly one entry per supported language for published content.</p><p>Missing translations are not warnings in production — they are build failures.</p><h2>URL structure</h2><p><code>/en/...</code> and <code>/fa/...</code>. No query-parameter language switching. No cookie-guessed locale for public content. The root <code>/</code> is a minimal selector with <code>hreflang</code> alternates.</p><h2>Metadata</h2><p>Every rendered page includes:</p><ul><li><code>lang</code> and <code>dir</code> on <code>&lt;html&gt;</code></li><li>Canonical URL</li><li><code>link rel=&quot;alternate&quot; hreflang=...</code> for each translation</li><li>Separate Atom and RSS feeds per language</li><li><code>sitemap.xml</code> entries with alternates</li></ul><h2>Search</h2><p>Per-language JSON indices at <code>/static/search-en.json</code> and <code>/static/search-fa.json</code>. Client-side normalisation unifies Persian character variants so typing is forgiving without mixing corpora.</p><h2>UI strings</h2><p>Navigation, form labels, and chrome strings live in a typed <code>i18n</code> catalogue — not scattered literals. The build checks that every key exists in both languages.</p><p>Explicit modeling costs author time. It saves the kind of embarrassment that only shows up in Search Console six months later.</p> https://komeil.me/fa/writing/static-first-publishing 2026-03-10T00:00:00Z 2026-07-16T00:00:00Z

The build is the editor's last line of defence.

<p>Most personal sites do not need a runtime. They need <strong>files</strong>, <strong>checks</strong>, and <strong>a deploy step you can explain in one sentence</strong>.</p><p>Static-first publishing means the production artifact is HTML on disk. The server — if there is one — handles the exceptions: forms, webhooks, admin tools. Not page rendering. Not content queries. Not template compilation at request time.</p><h2>What you gain</h2><ul><li><strong>Speed by default.</strong> No hydration tax, no framework boot, no layout shift from client rendering.</li><li><strong>Inspectable output.</strong> You can open <code>dist/en/writing/my-post/index.html</code> and see exactly what ships.</li><li><strong>Cheap hosting.</strong> Any object store or CDN works. Scale is someone else&#39;s problem.</li><li><strong>A real review surface.</strong> Content changes are diffs. Translation pairing is a build error, not a production surprise.</li></ul><h2>What you give up</h2><ul><li><strong>Instant publish without a build.</strong> Acceptable. A two-minute CI run is cheaper than operating a CMS database.</li><li><strong>Per-request personalization.</strong> Not missed on a personal site.</li><li><strong>Plugin ecosystems.</strong> Replaced by typed code you own.</li></ul><h2>The discipline</h2><p>Treat the build as part of the product. Translation validators, link checkers, and draft guards are not &quot;nice to have&quot; — they are how you keep a bilingual site honest without hiring an editor.</p><p>The contact form posts to <code>/api/contact</code>. Everything else is already HTML when the first byte leaves the CDN.</p>