Hi @humble valve. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
#FOUC on Language Toggle with Astro i18n and ClientRouter (View Transitions)
novel nymphBOT
Based on the provided knowledge sources, here’s what can be determined about your issue:
Is a full page reload on language toggle expected with Astro i18n and ClientRouter?
The knowledge sources do not explicitly state that a full page reload is required or expected when switching locales using Astro’s i18n system in combination with the <ClientRouter /> and view transitions. However, there are some important details and limitations to consider:
-
Client-side navigation with
<ClientRouter />: The<ClientRouter />is designed to intercept internal navigation (e.g., clicking<a>tags) and provide smooth, animated transitions without a full page reload, as long as both the source and destination pages are managed by the router and use the same routing context. It also allows programmatic navigation using thenavigate()function fromastro:transitions/clientfor custom navigation logic, such as language toggles. This should, in theory, allow for smooth transitions between localized routes if implemented correctly View transitions: Trigger navigation. -
i18n Routing and Middleware: Astro’s i18n system can be configured to use either automatic or manual routing. If you use manual routing, you are responsible for your own logic, but you can still use Astro’s i18n middleware programmatically Internationalization: manual. The i18n system does not mention any forced full page reloads when switching locales.
-
Preventing client-side navigation: There are mechanisms (like
data-astro-reloadon links) to force a full page reload, but these are opt-in. If you are not using these, navigation should remain client-side View transitions: Router control. -
Scripted navigation: The recommended way to trigger navigation programmatically is to use the
navigate()function fromastro:transitions/client, notwindow.Astro.navigate()(which is not documented in the sources). Using the correct function is important for ensuring the router intercepts the navigation and applies view transitions View transitions: Trigger navigation.
Workarounds and Recommendations
-
Use the documented
navigate()function: Make sure your language toggle usesimport { navigate } from "astro:transitions/client"and callsnavigate(newPath)rather than any undocumented global likewindow.Astro.navigate(). -
Ensure both source and destination pages are managed by
<ClientRouter />: Both the current and target language pages must be within the router’s context for client-side navigation to work. -
Check for middleware or redirects: If your i18n middleware or configuration is redirecting or rewriting URLs in a way that causes a full reload, review your setup. For example, if you use
redirectToDefaultLocale, it may affect how the root URL is handled Internationalization: redirectToDefaultLocale. -
No explicit mention of forced reloads: The documentation does not state that switching locales must cause a full reload. If you are experiencing this, it may be due to how the navigation is triggered or how your routes are structured.
Summary
- A full page reload on language toggle is not explicitly documented as required or expected with Astro’s i18n and
<ClientRouter />. - Use the official
navigate()function fromastro:transitions/clientfor language toggles. - Ensure both language versions are within the router’s context.
- Review your middleware and routing configuration for any forced reloads or redirects.
If you follow these patterns and still experience FOUC or full reloads, the knowledge sources do not provide further troubleshooting steps, and it may be a limitation or bug not covered in the current documentation.