Astro Internationalization: Plan URLs Before Translation

Astro internationalization needs a stable URL for each published language version and a clear rule for missing translations. Configure the locale routes, then connect equivalent pages through a shared page identity. Keep established default-language URLs unless the migration has a specific reason to change them. For an unfinished translation, choose deliberately between an unavailable page, a redirect, and visible fallback content.

TL;DR

---

• Choose the default-language URL before building translations; an established English route can remain at its existing path.
• Give each page a stable internal ID and record the published path and translation status for each locale.
• Define what happens when a translation is missing rather than sending visitors to a route that appears to be translated.
• Generate language selectors and alternate-language metadata from the same reviewed map of published equivalents.
• Test the actual deployment routes, language switching and missing translations before launch.

What does Astro internationalization need to cover?

Astro supplies routing helpers and fallback options. Your team still owns the translated copy, page relationships, language selector, and search metadata. A generated locale URL is not evidence that the destination has a reviewed translation.

This guide gives a technical lead a proposed English–Arabic route plan and launch acceptance matrix. The example is hypothetical. It does not describe a Hapy customer deployment. Use the broader Astro SEO migration guide for the full migration inventory and search checks.

Choose the default-language URL before building pages

Keep an existing English page at /services/ if that URL already serves the business and no requirement justifies changing it. Add the translated version under a locale path, such as /ar/services/. This reduces unnecessary URL changes during a migration. Prefixing every language is also valid when the site needs that structure.

Astro’s internationalization routing documentation defines prefixDefaultLocale as the setting that controls the default language’s prefix. The page files must match the selected route structure.

For the hypothetical site, choose unprefixed English URLs. The configuration below establishes that route policy. It does not generate translations or set the page’s SEO tags.

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    locales: ['en', 'ar'],
    defaultLocale: 'en',
    routing: {
      prefixDefaultLocale: false,
    },
  },
});

If you prefix every language, make a separate decision for /. Astro documents redirectToDefaultLocale for redirecting the root to the prefixed default locale. Verify the actual deployed response because static output, an adapter, and hosting rules can affect redirect delivery. Do not treat arriving at the correct page in a browser as proof of an HTTP redirect.

Give each page an identity across languages

Use a stable internal page ID to connect translations. Store each locale’s published path and translation status against that ID. Build the language selector from that mapping, especially when translated slugs differ.

Consider this proposed content record:

The slugs are examples, not a recommendation for Arabic terminology. A content owner should approve the actual paths. The useful distinction is between a page’s identity and its display path.

Astro’s i18n recipe shows route mappings and translated content organization. A URL helper can assemble a locale path, but the application still needs to know which translated page belongs to the current one. Replacing the first URL segment cannot reliably translate a different slug or detect an unpublished page.

For about, the selector should connect /about/ to /ar/about-us/. For pricing, label the Arabic version as unavailable or offer a clearly named alternative. Do not silently send a reader to the Arabic homepage while presenting the action as a translation of Pricing.

Keep translation status separate from route existence. Review the main copy, title, description, navigation, forms, and calls to action before marking a version published. For Arabic layout and mixed-direction data, use the dedicated Arabic website design and RTL guide.

Decide what happens when a translation is missing

Choose missing-translation behavior per content need. For a small marketing site, a reasonable starting policy is to publish only reviewed translations and omit unavailable versions from the selector. Someone requesting an unpublished path should receive the site’s intentional missing-page response. Add fallback behavior only when it helps the reader complete the task.

Astro separates the fallback language map, i18n.fallback, from the response behavior, i18n.routing.fallbackType. Its documentation distinguishes two built-in fallback approaches:

• A redirect takes the reader to the corresponding fallback-language URL.
• A rewrite serves fallback content while retaining the requested URL.

A fallback declaration does not translate the page. For example, an Arabic path that rewrites an English service page still contains English main content. Review its document language, navigation, notice, canonical, and alternate-language tags against what it actually serves.

Avoid using a fallback for a page whose offer or terms differ by market. A translation gap and a different commercial offer are separate content problems. Assign an owner to resolve the missing version instead of letting fallback hide it indefinitely.

Keep search metadata tied to published equivalents

Generate alternate-language links from the same reviewed page map used by the selector. A published English–Arabic pair should identify the actual equivalent URLs. An untranslated placeholder should not appear as a reviewed Arabic alternate.

Google’s localized-page guidance requires each language version’s alternate set to include itself and the other versions. Alternate URLs must be fully qualified, and paired versions need return links. The locale prefix alone does not create those relationships.

For the hypothetical About pair, review these relationships:

1. The English page identifies /about/ as its preferred English URL.
2. The Arabic page identifies /ar/about-us/ as its preferred Arabic URL.
3. Each page lists both fully qualified URLs in its hreflang set, with the correct language codes.
4. The language selector links between that same pair.
5. The sitemap and internal links use those published destinations.

A shared template can generate these fields, but inspect the rendered HTML. Do not point every translated page’s canonical to the English page merely because English is the default. Review duplicate fallback responses separately from genuine translated pages. Keep the wider redirect and canonical strategy in the parent migration guide.

Approve the bilingual route plan with evidence

Before launch, test the representative routes on the actual deployment mode. A local preview can show rendering, while the deployed host proves its own routing and response headers. Record expected behavior first so a successful page load cannot conceal a wrong language or destination.

Use this proposed acceptance matrix for the hypothetical site:

If the business chooses fallback instead, replace the Pricing expectations with the exact redirect or rewrite contract. Check both the HTTP response and visible language. Do not mark a rewrite as translated simply because it returns 200.

Test the selector with a keyboard and on mobile. Follow the main form journey in each published language. Check that a bookmark or shared link reaches the same language without relying on a previous cookie. If preference detection is needed, remember that Astro’s preferredLocale and preferredLocaleList are available for pages rendered on demand; a static page cannot inspect each visitor’s request headers during its build.

Name the person who approves each translation and the person who maintains the route map. Recheck the corresponding selector, metadata, and sitemap entries whenever a translation is added or removed.

Hapy offers Astro website migration services. If you need delivery support, bring the current URL inventory, target languages, and this route plan to the scoping discussion. Those decisions make the translation and routing work concrete before implementation starts.