Skip to content
IT // Adventures

A Bilingual Blog with Astro i18n

How I extended by blog to serve German and English content: routing, UI strings, and a language switcher that never points to a 404.

3 min read

This blog is written in German and English, and it is a fully static site. No server decides which language to send, no JavaScript switches texts at runtime. Everything is generated at build time with Astro.

This post walks through how I set that up: URL structure, UI strings, translated posts and the SEO details that are easy to get wrong.

Requirements

  1. German is the main language and lives at the root (/blog/...), English lives under /en/ (/en/blog/...).
  2. UI texts must be type-safe: a missing translation should break the build, not show up as a blank label.
  3. Posts can exist in one or both languages. If a translation exists, the two are linked. If not, nothing may point to a page that doesn’t exist.
  4. No client-side JavaScript for any of this.

Routing

Astro has built-in i18n routing. The whole configuration is a few lines in astro.config.mjs:

export default defineConfig({
  site: 'https://soltari.at',
  i18n: {
    locales: ['de', 'en'],
    defaultLocale: 'de',
    routing: {
      prefixDefaultLocale: false,
    },
  },
});

With prefixDefaultLocale: false the default language gets no prefix. Astro does not create the pages for you, though. It only provides the helpers (getRelativeLocaleUrl() and friends) and the Astro.currentLocale value. The routes are still files:

src/pages/blog/[slug].astro    -> /blog/hallo-welt/
src/pages/en/blog/[slug].astro -> /en/blog/hello-world/

To avoid duplicating logic, these route files are thin wrappers. They compute the static paths for their locale and hand over to a shared view:

---
import PostView from '../../../views/PostView.astro';
import { getPublishedPosts, postSlug } from '../../../lib/posts';

export const getStaticPaths = (async () => {
  const posts = await getPublishedPosts('en');
  return posts.map((post) => ({ params: { slug: postSlug(post) }, props: { post } }));
}) satisfies GetStaticPaths;

const { post } = Astro.props;
---

<PostView post={post} />

The German route is identical except for 'de'. All the markup lives once in src/views/, and the locale is derived from where the content sits.

Type-Safe UI Strings

For buttons, navigation labels and similar texts I use a plain TypeScript object per language instead of an i18n library. The German object defines the keys, the English one has to match:

const de = {
  'nav.blog': 'Blog',
  'post.readingTime': '{minutes} Min. Lesezeit',
  // ...
};

const en: Record<keyof typeof de, string> = {
  'nav.blog': 'Blog',
  'post.readingTime': '{minutes} min read',
};

export const ui: Record<Locale, Record<UiKey, string>> = { de, en };

If I add a key to de and forget en, astro check fails.

A tiny helper handles placeholders:

export function useTranslations(locale: Locale) {
  return (key: UiKey, params?: Record<string, string | number>): string => {
    const text = ui[locale][key] ?? ui[defaultLocale][key];
    return params
      ? text.replace(/\{(\w+)\}/g, (match, name) => String(params[name] ?? match))
      : text;
  };
}

In a component that becomes t('post.readingTime', { minutes: 3 }). Dates follow the same idea: Intl.DateTimeFormat with de-AT or en-GB, so no date format strings need translating.

Translated Posts

Posts are Markdown files in src/content/blog/de/ and src/content/blog/en/. The locale comes from the folder. Two files are linked when they share a translationKey in their frontmatter, and their slugs may differ:

# blog/de/.../hallo-welt.md
translationKey: hello-world

# blog/en/.../hello-world.md
translationKey: hello-world

getPostTranslations() collects, for a given post, every published post with the same key. The build fails if one key is used twice within a locale, which catches copy-and-paste mistakes early.

Alternates: hreflang and the Language Switcher

This is the part that is easy to get wrong. Search engines expect <link rel="alternate" hreflang="..."> tags pointing to the other language versions, and the language switcher should lead to the same content in the other language.

For pages like “About” the other version is simply the mirrored path (/about/ ↔ /en/about/), so that is the default. Everything else passes the layout an explicit map of the URLs that really exist:

  • Posts pass only the translations found via translationKey.
  • Year and tag pages pass only locales where that year or tag, with that page number, exists.

The layout feeds the same map into the SEO component and the language switcher. That way hreflang links and the switcher can never disagree. If there is no counterpart, the switcher falls back to the other language’s home page, and no hreflang tag is emitted at all.

German is also announced as x-default, and the sitemap integration is configured with the same locales so mirrored pages get their alternates there as well.

Pitfalls

  • One 404 page. A static host serves a single 404.html, so mine contains German and English text instead of one page per language.
  • Per-language lists. The blog index, tag pages and RSS feeds only list posts in their own language. Mixing languages in one list is confusing for readers and feed readers alike.
  • Tags are per language. A tag that exists only in German must not produce an English tag page, otherwise you get empty pages.

Conclusion

Astro’s i18n support is deliberately small: it handles configuration and URL helpers, while routes, strings and translation links stay in your hands. For a blog of this size that turned out to be an advantage. The system is a few hundred lines, fully typed, and everything is checked at build time.