Build an Astro Multilingual Blog Without Migrating Existing URLs

Start with the URL contract#

Suppose an existing Traditional Chinese article is already published at:

1
/posts/astro-sitemap/

Moving it to /zh-tw/posts/astro-sitemap/ would create a migration project: redirects, canonical changes, sitemap churn, and a period in which crawlers reconcile old and new URLs. None of that is necessary just to publish English content.

Astro supports an unprefixed default locale and prefixed secondary locales. The relevant configuration is:

1
export default defineConfig({
2
  site: "https://example.com/",
3
  trailingSlash: "always",
4
  i18n: {
5
    defaultLocale: "zh-TW",
6
    locales: ["zh-TW", "en"],
7
    routing: {
8
      prefixDefaultLocale: false,
9
      redirectToDefaultLocale: false,
10
    },
11
  },
12
});

With this policy, the observable route contract becomes:

The en/ segment in the content collection keeps source files organized. It must not leak into the public slug, or the site will produce /en/posts/en/....

Put locale rules in one module#

Route files, post cards, related posts, RSS, and structured data all need the same mapping. A small locale module prevents each caller from inventing its own version.

1
export const DEFAULT_LOCALE = "zh-TW" as const;
2
export const SUPPORTED_LOCALES = [DEFAULT_LOCALE, "en"] as const;
3
export type Locale = (typeof SUPPORTED_LOCALES)[number];
4

5
export function normalizeLocale(value?: string | null): Locale {
6
  if (!value?.trim()) return DEFAULT_LOCALE;
7
  if (value === "en") return "en";
8
  if (value === "zh-TW" || value === "zh_TW") return "zh-TW";
9
  throw new Error(`Unsupported locale: ${value}`);
10
}
11

12
export function getPublicPostSlug(slug: string, locale: Locale): string {
13
  if (locale === "en") {
14
    if (!slug.startsWith("en/")) {
15
      throw new Error(`English post must live below en/: ${slug}`);
16
    }
17
    return slug.slice(3);
18
  }
19

20
  if (slug.startsWith("en/")) {
21
    throw new Error(`Default-language post cannot use en/: ${slug}`);
22
  }
23
  return slug;
24
}
25

26
export function getPostPath(slug: string, locale: Locale): string {
27
  const prefix = locale === "en" ? "/en" : "";
28
  return `${prefix}/posts/${getPublicPostSlug(slug, locale)}/`;
29
}

Throwing on unknown locales is intentional. A silent fallback can publish a third language into the wrong index or create a canonical URL that does not match the route.

Filter content before sorting it#

A multilingual homepage is only one visible part of the system. Previous/next navigation, category counts, tag counts, and related-post scoring can all cross language boundaries if filtering happens after those values are calculated.

Filter the collection first:

1
async function getSortedPosts(locale: Locale = DEFAULT_LOCALE) {
2
  const posts = await getCollection("posts", ({ data }) => !data.draft);
3

4
  const localizedPosts = posts.filter(
5
    (post) => normalizeLocale(post.data.lang) === locale,
6
  );
7

8
  return localizedPosts.sort(
9
    (a, b) => b.data.published.valueOf() - a.data.published.valueOf(),
10
  );
11
}

Only after this step should you assign previous and next posts or calculate related content. Keep the locale argument defaulted to the original language so unchanged callers preserve their behavior.

Generate explicit English routes#

Astro file-based routes make the public boundary clear. Keep the original list route at src/pages/[...page].astro, then add an English list route at src/pages/en/[...page].astro.

1
---
2
import type { GetStaticPaths } from "astro";
3
import { getSortedPosts } from "../../utils/content-utils";
4

5
export const getStaticPaths = (async ({ paginate }) => {
6
  const posts = await getSortedPosts("en");
7
  return paginate(posts, { pageSize: 10 });
8
}) satisfies GetStaticPaths;
9
---

The English article route performs the same locale-specific query and removes the repository prefix when producing route parameters:

1
return englishPosts.map((entry) => ({
2
  params: { slug: getPublicPostSlug(entry.slug, "en") },
3
  props: { entry },
4
}));

Pass lang="en" from this route into the shared layout and UI components. Do not ask components to inspect window.location or browser preferences. Explicit props also work during static rendering and make missing translations easier to detect.

Keep feeds and metadata locale-specific#

Create /en/rss.xml from getSortedPosts("en"); keep /rss.xml on the default query. Every feed item link should use the same getPostPath mapping as article cards and Schema.org data.

Each page also needs an absolute self-canonical. An English article should resolve to:

1
<link rel="canonical" href="https://example.com/en/posts/example-slug/">

Do not add hreflang merely because two pages discuss Astro. It describes localized alternatives of the same page. Independent English topics should remain self-canonical without an alternate pair. The decision rules are covered in Hreflang for Independent Multilingual Content.

Verify the generated site, not only TypeScript#

Static-site bugs often appear in output paths or HTML rather than in type checking. After pnpm check, run the production build and inspect the artifacts:

1
pnpm build
2

3
test -f dist/index.html
4
test -f dist/en/index.html
5
test -f dist/rss.xml
6
test -f dist/en/rss.xml
7

8
rg '/en/posts/en/' dist
9
rg '<html lang="en"' dist/en
10
rg 'rel="canonical"' dist/en/posts

The first rg command should return no matches. Also inspect the sitemap and confirm that old default-language paths are unchanged.

Pagefind can use the same <html lang> boundary to separate search indexes. Pagefind Multilingual Search in Astro shows how to validate that part of the build.

The practical takeaway is to preserve public URLs first, then make locale explicit at every content and URL boundary. Once routes, queries, metadata, and feeds share that contract, English posts can be independent without destabilizing the existing site.

FAQ#