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.