<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Eray Gündoğmuş on Medium]]></title>
        <description><![CDATA[Stories by Eray Gündoğmuş on Medium]]></description>
        <link>https://medium.com/@gundogmuseray?source=rss-6702890b8f5f------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*AWpFHhlf50ICxXVsSPR4kg.jpeg</url>
            <title>Stories by Eray Gündoğmuş on Medium</title>
            <link>https://medium.com/@gundogmuseray?source=rss-6702890b8f5f------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 14:32:24 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@gundogmuseray/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[We Added a Headless CMS to Our i18n Platform — Here’s Why]]></title>
            <link>https://gundogmuseray.medium.com/we-added-a-headless-cms-to-our-i18n-platform-heres-why-94f66bc5b2a6?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/94f66bc5b2a6</guid>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[translation]]></category>
            <category><![CDATA[cms]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Thu, 19 Mar 2026 16:00:51 GMT</pubDate>
            <atom:updated>2026-03-19T16:00:51.087Z</atom:updated>
            <content:encoded><![CDATA[<p>Translations and content are the same problem. We just stopped pretending they aren’t.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sQZ396GYOphgwLVMNPpNnQ.png" /></figure><p>Two years into building Better i18n, we had a solid localization platform. CDN-delivered translations. AI-powered translation engine. SDKs for Next.js, React Native, Flutter, Remix, anything — the works.</p><p>Then our own marketing team broke the illusion.</p><h4>The Problem Nobody Talks About</h4><p>We needed a blog for our landing page. Multilingual, obviously — we’re a localization company.</p><p>So we looked at the usual suspects: <strong>Contentful, Sanity, Strapi.</strong></p><p>Every single one required us to:</p><ul><li>Set up a separate content platform</li><li>Configure language fields manually</li><li>Build a translation pipeline between the CMS and our own product</li><li>Pay for another SaaS subscription</li></ul><p>We were building a localization platform. And we were about to pipe content from an external CMS into our own system to translate it.</p><p><strong>The absurdity hit us like a wall.</strong></p><h3>Translations and Content Are the Same Problem</h3><p>Think about it. A translation key like <em>hero.title = “Ship globally, build locally”</em> and a blog post titled <em>“How We Scaled to 40 Languages”</em> have the<br> same lifecycle:</p><p>1. Someone writes text<br>2. That text needs to exist in multiple languages<br>3. It needs to reach users instantly — on web, mobile, API<br>4. Non-technical people need to edit it without opening a pull request</p><p>The only difference? One lives in a JSON file. The other lives in a CMS. Both need translation. Both need publishing. Both need a CDN.</p><blockquote><strong>So why are they in two different systems?</strong></blockquote><h4>CMS + TMS: The Merge That Should Have Happened Years Ago</h4><p>We decided to merge them. Better i18n became a<strong> Translation Management System and a Headless CMS in one platform.</strong></p><p>Here’s what that actually means in practice:</p><p>For developers: One SDK. One API key. One CDN.</p><p>Whether you’re fetching a <strong>t(“checkout.button”) </strong>translation or a blog post with its author, categories, and custom fields — it’s the same pipeline.</p><pre>// Translations<br> const t = useTranslations();<br> t(“hero.title”); // → “Ship globally, build locally”</pre><pre>// Content<br> const posts = await client<br> .from(“blog-posts”)<br> .eq(“status”, “published”)<br> .language(“en”)<br> .limit(10);</pre><p>Same auth. Same cache. Same fallback chain. No second platform to configure, monitor, or pay for.</p><p><strong>For content teams:</strong> Write a campaign slogan in the dashboard. It’s live on web, mobile, and API in 60 seconds. No PR. No deploy. No Slack message to<br> engineering asking “can someone push this?”</p><p><strong>For translators: </strong>The AI engine already understands context. It knows a “Submit” button needs a different tone than a “Submit your application”<br> heading. That same context-awareness now applies to CMS content — blog posts, landing pages, product descriptions. All of it.</p><h4>Why This Matters More Than It Sounds</h4><p>The traditional stack for a multilingual SaaS looks like this:</p><pre>Code → i18next/next-intl (translations in JSON)<br>Content → Contentful/Sanity (content in CMS)<br>Translation → Crowdin/Lokalise (translations managed separately)<br>Delivery → Build step → Deploy → Wait</pre><p>Four systems. Four billing cycles. Four sets of credentials. And a product manager waiting three days for a typo fix to reach production.</p><p>Our stack:</p><pre>Code → @better-i18n SDK (translations + content)<br>Management → Better i18n dashboard (translate + edit + publish)<br>Delivery → CDN (live in 60 seconds)</pre><p>One system. One source of truth.</p><p>When marketing changes a slogan, it updates across every language and every platform simultaneously. When a developer adds a new feature, the<br> content team can localize it without ever touching code. When an AI agent scans your codebase via MCP, it sees both your translation keys and your<br> content — and can create, translate, and publish without leaving the IDE.</p><h4>Localization-as-a-Service</h4><p>We’ve started calling this “<strong>Full-Stack i18n.</strong>” Not because it’s a buzzword, but because it’s the most honest description of what happened.</p><p>Localization used to be a library. You npm install’d it, you managed JSON files, you begged translators to use the right key format, and you<br> deployed when someone finally approved the PR.</p><p>We turned it into a service. A living, breathing layer that your entire organization — developers, content creators, translators, AI agents — can<br> interact with through their own preferred interface.</p><ul><li>Developers get type-safe SDKs and a CLI that scans for hardcoded strings</li><li>Content teams get a visual dashboard where changes go live instantly</li><li>Translators get AI-powered suggestions with glossary enforcement</li><li>AI agents get MCP tools that can manage translations from your IDE</li></ul><p>Nobody waits for anyone else. Nobody opens a ticket for a one-word change.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_mz_eaSifvUADRCCs3f4Kw.png" /></figure><h4>What We Learned</h4><p>Building the CMS wasn’t the hard part. The hard part was realizing that translations and content were never separate problems — we just treated<br> them that way because the tools forced us to.</p><p>The moment we stopped treating i18n as “that thing developers set up once and pray it doesn’t break,” everything clicked. It’s infrastructure. It’s<br> content delivery. It’s a service.</p><p>And services don’t live in JSON files.</p><p>Better i18n is open source. Free tier available. <a href="https://better-i18n.com/"><strong>https://better-i18n.com</strong></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=94f66bc5b2a6" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your AI Assistant Can Now Manage Translations From Your IDE]]></title>
            <link>https://gundogmuseray.medium.com/your-ai-assistant-can-now-manage-translations-from-your-ide-53f0ca575d49?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/53f0ca575d49</guid>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[localization]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Sun, 15 Mar 2026 22:47:53 GMT</pubDate>
            <atom:updated>2026-03-15T22:48:15.758Z</atom:updated>
            <content:encoded><![CDATA[<p>Last month, a well-meaning AI agent created <strong>1,005 phantom translation keys</strong> in our production namespace.</p><p>Wrong namespace. Bulk create. No guardrails.</p><p>Cleaning it up took hours.</p><p>That incident forced us to confront something we’d been quietly thinking about for a while:</p><p><strong>AI agents are going to manage translations whether we like it or not.</strong><br> The real question is whether the tooling around them is actually designed for that reality.</p><p>So we built <strong>MCP support</strong> into Better i18n.</p><p>Then we spent weeks doing the less glamorous part: making it much harder for agents to do something catastrophically stupid.</p><h3>AI agents are no longer “assistants”</h3><p>They’re becoming operators.</p><p>They don’t just suggest copy anymore. They create keys, update translations, inspect namespaces, propose languages, and publish changes. And increasingly, they do all of that from inside the IDE, during normal development flow.</p><p>That’s powerful.</p><p>It’s also dangerous if the system assumes the agent will always behave perfectly.</p><p>Our experience taught us the opposite: if you give an AI agent write access without strong guardrails, it will eventually make a mess at scale.</p><h3>What MCP is, in plain English</h3><p><strong>Model Context Protocol (MCP)</strong> is an open standard that lets AI assistants like <strong>Claude, Cursor, GPT, and Windsurf</strong> call external tools directly.</p><p>Instead of copying strings from a dashboard or manually editing translation files, your AI assistant can interact with your translation system through structured tools.</p><p>That means it can:</p><ul><li>inspect projects</li><li>see namespaces and languages</li><li>find missing translations</li><li>read source text</li><li>write translations</li><li>preview pending changes</li><li>publish updates</li></ul><p>In practice, it gives your AI assistant the ability to work with your localization system using the same primitives your team would use — just much faster.</p><h3>What an AI agent can actually do</h3><p>Here’s a real example.</p><p>You’re building a feature and realize the auth namespace is missing Turkish translations.</p><p>You say:</p><blockquote>Add Turkish translations for all missing keys in the auth namespace.</blockquote><p>The agent can then do the whole workflow end-to-end:</p><ol><li>Call listKeys({ namespace: &quot;auth&quot;, missingLanguage: &quot;tr&quot; })</li><li>Find the missing keys</li><li>Read the English source text with getTranslations()</li><li>Generate Turkish translations using your glossary and terminology rules</li><li>Write them with updateKeys()</li><li>Call getPendingChanges() so you can review what will be published</li><li>Wait for your confirmation</li><li>Publish with publishTranslations()</li></ol><p>No dashboard hopping.<br>No JSON file editing.<br>No translation spreadsheet.<br>No extra PR just to patch missing content.</p><p>It all happens inside your IDE, while you’re already building the feature.</p><h3>The toolset behind it</h3><p>At a high level, the MCP server exposes three kinds of capabilities.</p><h3>Read tools</h3><p>These are the tools agents use to understand the state of your translation system:</p><ul><li>listProjects — see all accessible projects</li><li>getProject — inspect namespaces, languages, and coverage</li><li>listKeys — search keys, filter by namespace, find missing translations</li><li>getTranslations — retrieve source text and existing translations</li><li>getPendingChanges — preview what will deploy</li></ul><h3>Write tools</h3><p>These let agents make controlled changes:</p><ul><li>createKeys — create new keys with source text and translations</li><li>updateKeys — update translations for existing keys</li><li>deleteKeys — soft-delete keys, applied on next publish</li><li>proposeLanguages — suggest or add target languages</li></ul><h3>Publish tools</h3><p>These push changes live:</p><ul><li>publishTranslations — deploy pending changes to CDN or GitHub</li></ul><p>That’s the happy path.</p><p>But the real story isn’t that AI can do these things.</p><p>The real story is how easily it can do the wrong thing if the tools are naive.</p><h3>The 1,005 phantom keys incident</h3><p>The original failure looked simple.</p><p>An AI agent was asked to “add translations for the checkout flow.”</p><p>Instead of behaving cautiously, it did this:</p><ol><li>Assumed a namespace that didn’t exist</li><li>Used createKeys instead of updateKeys</li><li>Bulk-created <strong>1,005 keys</strong></li><li>Published them</li></ol><p>From the agent’s point of view, it had completed the task.</p><p>From ours, it had polluted production with junk.</p><p>That failure made one thing obvious:</p><p><strong>MCP support is not enough. Tool safety matters just as much as tool availability.</strong></p><h3>Why tool descriptions matter more than people think</h3><p>One of the most important things we learned is that LLMs often treat tool descriptions almost like system prompts.</p><p>That means the description isn’t just documentation for humans. It’s also behavioral guidance for the agent.</p><p>So we rewrote our MCP tool descriptions to act as guardrails.</p><p>Instead of short, neutral descriptions, we made them defensive and explicit.</p><p>For example, a createKeys description now includes warnings like:</p><blockquote>IMPORTANT: Before creating keys, ALWAYS call listKeys first to check<br>if keys already exist. Use updateKeys to modify existing translations.<br>createKeys is for NEW keys only.</blockquote><blockquote>Namespace must match an existing namespace in the project.<br>Call getProject first to see available namespaces.</blockquote><p>This does a few things at once:</p><ul><li>it teaches the correct workflow</li><li>it warns against common misuse</li><li>it reduces ambiguity</li><li>it nudges the agent toward safer operations</li></ul><p>That alone significantly reduces bad behavior.</p><p>But we didn’t stop there.</p><h3>Descriptions prevent mistakes. Responses catch them.</h3><ul><li>specify the namespace</li><li>specify the language</li><li>specify the workflow</li><li>require review before publish</li></ul><p>Good tool design helps a lot. Good prompts help even more.</p><h3>Setting it up</h3><p>If you want to use Better i18n with MCP, the setup is straightforward.</p><p>Install the framework SDK:</p><pre>npm install @better-i18n/core @better-i18n/next</pre><p>Then install the MCP package:</p><pre>npm install @better-i18n/mcp</pre><p>For Claude Code, your config might look like this:</p><pre>{<br>  &quot;mcpServers&quot;: {<br>    &quot;better-i18n&quot;: {<br>      &quot;command&quot;: &quot;npx&quot;,<br>      &quot;args&quot;: [&quot;-y&quot;, &quot;@anthropic-ai/mcp-server&quot;, &quot;--config&quot;, &quot;better-i18n.json&quot;]<br>    }<br>  }<br>}</pre><p>In Cursor, you can add the Better i18n MCP server through the MCP settings panel and point it at the package configuration.</p><h3>Why we cared so much about safety</h3><p>The flashy part of MCP is obvious: your AI assistant can now manage translations directly from your IDE.</p><p>The non-flashy part is the one that matters more in the long run:</p><p><strong>you need to be able to trust the agent not to wreck production while doing it.</strong></p><p>That trust doesn’t come from hype.</p><p>It comes from:</p><ul><li>defensive tool design</li><li>explicit workflows</li><li>misuse warnings</li><li>publish previews</li><li>strong descriptions</li><li>response-level validation</li></ul><p>The phantom key incident was painful, but useful.</p><p>It forced us to design for the reality of AI behavior instead of the fantasy of perfect AI behavior.</p><p>And honestly, that’s probably the right way to build any AI-facing infrastructure.</p><h3>Getting started</h3><p>Better i18n supports both <strong>translation MCP</strong> and <strong>content MCP</strong>, and both are open source.</p><p>Free tier includes:</p><ul><li>5 projects</li><li>100 AI messages per month</li></ul><p>You can explore everything here:</p><ul><li><strong>Platform:</strong> better-i18n.com</li><li><strong>GitHub:</strong> github.com/better-i18n</li><li><strong>Docs:</strong> docs.better-i18n.com</li></ul><p>The phantom key incident was real.</p><p>We learned from it.</p><p>And that lesson shaped the product more than any happy-path demo ever could.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=53f0ca575d49" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Next.js i18n Made Easy: Build Multilingual Apps with App Router in 2026]]></title>
            <link>https://gundogmuseray.medium.com/next-js-i18n-made-easy-build-multilingual-apps-with-app-router-in-2026-236151f37d60?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/236151f37d60</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[nextjs]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Tue, 03 Mar 2026 17:16:27 GMT</pubDate>
            <atom:updated>2026-03-03T17:16:27.993Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-85u3evwsCy0usG5jWXVXA.png" /><figcaption>better-i18n.com</figcaption></figure><p>Building a multilingual app with Next.js shouldn’t require a weekend of configuration. Yet if you’ve tried adding internationalization to a Next.js App Router project, you know the pain — middleware routing headaches, the Server Component vs. Client Component split, and the eternal question of where translations actually get loaded.</p><p>I’ve been there. After struggling with the same problems across multiple projects, I built a production-ready starter template that handles all of this out of the box. Here’s how it works and how you can use it.</p><h3>The Problem with i18n in Next.js App Router</h3><p>The App Router introduced a fundamental shift in how React apps work. Server Components, streaming, parallel routes — all great for performance. But they created three specific headaches for internationalization:</p><p><strong>1. Middleware routing is tricky.</strong> You need to detect the user’s locale, redirect to the right path prefix (/en/about, /tr/about), and handle edge cases like missing locales or static assets. Most tutorials show you a 50-line middleware file that breaks the moment you add an API route.</p><p><strong>2. Server vs. Client components.</strong> Translations need to be available on both sides. Server Components can’t use React hooks. Client Components can’t call server-only APIs. You end up duplicating translation logic or creating awkward bridges between the two.</p><p><strong>3. Translation loading at scale.</strong> Hardcoding translations in JSON files works for 2 languages. But when you need 10+ languages, managing files becomes a nightmare. And every time a translator updates a string, you need a new deployment.</p><h3>The Solution: Cloud-Managed Translations + A Starter Template</h3><p><a href="https://better-i18n.com/">better-i18n</a> solves the translation management problem — translations live in the cloud, delivered via CDN, updated without redeployment. But you still need to wire it into your Next.js project correctly.</p><p>That’s why I created the <a href="https://github.com/better-i18n/nextjs-i18n-starter">nextjs-i18n-starter</a> — a production-ready template that combines Next.js 15, App Router, and better-i18n with all the routing, SSR, and locale switching already configured.</p><p><strong>Live demo:</strong> <a href="https://nextjs-i18n-starter.vercel.app/en">nextjs-i18n-starter.vercel.app</a> (try switching between 15 languages)</p><h3>Step-by-Step: How It Works</h3><h3>1. Clone &amp; Setup</h3><pre>npx create-next-app -e https://github.com/better-i18n/nextjs-i18n-starter my-i18n-app<br>cd my-i18n-app</pre><p>Create a free project at <a href="https://dash.better-i18n.com/">dash.better-i18n.com</a>, add your languages, and copy the project identifier:</p><pre># .env<br>NEXT_PUBLIC_BETTER_I18N_PROJECT=your-org/your-project</pre><pre>npm run dev</pre><p>That’s it. Open http://localhost:3000 and you have a multilingual app.</p><h3>2. The Config (One File, One Function)</h3><p>The entire i18n configuration lives in a single file:</p><pre>// i18n.config.ts<br>import { createI18n } from &quot;@better-i18n/next&quot;;<br>export const i18n = createI18n({<br>  project: process.env.NEXT_PUBLIC_BETTER_I18N_PROJECT || &quot;better-i18n/demo&quot;,<br>  defaultLocale: &quot;en&quot;,<br>  localePrefix: &quot;always&quot;,<br>});</pre><p>This i18n object is the single source of truth. It provides middleware, message loading, locale discovery — everything.</p><h3>3. Middleware (One Line)</h3><pre>// middleware.ts<br>import { i18n } from &quot;./i18n.config&quot;;<br>export default i18n.betterMiddleware();<br>export const config = {<br>  matcher: [&quot;/((?!api|_next/static|_next/image|favicon.ico).*)&quot;],<br>};</pre><p>No 50-line locale detection function. No manual redirect logic. One line.</p><h3>4. Server-Side Translation Loading</h3><p>The locale layout loads translations on the server and passes them to the provider:</p><pre>// src/app/[locale]/layout.tsx<br>export default async function LocaleLayout({ children, params }) {<br>  const { locale } = await params;<br>  const messages = await i18n.getMessages(locale);<br>  return (<br>    &lt;html lang={locale}&gt;<br>      &lt;body&gt;<br>        &lt;BetterI18nProvider<br>          config={i18n.config}<br>          locale={locale}<br>          messages={messages}<br>        &gt;<br>          {children}<br>        &lt;/BetterI18nProvider&gt;<br>      &lt;/body&gt;<br>    &lt;/html&gt;<br>  );<br>}</pre><p>Translations are fetched server-side from the CDN — no flash of untranslated content, no client-side loading spinners.</p><h3>5. Client-Side Locale Switching</h3><p>The language switcher uses useSetLocale() from the better-i18n SDK to switch languages instantly without a full page reload:</p><pre>// src/components/LanguageSwitcher.tsx<br>&quot;use client&quot;;<br>import { useSetLocale, useManifestLanguages } from &quot;@better-i18n/next/client&quot;;<br>export function LanguageSwitcher() {<br>  const setLocale = useSetLocale();<br>  const { languages } = useManifestLanguages(i18n.config);<br>  function handleLocaleChange(newLocale: string) {<br>    setLocale(newLocale);<br>    router.replace(pathname.replace(/^\/[^/]+/, `/${newLocale}`));<br>  }<br>  return (<br>    &lt;Select value={locale} onValueChange={handleLocaleChange}&gt;<br>      {languages.map((lang) =&gt; (<br>        &lt;SelectItem key={lang.code} value={lang.code}&gt;<br>          {lang.nativeName || lang.code}<br>        &lt;/SelectItem&gt;<br>      ))}<br>    &lt;/Select&gt;<br>  );<br>}</pre><p>The useManifestLanguages hook dynamically discovers available languages from your better-i18n project — add a new language in the dashboard, it shows up automatically.</p><h3>6. Using Translations in Pages</h3><p>In any page or component, use the standard useTranslations hook:</p><pre>// src/app/[locale]/page.tsx<br>import { useTranslations } from &quot;next-intl&quot;;<br>export default function HomePage() {<br>  const t = useTranslations(&quot;home&quot;);<br>  return (<br>    &lt;div&gt;<br>      &lt;h1&gt;{t(&quot;hero.title&quot;)}&lt;/h1&gt;<br>      &lt;p&gt;{t(&quot;hero.subtitle&quot;)}&lt;/p&gt;<br>    &lt;/div&gt;<br>  );<br>}</pre><h3>Try It Yourself</h3><p>Check out the live demo at <a href="https://nextjs-i18n-starter.vercel.app/en">nextjs-i18n-starter.vercel.app</a> — switch between 15 languages and see how the routing, SSR, and locale switching work together.</p><p><strong>Get started:</strong></p><ul><li><a href="https://github.com/better-i18n/nextjs-i18n-starter">GitHub repo</a> — clone, customize, deploy</li><li><a href="https://dash.better-i18n.com/">better-i18n Dashboard</a> — manage your translations in the cloud</li><li><a href="https://docs.better-i18n.com/">Documentation</a> — full API reference and guides</li></ul><p>If this saved you some i18n headaches, give the repo a ⭐ on GitHub. Happy internationalizing!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=236151f37d60" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Definitive Guide to i18n Libraries for Next.js & React in 2026]]></title>
            <link>https://gundogmuseray.medium.com/the-definitive-guide-to-i18n-libraries-for-next-js-react-in-2026-8102c7f68a77?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/8102c7f68a77</guid>
            <category><![CDATA[react]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[localization]]></category>
            <category><![CDATA[nextjs]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Mon, 02 Mar 2026 15:28:46 GMT</pubDate>
            <atom:updated>2026-06-16T12:37:50.525Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How to choose the right internationalization library — with honest trade-offs, real-world considerations, and a framework for deciding.</em></p><p>The i18n landscape in React and Next.js has transformed dramatically. The App Router killed the old next-i18next approach. React Server Components rewired how translations load. And AI-powered localization — once a buzzword — is now shipping in production tools.</p><p>If you’re choosing an i18n library in 2026, you’re not just picking a translation function. You’re choosing a workflow, a philosophy, and a set of trade-offs that will stay with you for years.</p><p>I’ve spent months evaluating the ecosystem. Here’s what I found — starting with the platform I work on (with full transparency about what it does and doesn’t do well), followed by every major alternative.</p><h3>A Note on Honesty</h3><p>I work on <strong>Better i18n</strong>, so I list it first and know its features best. But I’m not here to sell you on it — I’m here to help you pick the right tool. For some projects, next-intl is the clear winner. For others, react-i18next makes more sense. I’ll tell you when.</p><h3>The Libraries</h3><h3>1. Better i18n — The Full Platform Approach</h3><p>Most i18n libraries solve one problem: rendering translated strings in your components. <a href="http://better-i18n.com/"><strong><em>Better i18n</em></strong></a> solves the entire pipeline — from finding translation keys in your source code to delivering translations via a global CDN.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-85u3evwsCy0usG5jWXVXA.png" /><figcaption>better-i18n.com</figcaption></figure><p><strong>What makes it different:</strong></p><p><strong>AI translations that actually understand your product.</strong> Not generic Google Translate output. Better i18n crawls your website, builds a context manifest, learns your glossary, and produces translations that match your brand voice. A translator can review and approve — or the AI handles it end-to-end.</p><p><strong>Git-native workflow.</strong> You don’t export JSON files, upload them somewhere, wait for translators, then download and re-import. Better i18n scans your repo via AST, discovers keys automatically, and sends translations back as GitHub pull requests. The whole cycle is automated.</p><p><strong>Instant CDN delivery.</strong> When a translator approves a change, it’s live on Cloudflare’s edge network in seconds — sub-50ms globally. No rebuild. No redeploy. Your users see updated translations immediately.</p><p><strong>MCP integration for AI-native developers.</strong> If you use Claude or Cursor, you can manage translations directly from your AI assistant via the Model Context Protocol. No other localization platform offers this.</p><p><strong>11 framework SDKs.</strong> React, Next.js (App Router + Pages), Vue, Angular, Svelte, Nuxt, Remix, Astro, TanStack Start, Vite, and Expo. One platform, every framework.</p><p><strong>The honest limitations:</strong></p><ul><li>It’s a platform, not just a library. If you want a zero-dependency npm package with no external service, this isn’t for you.</li><li>The community is smaller than react-i18next’s massive ecosystem.</li><li>The free tier covers 1,000 keys and 2 languages. Beyond that, it’s $19/month.</li><li>It’s newer. You won’t find five years of Stack Overflow answers.</li></ul><p><strong>Best for:</strong> Teams that want one tool for the entire localization workflow — key discovery, AI translation, review, CDN delivery — without stitching together three or four services.</p><h3>2. next-intl — Simplicity Done Right</h3><p>If you’re building a Next.js-only project and want to be productive in 15 minutes, next-intl is the answer. It’s lightweight (457 bytes gzipped), well-documented, and designed specifically for the App Router.</p><p>You define your locales, drop JSON files in a folder, and use useTranslations() in your components. Middleware handles locale detection. Navigation helpers generate locale-aware links. It just works.</p><p><strong>Why developers love it:</strong></p><ul><li>Minutes to set up, not hours</li><li>First-class Server Component support</li><li>Active maintenance and responsive community</li><li>Middleware-based locale detection</li></ul><p><strong>Where it falls short:</strong></p><ul><li>Next.js only. If you also have a React Native app, a Vue admin panel, or an Astro marketing site, you need a second library.</li><li>No TMS, no AI translation, no CDN. You manage JSON files manually or integrate with an external platform.</li><li>No React Native or Expo support.</li></ul><p><strong>Best for:</strong> Next.js-only projects where simplicity is the top priority.</p><h3>3. react-i18next — The Industry Standard</h3><p>There’s a reason react-i18next is the most downloaded i18n library for React. It’s been around for years, has a massive plugin ecosystem, and works everywhere — React, React Native, Next.js, even plain Node.js.</p><p>If your team already knows i18next from a previous project, switching to it is frictionless. Namespaces, lazy loading, interpolation, pluralization — it supports everything. The community knowledge is enormous. Every question has been asked and answered on Stack Overflow.</p><p><strong>The trade-offs:</strong></p><ul><li>More boilerplate than modern alternatives. You’ll write more configuration code.</li><li>Type safety requires extra setup (i18next doesn’t generate types by default).</li><li>Server-side rendering with the App Router needs careful configuration.</li><li>The bundle is larger (~6KB) than newer, tree-shakeable alternatives.</li></ul><p><strong>Best for:</strong> Large teams with existing i18next experience, or projects that need maximum flexibility and community support.</p><h3>4. LinguiJS — Compile-Time Guarantees</h3><p>LinguiJS takes a radically different approach. Instead of loading JSON at runtime, it compiles translations at build time. You write messages using &lt;Trans&gt; macros in your JSX, run an extraction step, send the files to translators, and compile the results into optimized bundles.</p><p>The output is tiny (~2KB runtime). The build catches missing translations before your users do. And because only used messages are included, tree-shaking is automatic.</p><p><strong>The cost:</strong></p><ul><li>You need Babel or SWC plugin configuration.</li><li>The extraction → translation → compilation cycle adds CI/CD complexity.</li><li>The macro-based API has a learning curve.</li><li>The community is smaller than react-i18next.</li></ul><p><strong>Best for:</strong> Performance-critical applications where bundle size matters and your team is comfortable with build tooling.</p><h3>5. Paraglide (by Inlang) — Type Safety as a First-Class Citizen</h3><p>Paraglide generates typed functions from your translation messages. Instead of t(&quot;some.key&quot;) and hoping the key exists, you call m.someKey() and the compiler verifies it exists.</p><p>It also supports translated pathnames — your URLs can be /en/about and /fr/a-propos without hacky rewrites. The Inlang ecosystem provides a GUI for translators.</p><p><strong>The considerations:</strong></p><ul><li>The ecosystem is younger. Fewer production case studies than react-i18next.</li><li>No React Native support.</li><li>Code generation adds a step to your workflow.</li></ul><p><strong>Best for:</strong> Web projects where type safety and localized URLs are non-negotiable.</p><h3>6. FormatJS (react-intl) — The ICU Powerhouse</h3><p>If your application needs complex message formatting — plural rules that vary by locale, gender-dependent variations, select statements, rich text interpolation — FormatJS is the most complete implementation of the ICU MessageFormat standard.</p><p><strong>The trade-off:</strong> It’s the largest library on this list (~20KB gzipped). For simple key-value translations, it’s overkill.</p><p><strong>Best for:</strong> Apps with complex linguistic requirements across many locales.</p><h3>7. Intlayer — Enterprise SEO Integration</h3><p>Intlayer takes a per-component approach: one component, one co-located dictionary. It ships strict TypeScript types, build-time missing-key detection, and built-in SEO helpers for hreflang and localized meta tags. Its standout property is build-time optimization — it detects which dictionaries each component actually uses and tree-shakes the rest, so gzipped it lands around ~15KB vs ~31KB for next-intl and ~25KB for next-i18next in its own Next.js benchmark</p><p>Correction from my first draft: I called Intlayer “heavier” — that was wrong. The build-time tree-shaking is the whole point, and at scale it’s the lighter option, not the heavier one. Thanks to the reader who flagged this.</p><p><strong>The trade-off:</strong> <br> The content-declaration model (co-located files) is opinionated — migrating a JSON-based app means restructuring content, not just swapping a translation. AI translation is bring-your-own-key and CLI-driven; you orchestrate it locally rather than getting a managed discovery → review → delivery pipeline. It’s largely a single-maintainer project (~760 stars), so the community and Stack Overflow corpus are smaller than react-i18next’s.<br><strong> Best for: </strong>projects that want maximum bundle efficiency, strict type safety, and component-scoped translations, and are comfortable adopting its authoring model</p><h3>8. typesafe-i18n — Zero Dependencies, Full Types</h3><p>The smallest runtime on this list (~1KB) with full TypeScript type safety. No external dependencies. It generates types from your translations, so every key is autocompleted.</p><p><strong>The catch:</strong> The last major release was in 2023. The custom message format isn’t standard ICU.</p><p><strong>Best for:</strong> Smaller projects that want minimal overhead and maximum type safety.</p><h3>The Decision Framework</h3><p>After evaluating dozens of projects, I’ve found that three questions cut through the noise:</p><h3>Question 1: Do you need a library or a platform?</h3><p>A <strong>library</strong> handles rendering translations in your components. You manage the rest (files, translators, deployment).</p><p>A <strong>platform</strong> handles the entire workflow — key discovery, translation, review, delivery.</p><ul><li><strong>Library:</strong> next-intl, react-i18next, LinguiJS, Paraglide, FormatJS, typesafe-i18n</li><li><strong>Platform:</strong> Better i18n (also Crowdin, Lokalise, Phrase — but at 3–20× the price)</li></ul><h3>Question 2: How many frameworks do you support?</h3><p>If you’re Next.js only, next-intl is the fastest path. If you have React + React Native + a Vue admin panel, you need either react-i18next (with framework-specific bindings) or a platform like Better i18n that has SDKs for all of them.</p><h3>Question 3: What’s your bundle budget?</h3><p>If every kilobyte matters (mobile web, slow connections, Core Web Vitals targets):</p><ul><li>LinguiJS (~2KB, compiled)</li><li>typesafe-i18n (~1KB, generated)</li><li>next-intl (457B)</li></ul><p>If you’re fine with a few extra KB for more features:</p><ul><li>react-i18next (~6KB)</li><li>Better i18n SDK (~2KB + CDN fetch)</li></ul><p>Changing your i18n library mid-project is one of the most painful refactors in frontend development. It touches every component. It affects routing. It changes your build pipeline. It disrupts your translation workflow.</p><p>Take the time to evaluate now. Build a proof-of-concept with your top two choices. Talk to your translators, not just your engineers. The best i18n solution is the one that works for your entire team — developers, translators, and product managers alike.</p><p><em>I’d love to hear what you’re using.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8102c7f68a77" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Scaling i18n Beyond Lazy Loading: What Framework Comparisons Miss About Real-World Localization]]></title>
            <link>https://gundogmuseray.medium.com/scaling-i18n-beyond-lazy-loading-what-framework-comparisons-miss-about-real-world-localization-6e4defaa3fc3?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/6e4defaa3fc3</guid>
            <category><![CDATA[localization]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Mon, 02 Mar 2026 13:47:43 GMT</pubDate>
            <atom:updated>2026-03-02T13:47:43.391Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Namespace splitting and dynamic imports solve the bundle problem. They don’t solve the other five.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-85u3evwsCy0usG5jWXVXA.png" /></figure><h3>I’ve read a lot of “how we scaled our i18n” posts. They almost all follow the same arc: team evaluates frameworks, picks i18next or FormatJS, implements lazy loading per namespace, ships it, writes the blog post. Bundle size goes down, page load improves, everyone’s happy.</h3><p>I know because we wrote that exact post internally 18 months ago. Then we spent the next 12 months dealing with everything the framework comparison didn’t cover.</p><p>This post is about those 12 months. Not the framework choice — the infrastructure, workflow, and operational problems that show up at scale but never make it into the comparison table.</p><h3>The framework comparison trap</h3><p>Most i18n framework evaluations look something like this:</p><p><strong>| Criteria | i18next | FormatJS | Polyglot |</strong></p><p>|<strong> Bundle size (core) </strong>| ~40KB | ~32KB | ~3KB |</p><p>|<strong> Lazy loading </strong>| Plugin-based | Built-in | Manual |</p><p><strong>| ICU support </strong>| Plugin | Native | None |</p><p>|<strong> React integration </strong>| react-i18next | react-intl | Manual |</p><p>| <strong>TypeScript</strong> | Good | Good | Weak |</p><p>| <strong>Community</strong> | Large | Large | Small |</p><p>This is accurate and useful for picking a library. It is almost entirely useless for predicting what your localization workflow will look like at 500+ keys, 6+ languages, and a team of 8+ developers shipping weekly.</p><p>Here’s what the comparison table doesn’t tell you:</p><ol><li>How will you detect unused translation keys after a refactor?</li><li>What happens when two feature branches modify the same locale file?</li><li>How long does it take to push a one-word translation fix to production?</li><li>How will your translators get context about what they’re translating?</li><li>Who maintains the mapping between translation keys and the codebase?</li></ol><p>These are the problems that actually consume engineering time. The framework is a pipe fitting. The plumbing is everything else.</p><h3>Problem 1: The namespace illusion</h3><p>Namespace splitting is the first optimization every team implements. Instead of one massive translation.json, you split into auth.json, dashboard.json, settings.json, etc.</p><pre>// i18next namespace config<br>i18n.init({<br>  ns: [&#39;common&#39;, &#39;auth&#39;, &#39;dashboard&#39;, &#39;settings&#39;, &#39;billing&#39;],<br>  defaultNS: &#39;common&#39;,<br>  backend: {<br>    loadPath: &#39;/locales/{{lng}}/{{ns}}.json&#39;,<br>  },<br>});</pre><p>With lazy loading, each namespace loads on demand:</p><pre>// Only loads &#39;dashboard&#39; namespace when this route mounts<br>const DashboardPage = () =&gt; {<br>  const { t } = useTranslation(&#39;dashboard&#39;);<br>  return &lt;h1&gt;{t(&#39;title&#39;)}&lt;/h1&gt;;<br>};</pre><p>Bundle problem: solved. Performance: improved. Blog post: written.</p><p>But here’s what happens next.</p><h3>The namespace decision tax</h3><p>Developer writes a new error component for the billing page. Where does billing.errors.cardDeclined go? In billing.json or errors.json? If you have both namespaces, now you have a naming convention meeting. If you decide it goes in billing.json, what happens when the same error also shows on the settings page where users update their payment method?</p><p>We tracked this over 4 sprints. Developers spent an average of <strong>7 minutes per new key</strong> deciding which namespace it belonged to. With 15–20 new keys per sprint, that’s 2+ hours of namespace deliberation per sprint across the team. And that’s before the reviewer disagrees and asks for a rename.</p><h3>The cross-namespace import problem</h3><p>Components that span multiple features need multiple namespaces:</p><pre>// A notification component that shows messages from different domains<br>const NotificationItem = ({ notification }) =&gt; {<br>  const { t: tBilling } = useTranslation(&#39;billing&#39;);<br>  const { t: tAuth } = useTranslation(&#39;auth&#39;);<br>  const { t: tDashboard } = useTranslation(&#39;dashboard&#39;);<br>  const getMessage = () =&gt; {<br>    switch (notification.domain) {<br>      case &#39;billing&#39;: return tBilling(`notifications.${notification.key}`);<br>      case &#39;auth&#39;: return tAuth(`notifications.${notification.key}`);<br>      case &#39;dashboard&#39;: return tDashboard(`notifications.${notification.key}`);<br>    }<br>  };<br>  return &lt;p&gt;{getMessage()}&lt;/p&gt;;<br>};</pre><p>This defeats the purpose of lazy loading. You’re now loading 3 namespaces for a single component. Worse, you’ve created implicit coupling between namespaces and feature boundaries that breaks every time someone moves a component.</p><h3>What actually works</h3><p>Flat keys with convention-based prefixes, no namespace boundaries:</p><pre>// No namespaces. One flat map. Convention handles organization.<br>const t = useTranslations(&#39;billing&#39;);<br>t(&#39;errors.cardDeclined&#39;);     // → &quot;billing.errors.cardDeclined&quot;<br>t(&#39;notifications.overdue&#39;);   // → &quot;billing.notifications.overdue&quot;</pre><p>The namespace is a logical prefix, not a file boundary. No files to split. No lazy loading configuration per namespace. The entire locale payload is edge-cached on a CDN and delivered in a single request.</p><p>“But won’t that be slow?” At 1,000 keys, a gzipped JSON payload is ~18KB. That’s smaller than most hero images. At 5,000 keys, it’s ~70KB. A single CDN request at ~2ms from the nearest PoP beats the waterfall of 8 namespace requests at ~40ms each, every time.</p><h3>Problem 2: The merge conflict multiplier</h3><p>If your translations live as JSON files in the repo, every feature branch that adds a key modifies the same file. With a team of 6 developers, you’re touching en.json in every sprint, often in every PR.</p><p>Git’s diff algorithm treats JSON as text. A single reordered key produces a multi-line diff. Two developers adding keys in the same file — even in different sections — produces a merge conflict because JSON doesn’t have a natural merge strategy.</p><pre>// Developer A adds key at line 847<br>&quot;billing.newPlan.title&quot;: &quot;Choose your plan&quot;,<br>// Developer B adds key at line 848<br>&quot;billing.upgrade.cta&quot;: &quot;Upgrade now&quot;,<br>// Git: CONFLICT</pre><p>Namespace splitting reduces conflict frequency but doesn’t eliminate it. With 5 namespaces and 6 developers, you still get 1–2 conflicts per sprint. Each conflict requires someone to manually resolve a JSON file, re-validate the JSON syntax, and re-run the translation CI check.</p><h3>What actually works</h3><p>Remove JSON files from the repo entirely.</p><pre>// Translations fetched from CDN at request time<br>import { getMessages } from &#39;@better-i18n/use-intl/server&#39;;<br>export default async function Layout({ children, params: { locale } }) {<br>  const messages = await getMessages({<br>    project: &#39;my-app&#39;,<br>    locale,<br>  });<br>  return (<br>    &lt;IntlProvider locale={locale} messages={messages}&gt;<br>      {children}<br>    &lt;/IntlProvider&gt;<br>  );<br>}</pre><p>No locales/ directory in the repo. No JSON files to conflict. Keys are managed on a platform and served via CDN. If you want a Git record, the platform creates archive PRs — but they&#39;re documentation, not source of truth.</p><p>The Git PR flow inverts:</p><pre>Before:  Code → JSON files → TMS → JSON files → Merge conflicts<br>After:   Code → Platform → CDN (live) + Git PR (archive)</pre><h3>Problem 3: The ghost key problem</h3><p>After 6 months of active development, we had 2,400 translation keys. After running a dead code analysis, 340 of them (14%) weren’t referenced anywhere in the codebase.</p><p>These ghost keys accumulated over multiple refactors. When you rename a component from &lt;OnboardingWizard&gt; to &lt;SetupFlow&gt;, the code changes but nobody remembers to delete onboarding.wizard.step1.title from the JSON file. Why? Because deleting a key feels risky. What if it&#39;s used somewhere you didn&#39;t check? What if another component imports it dynamically?</p><p>So the keys stay. And your translators translate all of them. At $0.08/word across 6 languages, those 340 ghost keys cost us roughly $1,100 in unnecessary translation work over 6 months. That’s before you count the translator time wasted on context questions about strings that don’t correspond to any visible UI.</p><h3>Why regex-based detection fails</h3><p>The obvious fix is to scan the codebase for key references. Most teams write a script:</p><pre># Find keys in JSON that aren&#39;t referenced in source<br>grep -r &quot;onboarding.wizard&quot; src/ --include=&quot;*.tsx&quot;</pre><p>This misses:</p><ul><li>Namespaced keys: t(&#39;step1.title&#39;) inside a component that called useTranslations(&#39;onboarding.wizard&#39;) — the full key is onboarding.wizard.step1.title, but the source code only has step1.title.</li><li>Dynamic keys: t(\error.${code}`)` — you can&#39;t statically resolve the full key.</li><li>Passed references: &lt;Child t={t} /&gt; — the key usage is in the child, but the namespace binding is in the parent.</li></ul><h3>What actually works: AST scanning</h3><p>Parse the actual syntax tree, not the text:</p><pre>$ npx @better-i18n/cli scan<br>Scanning src/ for translation keys...<br>Found 2,412 keys in project<br>  ├── 2,072 matched (used in code)<br>  ├── 340 unused (safe to remove)<br>  └── 18 dynamic (manual review needed)<br>Dynamic keys (cannot statically resolve):<br>  src/components/ErrorBanner.tsx:14  →  t(`error.${code}`)<br>  src/lib/notifications.ts:28       →  t(`notification.${type}.title`)<br>  ...</pre><p>The AST parser:</p><ol><li>Finds all useTranslations(&#39;namespace&#39;) calls and tracks the bound variable</li><li>Follows the variable through the component scope</li><li>When it sees t(&#39;key&#39;), resolves the full qualified key: namespace.key</li><li>Cross-references against the platform’s key inventory</li><li>Flags dynamic keys (template literals, computed values) for manual review</li></ol><p>This runs in CI. Every PR gets a check: “This PR removes 3 key references. The following keys will become unused: [list].” No ghost keys accumulate.</p><h3>Problem 4: The 47-minute typo fix</h3><p>Your German translator finds that “Weiter” (next) should be “Fortfahren” (continue) on the checkout page. One word.</p><p>With file-based i18n, pushing that fix requires:</p><ol><li>Open translation file or TMS</li><li>Edit the string</li><li>If TMS: wait for sync → PR bot → merge → build → deploy</li><li>If file-based: edit JSON → commit → push → build → deploy</li></ol><p>Either way, a one-word change triggers a full deployment pipeline. CI runs, tests execute, containers build, CDN cache purges. Minimum 5 minutes. Average 15–45 minutes depending on your pipeline.</p><p>Now multiply this by 3–5 translation fixes per week. Your deployment pipeline is spending 15–25% of its runs on copy changes that don’t touch a single line of application code.</p><h3>What actually works: CDN-decoupled translations</h3><pre>Translation fix flow:<br>  1. Edit string in dashboard<br>  2. Click &quot;Publish&quot;<br>  3. CDN cache invalidates globally (~2 seconds)<br>  4. Next user request serves the corrected translation<br>Time: under 30 seconds. No build. No deploy. No PR.</pre><p>For the architecture-curious:</p><pre>Browser → Next.js Server Component<br>  → getMessages({ project, locale })<br>    → CDN Edge (cache HIT: ~2ms / MISS: ~40ms)<br>      → Platform API → Database</pre><p>The response is a flat JSON object, edge-cached with stale-while-revalidate. Even on cache miss, the server doesn&#39;t block — it serves stale content and revalidates in the background.</p><p>For SSR/RSC, messages are fetched once in the layout and serialized into the RSC payload. No additional CDN request from the client. Hydration uses the pre-fetched messages.</p><pre>// Server: one CDN fetch per request<br>const messages = await getMessages({ project: &#39;app&#39;, locale });<br>// Client: zero CDN fetches, messages arrive via RSC payload<br>&lt;IntlProvider locale={locale} messages={messages}&gt;<br>  {children}<br>&lt;/IntlProvider&gt;</pre><h3>Problem 5: The context black hole</h3><p>Translators see a key and a source string:</p><pre>Key: checkout.summary.total_label<br>Value: &quot;Total&quot;</pre><p>They don’t see the UI. “Total” in English is unambiguous. In German, it’s three different words depending on context:</p><ul><li>Table column header → “Gesamt”</li><li>Button text → “Gesamtbetrag”</li><li>Invoice line item → “Summe”</li></ul><p>Your translator picks one. It’s wrong. You get a bug report from a German user. A developer screenshots the UI, explains the context in Slack, the translator fixes it, and the fix goes through the deployment pipeline.</p><p>This cycle repeats 5–10 times per sprint. Each cycle involves a developer context-switch (15 min), a Slack thread (30 min round-trip), and a deployment (15–45 min). That’s 1–2 hours per mistranslation.</p><h3>What reduces this</h3><ol><li><strong>AI translation with glossary enforcement</strong>. Define domain-specific terms once:</li></ol><pre>| Term (EN)    | Term (DE)       | Context                    |<br>|--------------|-----------------|----------------------------|<br>| Total        | Gesamt          | Summary labels, headers    |<br>| Workspace    | Arbeitsbereich  | Not &quot;Arbeitsplatz&quot;         |<br>| Dashboard    | Dashboard       | Keep English (UX standard) |<br>| Provider     | Anbieter        | Service provider context   |</pre><p>When AI translates a new key, it checks the glossary first. “Total” always becomes “Gesamt” in summary contexts. Consistency that’s mechanically impossible when human translators work independently across 800+ keys.</p><ol><li><strong>Screenshot context on keys</strong>. Attach a visual reference to each key so translators see the component, not just the string.</li><li><strong>Review workflow with diff</strong>. Translators see what changed, not the entire file. When a developer changes “Total” to “Subtotal”, the translator sees the before/after in context.</li></ol><h3>Problem 6: The type safety gap</h3><p>This one is specific to TypeScript projects. Your translation keys are strings. Your IDE doesn’t know which keys exist. You type t(&#39;header.buttn_text&#39;) with a typo, and you find out when a user reports a blank button.</p><pre>// No error at compile time. No error at build time. Error at runtime.<br>const title = t(&#39;dashbord.title&#39;); // typo: should be &#39;dashboard.title&#39;</pre><p>i18next has @types/i18next which can provide type checking if you configure it correctly. FormatJS has similar support. But both require you to generate type definitions from your JSON files and keep them in sync. That&#39;s another CI step, another file to maintain, another thing that can go stale.</p><h3>What actually works</h3><p>Generate types from the source of truth (the platform), not from local files:</p><pre>$ npx @better-i18n/cli generate-types<br>Generated src/i18n.d.ts with 2,072 typed keys</pre><pre>// IDE autocomplete for every key. Red squiggly on typos.<br>const t = useTranslations(&#39;dashboard&#39;);<br>t(&#39;title&#39;);        // ✅ autocomplete<br>t(&#39;titl&#39;);         // ❌ TypeScript error: &#39;titl&#39; not in DashboardKeys<br>t(&#39;stats.users&#39;);  // ✅ autocomplete with nested keys</pre><p>The type file is generated from the platform’s key inventory, which is the same data the CDN serves. One source of truth, zero drift.</p><h3>The real scaling checklist</h3><p>Framework comparisons evaluate the 10% of i18n work that involves writing t() calls. Here&#39;s what you should actually evaluate when your project passes 500 keys:</p><p>| Question | File-based answer | CDN-first answer |</p><p>| — — — — — | — — — — — — — — — -| — — — — — — — — — |</p><p>| How do you detect unused keys? | Manual audit or regex script | AST scanner in CI |</p><p>| How do you fix a translation typo? | Full deploy (15–45 min) | CDN publish (30 sec) |</p><p>| How do you avoid merge conflicts? | Namespace splitting (reduces, doesn’t eliminate) | No locale files in repo |</p><p>| How do translators get context? | Screenshot in Slack | Attached to key, AI-assisted |</p><p>| How do you ensure key type safety? | Generated types from local JSON (drift risk) | Generated types from platform (single source) |</p><p>| How long is your translation pipeline? | Dev → TMS → PR → Merge → Build → Deploy | Dev → Platform → CDN |</p><p>| What’s your cost per language added? | Linear: new files, new conflicts, new translations | Sublinear: glossary-enforced AI + human review |</p><h3>The migration is not the hard part</h3><p>If you’re currently running i18next or FormatJS with file-based translations, the migration to a CDN-first model is straightforward:</p><ol><li><strong>Export</strong> your current JSON files (you already have them)</li><li><strong>Import</strong> into a translation platform via CLI</li><li><strong>Replace</strong> i18next.init({ backend: { loadPath } }) with getMessages({ project, locale })</li><li><strong>Remove</strong> the locales/ directory from your repo</li><li><strong>Run</strong> the AST scanner to verify key coverage</li></ol><p>Steps 1–4 took our team about 4 hours. Step 5 found 340 unused keys in 30 seconds.</p><p>The framework you use for t() calls barely changes. The infrastructure around it changes completely.</p><h3>What I’d recommend today</h3><ol><li><strong>Pick any modern i18n library.</strong> i18next, FormatJS, or next-intl — they all handle the t() function well. This is the least important decision you&#39;ll make.</li><li><strong>Don’t split into namespace files.</strong> Use logical key prefixes (billing.errors.cardDeclined) without file boundaries. Let the CDN serve everything in one cached response.</li><li><strong>Set up AST scanning from day one.</strong> The longer you wait, the more ghost keys accumulate. Run it in CI so unused keys are caught in the PR that removes them.</li><li><strong>Decouple translations from deployments immediately.</strong> A translation fix should never trigger a build. This alone will save your team hours per week.</li><li><strong>Build a glossary before you translate.</strong> 40 domain-specific terms in a glossary produces more consistent translations than a 10-page style guide nobody reads.</li><li><strong>Measure developer time on i18n.</strong> Track it for one sprint. Count the merge conflicts, the Slack threads with translators, the namespace debates, the deployment time on copy-only changes. The number will be higher than you expect.</li></ol><p><em>Our team uses </em><a href="https://better-i18n.com/"><em>Better i18n</em></a><em> for CDN-delivered translations, AST key scanning, and AI translation with glossary enforcement. If you’re evaluating your i18n infrastructure, the free tier is enough to test whether the CDN-first model works for your workflow.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6e4defaa3fc3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why We Ditched Crowdin After 6 Months and Built a Git-Native i18n Pipeline]]></title>
            <link>https://gundogmuseray.medium.com/why-we-ditched-crowdin-after-6-months-and-built-a-git-native-i18n-pipeline-e4256d2bfe63?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/e4256d2bfe63</guid>
            <category><![CDATA[language-translation]]></category>
            <category><![CDATA[i18n]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[localization]]></category>
            <category><![CDATA[language]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Sun, 01 Mar 2026 14:14:34 GMT</pubDate>
            <atom:updated>2026-03-01T15:24:52.901Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How our team at </em><a href="http://carna.ai/"><em>Carna</em></a><em> went from 3-week translation cycles to same-day multilingual releases</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-85u3evwsCy0usG5jWXVXA.png" /></figure><p>We’re a small team building <a href="http://carna.ai/">Carna</a>, a edu-tech platform. When we started expanding to European markets last year, we needed to localize the app into German, French, and Turkish. Simple enough, right?</p><p>We picked Crowdin. It’s the industry standard, it has GitHub integration, it handles pluralization. Every “best TMS” listicle recommends it. So we set it up, connected our repo, invited our translators, and got to work.</p><p>Six months later, we ripped it all out.</p><p>This isn’t a hit piece on Crowdin. It’s a solid product, and it works well for certain team structures. But for a developer-heavy startup shipping weekly, the friction points compounded until the translation workflow became our single biggest bottleneck.</p><p>Here’s what happened, what we tried, and what we ended up building instead.</p><h3>The setup that looked great on paper</h3><p>Our stack: Next.js 15 (App Router), TypeScript, Tailwind, deployed on Vercel. We had about 400 translation keys across 30 pages when we started.</p><p>The initial Crowdin integration looked clean:</p><ol><li>Developers write code with t() function calls</li><li>JSON source files (en.json) live in locales/en/ in the repo</li><li>Crowdin’s GitHub integration picks up changes automatically</li><li>Translators work in Crowdin’s web editor</li><li>Crowdin creates PRs back to the repo with translated files</li></ol><p>On a whiteboard, this is a perfect loop. In practice, here’s what actually happened sprint after sprint.</p><h3>Problem 1: The JSON merge conflict nightmare</h3><p>Our locales/en/common.json file grew to 847 keys by month 4. Every feature branch that touched translations modified this file. When two developers added keys in the same sprint (which was every sprint), we got merge conflicts.</p><p>Not small conflicts either. Git’s merge strategy for JSON is terrible. A single reordered key produces a 200-line diff. And because Crowdin also writes to these files via its PR bot, we’d sometimes have three-way conflicts between two feature branches and Crowdin’s translation PR.</p><p>We tried splitting into namespace files (auth.json, dashboard.json, settings.json). That helped with conflicts but created a different problem: developers now had to decide which namespace a key belonged to before writing it. &quot;Does the error message on the payment page go in payments.json or errors.json?&quot; These decisions took longer than writing the actual component.</p><p><strong>Time lost per sprint: ~3 hours on merge conflicts and namespace decisions.</strong></p><h3>Problem 2: The stale key graveyard</h3><p>By month 3, we had 127 translation keys that weren’t used anywhere in the codebase. We knew this because a new developer joined and asked “what does legacy.onboarding.step3.subtitle do?&quot; and nobody could find it in the code.</p><p>The keys had accumulated over two refactors. When we renamed components and restructured pages, the old keys stayed in the JSON files because nobody wanted to risk deleting a key that might be used somewhere they hadn’t checked.</p><p>Our translators were translating all 127 of these ghost keys into every new language we added. At our translator’s rate, that was roughly $380 worth of translation work on strings that would never be seen by any user.</p><p>Crowdin has no built-in way to detect unused keys. You can mark keys as “hidden” manually, but that requires someone to audit every key against the codebase. With 847 keys across 4 namespaces, nobody volunteered for that job.</p><h3>Problem 3: The deployment coupling</h3><p>This one hurt the most.</p><p>Our German launch was on a Tuesday. On Wednesday morning, a German-speaking user reported that the checkout button said “Fortsetzen” (continue) instead of “Kaufen” (buy). A one-word fix.</p><p>To push that fix, we had to:</p><ol><li>Open Crowdin, find the key, edit the German translation</li><li>Wait for Crowdin’s sync (runs every 15 minutes)</li><li>Wait for Crowdin’s PR bot to create a PR</li><li>Merge the PR</li><li>Wait for Vercel to build and deploy</li></ol><p>Total time from identifying the typo to the fix being live: <strong>47 minutes</strong>. For one word.</p><p>This happened again and again. Translation fixes were coupled to our deployment pipeline. Every typo fix, every copy improvement, every “the client wants to change this heading” required a full build-deploy cycle.</p><p>We started keeping a spreadsheet of “translation fixes waiting for next deploy.” That spreadsheet had 12 items in it by the end of month 5.</p><h3>Problem 4: The context gap</h3><p>Translators working in Crowdin see a key name and a source string. They don’t see the UI.</p><p>When a translator sees:</p><pre>Key: checkout.summary.total<br>Value: &quot;Total&quot;</pre><p>They don’t know if “Total” is a table header, a line item label, a button, or a section heading. In German, these have different translations:</p><ul><li>Table header: “Gesamt”</li><li>Button text: “Summe” or “Gesamtbetrag”</li><li>Section heading: “Zusammenfassung”</li></ul><p>Crowdin has an “in-context” editor that overlays translations on your actual UI. We tried it. It required injecting a JavaScript snippet into our production build, which our security review flagged. We could only run it in staging, but staging was often broken because it was our integration environment. So the in-context editor worked in theory but never in practice.</p><p>Our translators ended up sending us Slack messages like “what is this string for?” an average of 6 times per sprint. Each message required a developer to stop what they were doing, find the component, take a screenshot, explain the context, and hope the translator didn’t have follow-up questions.</p><h3>What we tried before switching</h3><p>Before abandoning Crowdin, we tried to fix the workflow:</p><p><strong>Attempt 1: i18n linting</strong></p><p>We wrote a custom ESLint rule that checked if every t() call had a corresponding key in en.json. This caught missing keys at dev time but didn&#39;t help with unused keys or merge conflicts.</p><p><strong>Attempt 2: Namespace conventions</strong></p><p>We documented a namespace convention: {page}.{section}.{element}. Developers followed it for two weeks, then stopped because it was too verbose and the naming meetings took longer than the coding.</p><p><strong>Attempt 3: Translation freezes</strong></p><p>We tried freezing translations two days before release. This meant developers couldn’t add new translatable strings within 48 hours of shipping. On a weekly release cycle, that meant a 28% reduction in our available development time.</p><p>None of these fixed the fundamental issue: <strong>our translation workflow was built around a file-synchronization model, but our team operated on a continuous delivery model.</strong></p><h3>The switch</h3><p>We moved to <a href="https://better-i18n.com/">Better i18n</a>. The migration took a weekend.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*lNJkoH8Ks0BAbDB8PTg4tw.png" /></figure><p>Here’s what the new pipeline looks like:</p><h3>No more JSON files in the repo</h3><p>Translations are fetched from a CDN at request time:</p><pre>// app/[locale]/layout.tsx<br>import { getMessages } from &#39;@better-i18n/use-intl/server&#39;;<br>export default async function LocaleLayout({ children, params: { locale } }) {<br>  const messages = await getMessages({<br>    project: &#39;carna/web&#39;,<br>    locale,<br>  });<br>  return (<br>    &lt;BetterI18nProvider locale={locale} messages={messages}&gt;<br>      {children}<br>    &lt;/BetterI18nProvider&gt;<br>  );<br>}</pre><p>No locales/ directory. No JSON files. No merge conflicts. The CDN response is edge-cached, so latency is sub-10ms from any region.</p><h3>Automatic key discovery via AST scanning</h3><p>The CLI scans the codebase using AST parsing (not regex):</p><pre>$ npx @better-i18n/cli scan<br>Scanning src/ for translation keys...<br>Found 892 keys in 147 files<br>  ├── 847 existing keys (matched)<br>  ├── 45 new keys (need translation)<br>  └── 127 unused keys (not in codebase)<br>Unused keys:<br>  legacy.onboarding.step3.subtitle<br>  legacy.onboarding.step3.description<br>  legacy.onboarding.step4.title<br>  ... (124 more)</pre><p>Those 127 ghost keys? Found in 30 seconds. The scanner parses the actual AST of every .tsx file, finds t(), useTranslations(), and getTranslations() calls, extracts the key arguments, and cross-references them against the platform&#39;s key inventory.</p><p>This is fundamentally different from regex-based key extraction. AST parsing handles:</p><pre>// Dynamic namespace - AST understands this<br>const t = useTranslations(&#39;checkout&#39;);<br>t(&#39;summary.total&#39;); // Resolves to &quot;checkout.summary.total&quot;<br>// Computed keys - AST flags these for manual review<br>t(`error.${code}`); // Flagged: dynamic key, cannot statically analyze<br>// Nested component namespaces - AST traces the scope<br>function CheckoutPage() {<br>  const t = useTranslations(&#39;checkout&#39;);<br>  return &lt;Summary t={t} /&gt;; // AST tracks that Summary uses checkout namespace<br>}</pre><h3>CDN-delivered translations = instant fixes</h3><p>Remember the 47-minute “Kaufen” fix? Here’s the same scenario now:</p><ol><li>Open Better i18n dashboard, find the key, edit the German translation</li><li>Hit “Publish”</li><li>CDN cache invalidates globally in &lt;2 seconds</li></ol><p>Total time: <strong>under 30 seconds</strong>. No build. No deploy. No PR. The next user request serves the corrected translation from the edge.</p><p>For staging/preview environments, we use a draft mode that pulls unpublished translations so QA can verify copy changes before they go live.</p><h3>AI translation with glossary enforcement</h3><p>We built a glossary with 43 terms specific to <a href="http://carna.ai/"><strong>Carna’s</strong></a> health-tech domain:</p><pre>| Term (EN)       | Term (DE)         | Context                    |<br>|-----------------|-------------------|----------------------------|<br>| Assessment      | Bewertung         | Health risk assessment      |<br>| Vitals          | Vitalwerte        | Not &quot;Lebenswichtig&quot;        |<br>| Provider        | Anbieter          | Healthcare provider         |<br>| Dashboard       | Dashboard         | Keep English (UX standard)  |<br>| Risk Score      | Risikowert        | Single compound word        |</pre><p>When AI translates a new key, it checks the glossary first. “Risk Score” always becomes “Risikowert”, never “Risikopunktzahl” or “Risikobewertung”. The consistency across 900+ keys is something we never achieved with human translators working in Crowdin, because each translator had their own preference.</p><h3>Git sync as output, not input</h3><p>Translations still land in our GitHub repo as PRs. But now the flow is reversed:</p><pre>Before (Crowdin):  Git → Crowdin → Git (circular, conflict-prone)<br>After:             Platform → CDN (live) + Platform → Git PR (archive)</pre><p>The Git PR is a record, not a blocker. We merge it when convenient. If we never merge it, the translations still work because they’re served from the CDN. This completely eliminated the merge conflict problem because the JSON files in the repo are output artifacts, not source-of-truth inputs.</p><h3>The migration: what it actually took</h3><p><strong>Friday evening (2 hours):</strong></p><ol><li>Exported all translations from Crowdin as JSON (5 minutes)</li><li>Imported into Better i18n via CLI bulk upload (10 minutes)</li><li>Ran the CLI scanner against our codebase to verify key inventory (5 minutes)</li><li>Fixed 3 key mismatches between Crowdin’s namespace format and ours (30 minutes)</li><li>Updated next.config.js and middleware to use the new provider (45 minutes)</li><li>Verified dev server worked with CDN-delivered translations (15 minutes)</li></ol><p><strong>Saturday morning (3 hours):</strong></p><ol><li>Updated 6 server components from getTranslations() pattern to new import (1 hour)</li><li>Added locale middleware configuration (30 minutes)</li><li>Set up hreflang and canonical URL helpers in the layout (30 minutes)</li><li>Ran full test suite (30 minutes, 2 failures — both were hardcoded locale assumptions in tests)</li><li>Fixed tests, ran again, all green (30 minutes)</li></ol><p><strong>Saturday afternoon (1 hour):</strong></p><ol><li>Deployed to staging, tested all 4 languages manually (45 minutes)</li><li>Deployed to production (15 minutes)</li></ol><p><strong>Total migration time: ~6 hours across a weekend.</strong></p><p>The Crowdin subscription ran in parallel for 2 weeks as a safety net. We didn’t need to roll back.</p><h3>Quantified results after 3 months</h3><p>| Metric | With Crowdin | With Better i18n |</p><p>| — — — — | — — — — — — -| — — — — — — — — -|</p><p>| Translation fix to production | 47 min avg | ❤0 sec |</p><p>| Merge conflicts per sprint | 2–3 | 0 |</p><p>| Unused keys in codebase | 127 (growing) | 0 (scanner runs in CI) |</p><p>| Translator context questions per sprint | ~6 Slack threads | ~1 |</p><p>| Time developers spent on i18n per sprint | ~5 hours | ~45 min |</p><p>| Monthly cost | $149/mo (Crowdin Team) | $19/mo (Better i18n Pro) |</p><p>The developer time savings alone justified the switch. 5 hours per sprint across 3 developers is 15 engineer-hours per sprint spent on JSON file management. That’s now 2.25 hours spent reviewing AI-generated translations and occasionally adding glossary terms.</p><h3>Technical deep-dive: the CDN architecture</h3><p>For the engineers who want to understand what “CDN-delivered translations” means architecturally:</p><pre>Request flow:<br>  Browser → Next.js Server Component<br>    → getMessages({ project: &#39;carna/web&#39;, locale: &#39;de&#39; })<br>      → HTTP GET https://cdn.better-i18n.com/v1/carna/web/de<br>        → Cloudflare Edge (cache HIT: ~2ms, MISS: ~40ms)<br>          → Origin: Better i18n API → PostgreSQL</pre><p>The response is a flat JSON object:</p><pre>{<br>  &quot;checkout.summary.total&quot;: &quot;Gesamt&quot;,<br>  &quot;checkout.summary.tax&quot;: &quot;MwSt.&quot;,<br>  &quot;checkout.button.buy&quot;: &quot;Kaufen&quot;,<br>  ...<br>}</pre><p>Cache invalidation happens on publish via Cloudflare’s purge API. We tested invalidation latency across 15 PoPs: median 1.2 seconds, p99 3.8 seconds.</p><p>For server-side rendering, getMessages() adds a stale-while-revalidate header, so even if the CDN cache expires, the server doesn&#39;t block rendering. It serves the stale translation and revalidates in the background.</p><p>For client-side hydration, the messages are serialized into the HTML payload once (in the layout), so there’s no additional CDN request from the browser. The BetterI18nProvider receives pre-fetched messages as a prop.</p><pre>// This runs once on the server, messages are passed to client via RSC payload<br>const messages = await getMessages({ project: &#39;carna/web&#39;, locale });<br>// Client sees pre-loaded messages, zero additional network requests<br>&lt;BetterI18nProvider locale={locale} messages={messages}&gt;</pre><h3>What we’d still use Crowdin for</h3><p>To be fair: if we were a 50-person company with a dedicated localization team, a translation memory database spanning 10 years, and content that changes monthly rather than daily, Crowdin’s model makes more sense. Its translation memory, glossary management, and multi-step approval workflows are built for that scale.</p><p>Our use case was different: a small engineering team shipping daily, where the “localization team” was one freelance translator per language and three developers who sometimes fixed translations themselves. For that profile, the file-sync model was overhead, not infrastructure.</p><h3>Takeaways</h3><ol><li><strong>Your i18n tool choice should match your release cadence.</strong> If you ship weekly or daily, file-sync tools create friction. If you ship quarterly, they’re fine.</li><li><strong>Unused key detection is not optional.</strong> Without it, your translation costs grow linearly with every refactor. Automate it in CI.</li><li><strong>Decouple translations from deployments.</strong> A translation fix should never require a build. CDN-delivered translations make this possible.</li><li><strong>Glossaries beat style guides.</strong> You can write a 10-page translation style guide, but a machine-enforced glossary with 40 terms is more effective than a document nobody reads.</li><li><strong>Measure the developer time cost.</strong> We tracked it for one sprint before switching and were shocked by the 5 hours/sprint number. Most teams don’t measure this because “i18n overhead” is spread across dozens of small interruptions that never show up on a Jira board.</li></ol><p><em>We’re using </em><a href="https://better-i18n.com/"><em>Better i18n</em></a><em> for Carna’s web and mobile apps. If you’re hitting similar friction with your current TMS, their free tier is enough to test whether the CDN-first model works for your workflow</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e4256d2bfe63" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why We Built a GitHub-First Localization Platform (and How You Can Use It)]]></title>
            <link>https://gundogmuseray.medium.com/why-we-built-a-github-first-localization-platform-and-how-you-can-use-it-51bf9c2dd12f?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/51bf9c2dd12f</guid>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[internationalization]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[nextjs]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Sun, 01 Mar 2026 13:01:32 GMT</pubDate>
            <atom:updated>2026-03-01T13:53:59.642Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A deep dive into modern i18n workflows — from JSON file chaos to AI-powered, CDN-delivered translations with PR-native collaboration.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-85u3evwsCy0usG5jWXVXA.png" /></figure><p>If you’ve ever worked on a multilingual app, you know the pain. Translation files scattered across your repo. Developers manually copy-pasting keys. A product manager emailing an Excel spreadsheet with “updated translations.” Deployments blocked because someone forgot to add the Turkish version of a button label.</p><p>We lived this pain for years. And when we looked at the existing tools — Crowdin, Lokalise, Phrase — they all shared the same fundamental problem: <strong>they treat translations as a separate workflow from code.</strong></p><p>So we built <a href="https://better-i18n.com/">Better i18n</a>, an open-source localization platform where translations are managed through the same GitHub workflow you already use for code. No context switching. No spreadsheets. No “sync” buttons.</p><p>Here’s what we learned, and how you can set it up in your project today.</p><h3>The Problem with Traditional Translation Management</h3><p>Most localization platforms follow the same pattern:</p><ol><li>Export your translation keys to their dashboard</li><li>Translators work in a separate UI</li><li>Export translations back as JSON/YAML files</li><li>Commit the files to your repo</li><li>Hope nothing broke</li></ol><p>This creates several problems:</p><ul><li><strong>Translations drift from code.</strong> Keys get renamed in code but not in the translation platform. Deleted features leave orphaned translations.</li><li><strong>No review process.</strong> Code changes go through pull requests with CI checks. Translation changes? Dropped into a folder and merged.</li><li><strong>Deployment coupling.</strong> Want to fix a typo in a translation? You need a full build and deploy cycle.</li><li><strong>Context loss.</strong> Translators see isolated strings without knowing where they appear in the UI or what variables mean.</li></ul><h3>A Different Approach: GitHub-First Localization</h3><p>What if translations followed the exact same workflow as code?</p><p>That’s the core idea behind Better i18n. When a translator updates a string in the <a href="https://better-i18n.com/">dashboard</a>, the platform doesn’t just save it to a database — it creates a pull request in your GitHub repo. Your team reviews the translation change the same way they review code changes. CI runs. Checks pass. The PR gets merged.</p><pre>Translator updates string in dashboard<br>        ↓<br>Better i18n creates a PR in your repo<br>        ↓<br>Team reviews the PR (diff shows exactly what changed)<br>        ↓<br>CI checks pass (type checking, key validation)<br>        ↓<br>PR merged → CDN cache invalidated → users see the update</pre><p>The reverse also works. When a developer adds new translation keys in code and pushes to GitHub, Better i18n detects the new keys and makes them available for translation in the dashboard.</p><p>This bidirectional sync means <strong>your GitHub repo is always the source of truth</strong>, not some external database.</p><h3>CDN Delivery: Translations Without Redeployment</h3><p>Here’s something that surprised us: most apps bundle translations into the build artifact. This means fixing a single typo in a translation requires rebuilding and redeploying the entire application.</p><p>Better i18n takes a different approach. Translations are served from <a href="https://www.cloudflare.com/network/">Cloudflare’s edge network</a> — the same CDN infrastructure that powers millions of websites. When a translation is updated:</p><ol><li>The new value is pushed to the CDN</li><li>Cache is invalidated at the edge</li><li>The next request gets the updated translation</li></ol><p>No rebuild. No redeploy. No downtime.</p><p>For applications where translation updates are frequent — think e-commerce product descriptions, marketing copy, or compliance-sensitive content — this eliminates an entire deployment cycle per change.</p><h3>Setting It Up: Next.js Example</h3><p>Let’s walk through a real setup. I’ll show you how to add Better i18n to a <a href="https://nextjs.org/">Next.js</a> app with the <a href="https://nextjs.org/docs/app">App Router</a>.</p><h3>1. Install the SDK</h3><pre>npm install @better-i18n/next @better-i18n/cli</pre><p>The <a href="https://www.npmjs.com/package/@better-i18n/next">@better-i18n/next</a> package provides middleware, hooks, and server component utilities. The <a href="https://www.npmjs.com/package/@better-i18n/cli">@better-i18n/cli</a> handles scanning your codebase for translation keys and syncing with the platform.</p><h3>2. Configure the Middleware</h3><pre>// middleware.ts<br>import { createI18nMiddleware } from &#39;@better-i18n/next&#39;;<br>export default createI18nMiddleware({<br>  locales: [&#39;en&#39;, &#39;tr&#39;, &#39;de&#39;, &#39;ja&#39;],<br>  defaultLocale: &#39;en&#39;,<br>});<br>export const config = {<br>  matcher: [&#39;/((?!api|_next|.*\\..*).*)&#39;],<br>};</pre><p>This middleware handles locale detection from the Accept-Language header, URL prefix routing (/tr/about, /de/pricing), and cookie-based locale persistence.</p><h3>3. Use Translations in Components</h3><pre>import { useTranslations } from &#39;@better-i18n/next&#39;;<br>export default function PricingPage() {<br>  const t = useTranslations(&#39;pricing&#39;);<br>  return (<br>    &lt;section&gt;<br>      &lt;h1&gt;{t(&#39;title&#39;)}&lt;/h1&gt;<br>      &lt;p&gt;{t(&#39;subtitle&#39;)}&lt;/p&gt;<br>      &lt;div&gt;<br>        {plans.map(plan =&gt; (<br>          &lt;div key={plan.id}&gt;<br>            &lt;h3&gt;{t(`plans.${plan.id}.name`)}&lt;/h3&gt;<br>            &lt;p&gt;{t(&#39;price&#39;, { amount: plan.price })}&lt;/p&gt;<br>          &lt;/div&gt;<br>        ))}<br>      &lt;/div&gt;<br>    &lt;/section&gt;<br>  );<br>}</pre><h3>4. Scan and Sync</h3><pre># Scan your codebase for all translation keys<br>npx @better-i18n/cli scan<br># Sync with the Better i18n platform<br>npx @better-i18n/cli sync</pre><p>The CLI scanner uses AST parsing to find every t() call in your codebase. It detects:</p><ul><li>New keys that need translation</li><li>Unused keys that can be cleaned up</li><li>Keys with missing translations in specific locales</li><li>ICU MessageFormat syntax errors</li></ul><p>This is something most translation platforms can’t do — they don’t understand your code, so they can’t tell you which translations are actually being used.</p><h3>AI Translation That Actually Works</h3><p>Let’s be honest: machine translation has been “good enough” for a while. Google Translate, DeepL — they all produce readable output. But for product UI, “readable” isn’t enough. You need translations that:</p><ul><li>Match your brand voice</li><li>Handle technical terminology consistently</li><li>Respect the context of where the string appears</li><li>Get pluralization and formatting right</li></ul><p>Better i18n uses <a href="https://deepmind.google/technologies/gemini/">Google Gemini</a> for translation, but with a crucial addition: <strong>context</strong>. When translating a string, the AI sees:</p><ul><li>The full namespace (what section of the app this belongs to)</li><li>The glossary (how your team translates specific terms)</li><li>The ICU MessageFormat structure (so pluralization is handled correctly)</li><li>Other translations in the same namespace (for consistency)</li></ul><p>The result is translation that sounds like a human wrote it, because the AI has the same context a human translator would have.</p><h3>MCP: Letting AI Agents Handle Translations</h3><p>This is where things get interesting. We built a <a href="https://modelcontextprotocol.io/">Model Context Protocol (MCP)</a> server that lets AI assistants like <a href="https://claude.ai/">Claude</a> or <a href="https://cursor.com/">Cursor</a> manage translations directly.</p><pre>npm install @better-i18n/mcp</pre><p>With the MCP server connected, you can ask your AI assistant:</p><ul><li><em>“Add a new translation key </em><em>auth.password_reset.title in all locales&quot;</em></li><li><em>“Find all unused translation keys in the </em><em>dashboard namespace&quot;</em></li><li><em>“Translate the new marketing copy into Turkish and German”</em></li></ul><p>The AI assistant calls the Better i18n API through MCP, and the changes flow through the same GitHub PR workflow. No manual dashboard interaction needed.</p><p>This is particularly powerful for developer workflows. Instead of switching between your IDE and a translation dashboard, you stay in your editor and let the AI handle the translation management.</p><h3>React Native / Expo Support</h3><p>Mobile apps have unique i18n challenges: offline support, OTA updates, and platform-specific formatting. The <a href="https://www.npmjs.com/package/@better-i18n/expo">@better-i18n/expo</a> package handles all of this:</p><pre>import { BetterI18nExpoProvider, useTranslations } from &#39;@better-i18n/expo&#39;;<br>export default function App() {<br>  return (<br>    &lt;BetterI18nExpoProvider<br>      projectId=&quot;your-project-id&quot;<br>      defaultLocale=&quot;en&quot;<br>      fallbackMessages={require(&#39;./messages/en.json&#39;)}<br>    &gt;<br>      &lt;Navigation /&gt;<br>    &lt;/BetterI18nExpoProvider&gt;<br>  );<br>}</pre><p>Key features for mobile:</p><ul><li><strong>Offline caching</strong> — translations are cached locally and work without network</li><li><strong>OTA updates</strong> — new translations are fetched in the background, no app store update needed</li><li><strong>Automatic locale detection</strong> — reads the device language settings</li><li><strong>Bundle fallback</strong> — ships with bundled translations so the app works immediately on first launch</li></ul><h3>Open Source</h3><p>The SDKs, CLI, and MCP server are all <a href="https://github.com/better-i18n/oss">open source on GitHub</a> under the MIT license. You can inspect the code, contribute, or fork it for your own needs.</p><p>We also published <a href="https://github.com/better-i18n/skills">AI agent skills</a> — structured knowledge files that teach AI assistants i18n best practices. Install them in your Claude Code or Cursor project, and your AI assistant will automatically follow best practices when helping with internationalization.</p><h3>Getting Started</h3><p>If you want to try Better i18n:</p><ol><li><strong>Sign up</strong> at <a href="https://better-i18n.com/">better-i18n.com</a> (free tier available)</li><li><strong>Install the CLI</strong>: npm install -g @better-i18n/cli</li><li><strong>Initialize</strong>: npx @better-i18n/cli init</li><li><strong>Read the docs</strong>: <a href="https://docs.better-i18n.com/">docs.better-i18n.com</a></li></ol><p>The SDKs are available on npm:</p><ul><li><a href="https://www.npmjs.com/package/@better-i18n/next">@better-i18n/next</a> — Next.js integration</li><li><a href="https://www.npmjs.com/package/@better-i18n/use-intl">@better-i18n/use-intl</a> — React with <a href="https://www.npmjs.com/package/use-intl">use-intl</a></li><li><a href="https://www.npmjs.com/package/@better-i18n/expo">@better-i18n/expo</a> — Expo / React Native</li><li><a href="https://www.npmjs.com/package/@better-i18n/mcp">@better-i18n/mcp</a> — MCP server for AI agents</li><li><a href="https://www.npmjs.com/package/@better-i18n/cli">@better-i18n/cli</a> — CLI tools</li></ul><p>Source code: <a href="https://github.com/better-i18n/oss">github.com/better-i18n/oss</a></p><p><em>We’re building Better i18n in the open. If you have feedback, feature requests, or just want to say hi — find us on </em><a href="https://github.com/better-i18n"><em>GitHub</em></a><em> or reach out at </em><a href="/service/mailto:hello@better-i18n.com"><em>e</em></a>ray@carna.ai<em>.</em></p><p><strong>Tags:</strong> #javascript #nextjs #react #internationalization #typescript #localization #i18n #webdev #opensource #ai</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=51bf9c2dd12f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Too Good for an MVP: Scaling an AI-Native LMS with JavaScript]]></title>
            <link>https://gundogmuseray.medium.com/too-good-for-an-mvp-scaling-an-ai-native-lms-with-javascript-c62dc4c0e4e2?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/c62dc4c0e4e2</guid>
            <category><![CDATA[system-design-concepts]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Thu, 25 Dec 2025 12:26:46 GMT</pubDate>
            <atom:updated>2025-12-25T12:28:21.780Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="carna" src="https://cdn-images-1.medium.com/max/200/1*u7QDc3KLkJb1WaIVo6rmDA.jpeg" /><figcaption>Carna Logo</figcaption></figure><p>JavaScript is not just for MVPs.</p><p>There’s a persistent belief that <strong>JavaScript</strong> is only good for <strong>MVPs</strong>.<br>Fast prototypes. Temporary systems. Something you rewrite “properly” later.</p><p>At <a href="http://carna.ai/"><strong>Carna</strong></a>, we ended up disproving that assumption — not intentionally, but by necessity.</p><p>Using the modern JS/TS ecosystem — <strong>Bun</strong>, <strong>Next.js</strong>, and <strong>tRPC</strong> — we built an AI-native Learning Management System that now runs at production scale. Not a demo. Not an experiment. A real platform used daily by institutions.</p><p>With <strong>~1.1M total requests</strong> served at an average of <strong>~95ms</strong>, the system is fast, predictable, and boring in the best possible way.</p><p>This is what that actually looks like under the hood.</p><h3>Education, Reimagined (Not a Chat App)</h3><p>We didn’t build “an AI chat for education.”</p><p><strong>For the Learner: The Tutor Interface</strong></p><p>That approach breaks the moment real users show up. Instead, we designed the product around pedagogy first, AI second. On the learner side, the <strong>Tutor Interface</strong> follows a clear three-phase flow:</p><p>- <strong>Learn</strong>: Interactive, structured lessons that adapt in real-time to the student&#39;s progress and CEFR level.</p><p>- <strong>Practice</strong>: A judgment-free zone for real-time speaking and pronunciation practice, powered by AI agents that provide instant phonetic feedback.</p><p>- <strong>Review:</strong> Personalized, spaced-repetition sessions that intelligently target an individual&#39;s weak points based on their historical performance.</p><p><strong>For the Institution: The Control Center</strong></p><p>- <strong>Institutional Admin Panel</strong>: A high-scale management interface.</p><p>- <strong>Deep Analytics &amp; Reports</strong>: Real-time dashboards tracking adoption, average practice time, and skill-level improvements across thousands of students.</p><p>- <strong>Common Mistakes Engine</strong>: An automated system that aggregates recurring errors across classes, allowing teachers to identify and address systemic learning gaps.</p><p>- <strong>AI-Powered Content Ops</strong>: Tools for <strong>Test Generation</strong> and <strong>Content Generation</strong> that allow educators to create high-quality, validated curriculum materials in seconds, ensuring the LMS content is always fresh and aligned with institutional goals.</p><p>On the organizational side, we built a full <strong>Admin Panel</strong> that institutions can actually operate.</p><p>Today, the system manages:</p><ul><li><strong>~11,000 questions</strong></li><li><strong>~1,500 courses</strong></li><li><strong>~373 active learning groups</strong></li><li>across <strong>~49 institutions</strong></li></ul><p>With a <strong>~76% course completion rate</strong> and <strong>~900 concurrent active users</strong>, the platform runs without drama — which is exactly the goal. And still, we keep adding our educational content.</p><p>Scale has a way of exposing bad assumptions.<br>This architecture survived it.</p><h3>The Engine: JavaScript, End to End</h3><p>Our “JS everywhere” approach wasn’t ideological. It was practical.</p><p>Shared validators, shared types, shared contracts — front to back.</p><p>Performance came from infrastructure discipline, not language tricks:</p><ul><li><strong>Runtime</strong>: Auth services built with <strong>Bun + Elysia</strong>, keeping overhead minimal</li><li><strong>Orchestration</strong>: <strong>AWS ECS Fargate</strong>, defined via Infrastructure as Code, scaling cleanly with school traffic spikes</li><li><strong>Database</strong>: <strong>Postgres 17</strong>, fronted by <strong>RDS Proxy</strong> to handle connection pressure from concurrent AI workloads</li><li><strong>Caching &amp; Rate Limiting</strong>: <strong>Valkey</strong>, keeping latency stable even under load</li></ul><p>Nothing exotic. Just careful choices and consistency.</p><h3>AI Engineering: Beyond “Prompting”</h3><p>Once you ship AI features to real users, you quickly learn that raw LLM calls are not enough.</p><p>We moved from “prompting” to <strong>pipelines</strong>.</p><p>Key decisions:</p><ul><li><strong>Progressive Generation</strong><br> Content is generated object-by-object, not in bulk.<br> Every output is validated against strict <strong>Zod schemas</strong>.<br> Failures trigger retries or fallbacks automatically — no broken UI, no silent corruption.</li><li><strong>Contextual RAG</strong><br> We use embeddings (<strong>1536 dimensions</strong>) and a dedicated vector database.<br> A <strong>~0.65 similarity threshold</strong> ensures AI output stays anchored to verified educational content.</li><li><strong>Async Offloading</strong><br> Heavy tasks — metrics, version locking, background analysis — are pushed to <strong>SQS + Lambda</strong>, keeping the request path clean and predictable.</li></ul><p>The result is AI behavior that feels deterministic, even though the models aren’t.</p><h3>Security, Observability, and Velocity</h3><p>Institutional software doesn’t get to be “good enough.”</p><p>We optimized for boring reliability:</p><ul><li><strong>JWT Isolation</strong> via published <strong>JWKS</strong>, enabling local verification across microservices</li><li><strong>Audit Engine</strong> logging every mutation asynchronously, with automatic data redaction</li><li><strong>Full Observability</strong> using <strong>Prometheus</strong> and <strong>Grafana Alloy</strong></li><li><strong>Immediate Alerts</strong> for error spikes or external API rate limits (LLMs, TTS, etc.)</li></ul><p>One unexpected velocity boost came from internationalization.</p><p>We built <a href="http://better-i18n.com/"><strong>Better-i18n</strong></a>, a GitHub-first translation workflow that lets us ship curriculum updates via pull requests — no redeploys, no downtime.</p><h3>What This Actually Proves</h3><p>Carna for Organizations isn’t proof that JavaScript is “better” than other stacks.</p><p><strong>Engineering the Future</strong></p><p>The success of Carna for Organizations proves that JavaScript is no longer just a language for MVPs — it’s a platform for engineering high-scale, AI-native institutions. By focusing on disciplined IaC and robust AI pipelines, we’ve reimagined education for the 21st century.</p><p><em>The difference isn’t the tools.<br></em>It’s how seriously you treat architecture, validation, and failure modes. <br>If there’s one lesson here, it’s this: <strong>Don’t just ship an MVP. Engineer a platform that survives success.</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c62dc4c0e4e2" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Lessons from Using 17 Billion Tokens with Cursor While Shipping AI Products]]></title>
            <link>https://gundogmuseray.medium.com/lessons-from-using-17-billion-tokens-with-cursor-while-shipping-ai-products-430707476186?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/430707476186</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[developer-tools]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[productivity]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Wed, 24 Dec 2025 14:27:39 GMT</pubDate>
            <atom:updated>2025-12-24T14:28:36.810Z</atom:updated>
            <content:encoded><![CDATA[<p>Most active Cursor user — %0.6</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7qJkxeyGYjX4M3v-B3pMlg.jpeg" /></figure><p>I’ve been using <a href="http://cursor.com/">Cursor</a> as my primary IDE for over a year. I’m not writing this to say <em>“AI made me 10x faster”</em> or <em>“look what I built with magic.”</em><br> If anything, this is the opposite.</p><p>After nearly a year of heavy usage and more than <strong>17 billion tokens</strong>, I can confidently say this:</p><blockquote><em>You cannot produce something truly solid with AI alone.<br> And if you do, you’ll pay for it later — in maintainability, cost, or complexity.</em></blockquote><p>Let me set the context first.</p><h3>How I Used Cursor</h3><p>I didn’t discover any secret tricks or hidden features.<br> No magic workflows.</p><p>What I <em>did</em> spend serious time on was:</p><ul><li>prompt engineering</li><li>understanding LLM limitations</li><li>learning where these models fail silently</li></ul><p>I also bring <strong>6+ years of hands-on software engineering experience</strong>.</p><p>My work spans:</p><ul><li>DevOps and occasional IaC</li><li>backend and frontend</li><li>AI agents and system design</li></ul><p>Recently, I built and shipped <a href="http://carna.ai/"><strong>Carna</strong></a><strong> </strong>— a platform with <strong>thousands of daily active users</strong>.</p><p>That matters, because usage at scale exposes problems that demos never show.</p><p>Thanks to the <a href="http://cursor.sh/">Cursor</a> team for building something that’s genuinely useful in production.</p><h3>Why Cursor?</h3><p>My reasons were mostly practical:</p><ol><li><strong>VS Code familiarity</strong><br> Years of using VS Code made stacking <a href="http://cursor.sh/">Cursor</a> on top of existing habits almost frictionless. Adaptation was easy.</li><li><strong>Strong UX / DX focus</strong><br> The Cursor team handled feedback well. Over time, the product shifted from an “AI showcase” to a developer-first IDE.</li><li><strong>Weak alternatives</strong><br> Other IDE-integrated AI tools simply weren’t good enough in real-world use.</li><li><strong>Terminal-first tools didn’t fit me</strong><br> I tried options like Claude Code, but my habits didn’t align with terminal-centric workflows.<br> If I had strong <strong>vim</strong> experience, I’d probably get similar productivity from <strong>Claude Code + Warp</strong>.</li></ol><h3>How My Workflow Evolved</h3><p>Both AI models and Cursor itself changed significantly over the last year.</p><p>Early on, one of my most-used features was Docs. After <strong>Context7 MCP</strong> was released, I almost completely stopped using it.</p><p>For a long time, my user rules included something like:</p><blockquote>“You are always free to investigate, collect information, and search the codebase.<br> But you must ask for permission before edits after explaining what you plan to do.”</blockquote><p>Once <strong>plan mode</strong> and similar features arrived in AI IDEs, even this became less necessary.</p><p>In the beginning, I relied heavily on:</p><ul><li>PRDs</li><li>planning documents</li><li>markdown-based progress tracking</li></ul><p>Everything revolved around the context window.</p><p>In the last 1–2 months, increasing <strong>context window sizes</strong> made most of that obsolete.</p><p>My typical setup now:</p><ul><li><strong>Gemini 3</strong> → planning and general programming</li><li><strong>Sonnet 4 / 4.1 / 4.5 (1M)</strong> → execution</li><li><strong>Opus 4.5</strong> → system design, architecture, controlled development</li></ul><p>Every iteration matters.</p><p>I <strong>review every single code change</strong> the agent makes.<br> If I don’t like the direction, I stop it, refine the prompt, and push for higher-quality output.</p><p>When a model repeatedly fails:</p><ul><li>I design the abstraction myself</li><li>restructure files</li><li>clarify the logic manually</li></ul><p>Only then do I let the model continue.</p><p>For MCP servers, about <strong>90% of my usage</strong> comes from:</p><ul><li>sequential-thinking</li><li>context7</li></ul><h3>What I Actually Learned</h3><p>The real value of AI in software engineering is not automation — it’s leverage for experienced judgment.</p><p>AI — Cursor included — is not something mystical to me.<br> It’s a tool. Nothing more.</p><p>In the right hands, tools increase productivity.<br> In the wrong hands, they’re dangerous.</p><p>Electricity is useful.<br>So is natural gas.<br>Both can also kill you.</p><p>Technology that’s deeply embedded in our lives becomes harmful if it’s not used correctly and safely.</p><p>That’s why I don’t believe AI will take my job.</p><p>If anything:</p><ul><li>it simplifies my work</li><li>increases my velocity</li><li>reduces cognitive load</li></ul><p>Once you’re experienced, you already know the likely root causes.<br> Instead of reading every line, you guide the AI <em>where to look</em>.</p><p>I now have:</p><ul><li>a system that executes boring chores</li><li>something like a mid-level engineer that needs review and feedback</li><li>an always-available assistant</li><li>someone who can search the web on my behalf</li></ul><p>This expands:</p><ul><li>my idea space</li><li>my solution spectrum</li><li>my willingness to experiment</li></ul><p>But I’m also very aware of the other side.</p><blockquote><em>In inexperienced hands, this technology produces spaghetti — or worse, garbage systems.</em></blockquote><p>AI hides problems well.<br> Everything looks like it “works” at first.</p><p>The cost shows up later.</p><h3>Not Magic —</h3><p>AI tools for coding perform well only when structure, constraints, and supervision are present.<br>Without them, they produce output that looks correct early — and becomes expensive later.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=430707476186" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When “Best Practices” Break — Yes, Let’s Reinvent the Wheel]]></title>
            <link>https://gundogmuseray.medium.com/when-best-practices-break-yes-lets-reinvent-the-wheel-aad2d42d3b16?source=rss-6702890b8f5f------2</link>
            <guid isPermaLink="false">https://medium.com/p/aad2d42d3b16</guid>
            <category><![CDATA[teamwork]]></category>
            <category><![CDATA[decision-making]]></category>
            <category><![CDATA[leadership]]></category>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Eray Gündoğmuş]]></dc:creator>
            <pubDate>Thu, 30 Oct 2025 11:16:15 GMT</pubDate>
            <atom:updated>2025-10-30T11:19:44.857Z</atom:updated>
            <content:encoded><![CDATA[<h3>When “Best Practices” Break — Yes, Let’s Reinvent the Wheel</h3><h4>A field guide to testing assumptions when humans — and their biases — are in the loop</h4><blockquote><strong>TL;DR<br>Best practices ≠ truth:</strong> Most “truths” are context-dependent hypotheses; they need evidence.<br><strong>The human factor breaks things:</strong> People-heavy, one-size-fits-all methods rarely work as intended.<br><strong>Bias management matters:</strong> Status quo, sunk cost, and groupthink quietly derail teams.<br><strong>Three rules:</strong> Learn from anyone · Represent, don’t prosecute · No acceptance without tests.<br><strong>Ship over argue:</strong> The fastest way to prove a point is to <strong>ship</strong> something that works.<br><strong>Takeaway:</strong> Truth doesn’t need urgency; it needs a <strong>process</strong> — and the courage to keep showing up.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*3VhVbnpcWOSV431I" /><figcaption>Photo by <a href="https://unsplash.com/@purzlbaum?utm_source=medium&amp;utm_medium=referral">Claudio Schwarz</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>I’ve spent years working with sharp, ambitious engineers — looking closely at their input, questioning a lot and accepting some. Along the way, I learned fast — and unlearned faster. I strongly opposed certain methods — even against the crowd — and followed others even when they seemed minor.</p><p>My modest experience and my curious, questioning, sometimes even excessive nature sped up how I learned certain things. All I can do is speak from my truth and experience. Here it is:<strong> much of what we’re told is incomplete — or context-dependent.</strong></p><p><strong>Sometimes, reinventing the wheel is the right thing to do.</strong></p><p>If you add the human factor, people-heavy, one-size-fits-all methods rarely work as intended.</p><blockquote><strong><em>What’s one people-heavy rule in your org that doesn’t work as intended? </em></strong><em>Drop a one-liner .</em></blockquote><p>Science is about evidence. It examines statements we can verify. The math behind a sorting algorithm is provable and testable; we can reach consensus on it. But on clean code, the “best” software processes, and the “best” way to manage teams, we lack data that would pass a strict scientific bar. Instead, we rely on educated guesses, limited tests, and practices we keep mostly because nothing decisively better has emerged.</p><p>As in most parts of human life, software teams and structures are full of politics and a bit of hypocrisy. <strong>Many methods, solutions, and people-driven practices end up used outside their technical purpose — or point us in the wrong direction.</strong><br>History shows the pattern. Religion seeks good, yet once filtered through human hands it can be used to mislead. Money replaced barter for sound reasons, yet it often drifts from that intent.</p><p>Name the problem -‘This meeting could have been an email’- and rather than change, people defend the routine. That’s how biases show up: status quo bias, commitment to old choices, sunk costs. Warn that technical debt grows and someone says sales beat code -another fast, biased judgment. If you look closely, you’ll catch the paradox: DRY (Don’t Repeat Yourself) advocates keep repeating themselves; KISS (Keep It Simple, Stupid) champions keep adding complexity.</p><p>Even when it’s said with good intentions, people don’t like hearing they’re wrong or that they did something badly. So you’re taught that getting along with people matters more. But that idea is debatable. Putting harmony first in every situation doesn’t fit human dynamics, doesn’t guarantee good outcomes, and often turns into avoidant behavior.</p><p>What should we do? First, admit it: we don’t always have the strongest mindset — me neither. There are moments when stepping back beats pushing the truth. There are times we know we’re right but can’t prioritize the argument. And yes, the other person’s mood — or the distance in understanding — can stop us cold.</p><p>That’s where the dilemma lies. Sometimes we’re responsible for doing what’s right and performing under pressure in our domain. Courage isn’t about having no fear; it’s about acting anyway. Being fearless can even slide into a kind of madness.</p><p><strong>1) Learn from anyone. </strong>The form and the source are secondary — interrogate the idea itself. If it’s false, keep it as ‘known false’ rather than refusing to learn. If it’s true, don’t stop there: translate it into practice, make it work in your life, and, when necessary, shape it into a unique version that fits you.</p><p><strong>2) Don’t try to prove the truth</strong>. You’re not its prosecutor — you can be its representative. Apply and model what’s right without putting yourself at risk. Others may be wrong; give them time. Understanding and change take a process.</p><p>If you’re testing methods and chasing truth, spend less energy battling ignorance and more on what you contribute. Hold on to your value — keep it front and center.</p><p>There’s no need to sprint toward righteousness. In every major event, someone was there questioning and problem-solving, even if they were silenced. If truth is your aim, be patient — truth has a way of emerging on its own. In debates, we tend to frame ignorance as a foe. Treat ignorance as a starting point, not an enemy: you wouldn’t blame a baby for not running, or tell a blind person to ‘just look.’ Don’t turn people into opponents just because they haven’t perceived what you have.</p><p>What can you <strong>ship this week</strong> that proves a point <strong>without arguing</strong>?</p><p><strong>3.) No acceptance without testing and observing (including the two rules above).</strong> Audit your ‘truths’ periodically in proportion to the speed of the field; they may need to change. If you know something is false, resist — actively at the right time, passively when that’s wiser.</p><p>Don’t intervene without assessing risk or without a margin of safety. Remember: how, when, and by whom the truth appears is often unpredictable — sometimes it shows up in a world of errors. Visible outcomes — good or bad — don’t, by themselves, prove a method or idea right or wrong. In fact, being wrong is often a positive. What matters most is the process and what it teaches.</p><blockquote><em>Truth doesn’t need urgency; it needs a process—and the courage to keep showing up.</em></blockquote><p>Let’s admit it: we rely on methods born 20–30 years ago, and we’ve been too slow to create the next set. Still, evolution is coming — most of today’s ‘best’ will be tomorrow’s baseline.</p><p><strong>Your turn:</strong> name one practice we’ll be ashamed of later, and propose a small experiment to replace it.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=aad2d42d3b16" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>