I18n

Right, so you’ve built a beautiful, responsive UI. It looks perfect. Until someone views it in a language that reads right-to-left, like Arabic or Hebrew, and suddenly your meticulously placed “Add to Cart” button is floating in the void like a lost astronaut. The web is a global place, and assuming left-to-right (LTR) is a fantastic way to look amateurish to a huge portion of your audience. Thankfully, CSS does most of the heavy lifting here with the dir attribute and the direction property. Our job in TypeScript isn’t to reimplement that logic, but to model it, to make our components direction-aware and our functions robust enough to handle the flip. We’re adding type-safety to a design paradigm.

Right, let’s talk about making your dates and numbers look like they belong on this planet. You’ve probably reached for Intl.DateTimeFormat and Intl.NumberFormat and thought, “This is great! I’ll just… uh…” and then your TypeScript compiler started screaming at you. That’s because these APIs are incredibly powerful, but their types are a glorious mess of string literals and overloads. TypeScript knows what’s valid, but it often refuses to hold your hand. It’s our job to be smarter than the average type assertion.

Right, let’s talk about ARIA. You’ve probably heard the mantra: “No ARIA is better than bad ARIA.” It’s good advice, but it’s led to a weird fear of using it at all. The truth is, when you’re building a complex, dynamic web app, you need ARIA to bridge the gap between what your div-soup looks like and what it actually is for a screen reader user. TypeScript, being the wonderfully pedantic friend it is, can actually help you write good ARIA instead of avoiding it.

Right, so you’ve decided you don’t want your app to greet your German users with a friendly, debug-mode-style "homepage.header.welcome_message" instead of an actual “Willkommen”. We’ve all been there. The classic i18n (internationalization) problem is that your translation files are just loose JSON objects living out in the wild, and your code is just making a hopeful, stringly-typed request for a key that might not exist. TypeScript’s entire reason for being is to catch this exact class of error at compile time, not in your user’s console. So let’s use it.

Right, let’s talk about making your app speak human. Not just a human, but many humans, in their own languages and formats. And we’re going to do it without resorting to a brittle mess of string keys and hope. We’re using TypeScript, for heaven’s sake. We have a type system; let’s make it earn its keep. The core problem with most i18n setups is that your translation files are a black box. You have a key like homepage.greeting and you just… hope that the value for that key exists and has the right number of placeholders. It’s like sending a junior developer to a meeting with a sticky note that just says “ask about the thing.” It’s a strategy, but not a good one.

Right, let’s talk about something that starts with the best intentions and often ends in a tangled mess of stringly-typed despair: managing translation keys. You’ve decided to not hardcode every user-facing string, which is fantastic. But if you’re just doing t('some_key') all over your codebase, you’ve traded one problem for another. You now have a codebase littered with invisible dependencies on a JSON file you need to pray you spelled correctly. TypeScript exists precisely to save us from this particular flavor of self-inflicted pain.

Right, so you’ve built a beautiful, left-to-right (LTR) site. Everything is neatly aligned to the left, your navigation is on the left, your “close” button is in the top-right corner, and your design has a certain… well, let’s call it a Western sensibility. Now you need to support a language like Arabic or Hebrew, and the entire visual logic of your layout flips on its axis. Welcome to the wonderfully disorienting world of Right-to-Left (RTL).

Right, let’s talk about the silent, soul-crushing workhorses of any multilingual site: dates and numbers. You can have the most beautiful translation in the world, but if you present a French user with “5/12/2023” and they have to wonder if it’s May 12th or December 5th, you’ve lost them. It’s a small detail that screams “amateur hour.” We’re not amateurs. We’re going to get this right. The secret weapon here is the Intl object (short for Internationalization). This is the browser’s and Node.js’s built-in, no-dependency-required powerhouse for doing this stuff correctly. It’s not some clunky library from 2010; it’s a modern API that leans on the Unicode CLDR (Common Locale Data Repository), which is basically the holy text for how cultures format things. We use it.

Right, so you’ve got a site that speaks multiple languages. Congratulations, you’ve just multiplied your complexity. The language switcher is the public-facing proof you’ve pulled it off. It’s the little widget that says, “Hey, we see you,” and it’s deceptively tricky to get right. It’s not just a dropdown; it’s a state machine with opinions about URLs, user sessions, and SEO. Let’s build one that doesn’t suck. The Core Logic: It’s All About the URL Forget sessions, forget cookies as your primary method. The single most important rule for a language switcher is this: the chosen language must be reflected in the URL. Why? Because a URL is a unique, shareable, bookmarkable representation of the resource. If I copy a URL for /fr/a-propos and send it to you, you should see the French page, not get redirected to English because your browser prefers it. This is non-negotiable for SEO and basic user sanity.

Right, let’s talk about menus. You’ve set up your i18n paths, your locales are neatly organized, and your content is being translated. Fantastic. But now you need a menu that changes its items based on the user’s language. This is where many frameworks’ built-in i18n support suddenly gets a bit… vague. They handle the routes, but they leave the content of those routes up to you. And they’re right to do so. Your menu structure is your business, not the router’s.

Right, let’s talk about making your site speak other languages. You’re not just slapping a Google Translate widget on this thing and calling it a day, are you? I thought not. That’s a one-way ticket to “le chicken fried” territory. We’re going to do it properly, which means we’re diving into the i18n directory and the T function. This is the bedrock. Get this right, and the rest is (mostly) smooth sailing.

Alright, let’s talk about linking translated pages. This is where the rubber meets the road. You’ve painstakingly translated your content, and now you need to tell both users and search engines that “this page in French is the same as that page in English.” Get this wrong, and you’ll have a fragmented, confusing mess where your SEO value is diluted and users can’t easily switch languages. It’s a bad time.

Right, so you’ve decided to build a site for more than one language. Congratulations, you’ve just leveled up from “building a website” to “managing a small, digital Babel.” It’s a fantastic problem to have, but how you structure the actual files and URLs for this endeavor is your first, and arguably most important, architectural decision. Get it wrong, and you’ll be haunted by redirect loops and SEO ghouls for years. Get it right, and everything else—localization, routing, deployment—becomes significantly easier.

Right, let’s get your hugo.toml (or config.toml for you old-timers) ready for its new life as a polyglot. This isn’t just flipping a switch; it’s about telling Hugo, “Hey, buddy, we’re not just doing one language anymore, so get your act together.” We’ll do this step-by-step, and I’ll explain the why behind the weirdness because some of these configuration options look like they were chosen by a random word generator.

Right, let’s talk about time. Or more specifically, let’s talk about how computers handle the bafflingly human concept of timezones. If you’ve ever tried to schedule a meeting with someone in another country and felt a deep, existential dread, you already understand the problem. Your database stores a timestamp, but is that timestamp in UTC? Local time? The timezone of your server, which is in a data center you’ve never actually visited? This is how outages and missed birthday calls happen.

Alright, let’s talk about Right-to-Left (RTL) text. You’ve probably been blissfully living in a left-to-right world, where everything starts at a sensible, familiar corner of the screen. Then, one day, you need to support Arabic or Hebrew, and suddenly your entire UI looks like it’s been through a matter-antimatter inversion. Welcome. It’s not actually that bad, but it’s a domain where a little knowledge prevents a lot of utterly bizarre layout bugs.

Right, so you’ve decided your Python application shouldn’t be a parochial little hermit that only speaks one language. Good for you. Welcome to the wonderful, occasionally maddening, world of making your code play nice with the entire planet. We call this twin-headed beast “i18n” (internationalization - 18 letters between the ‘i’ and the ’n’) and “l10n” (localization - 10 letters, you get it). i18n is the plumbing: the hooks and architecture to make multiple languages possible. l10n is the actual translation and cultural adaptation. You can’t have the second without the first.

Right, let’s talk about the part of i18n that feels like you’re tagging your entire codebase with digital sticky notes: marking strings for translation. This is where we use gettext, the granddaddy of i18n libraries, a piece of software so old and battle-tested it has its own particular, slightly musty, smell. Don’t worry, it’s still incredibly effective. The core idea is simple, even if the implementation makes you want to weep. You wrap every user-facing string in your code in a special function call. This tells the gettext system, “Hey, this one needs to be translated.” Later, a tool will scan your code, find all these tagged strings, and create a template file (.pot) for translators to fill in. The magic happens at runtime: when your function is called, it looks up the original string in the correct translated catalog and returns the translation. If it doesn’t find one, it just returns the original string. No harm, no foul.

Right, let’s talk about making your app stop being so… American. Or British. Or whatever your default is. You’ve probably hard-coded a comma here, a dollar sign there, and called it a day. That works until your first user from Germany sees 1,99 for a price and thinks you’re charging one dollar and ninety-nine cents, not one thousand and ninety-nine. Whoops. That’s where locale comes in—it’s your app’s cultural and linguistic settings, and it’s the single most important tool for not accidentally insulting your users’ number formats.

Right, let’s get our hands dirty with the actual bytes. You’ve probably heard “just use UTF-8” as a mantra, and 99% of the time, that’s brilliant advice. But it’s our job to understand the why behind the mantra, so we know how to handle that other 1% and, more importantly, so we can debug the spectacularly weird errors that happen when this goes wrong. First, a crucial distinction. Encoding is the map that turns abstract characters into bytes. Unicode is the grand, all-encompassing catalog of every character we might want to use. UTF-8, UTF-16, and even the ancient Latin-1 are different encodings for that Unicode standard. Think of Unicode as the idea of “the number 42,” and UTF-8 as the specific way to write those digits as bytes (0x34, 0x32).

Right, let’s get into the weeds. You’ve probably heard that “Unicode solves everything.” It mostly does, but it does so by trading a simple, obvious problem (mapping one character to one number) for a complex, robust solution (mapping human text to a system of codes, rules, and algorithms). It’s a fantastic trade, but you need to understand its machinery or it will bite you. Think of Unicode not as a simple character set but as a database. Its core abstraction is the code point. A code point is just a number, represented as U+XXXX, where XXXX is a hexadecimal value. For example, the code point for the letter ‘A’ is U+0041. This number isn’t the bytes you’ll store it in; it’s the abstract idea of the character. The range of possible code points is massive: from U+0000 to U+10FFFF. That’s over 1.1 million slots. We call this entire space the Codespace.