The Astro integration is one package, @universally-sdk/astro, that serves your Astro site in every language of your Universally project from a single page tree. Your source language stays at /about, and each target language is served on the same host under its own prefix, such as /fr/about, with no extra routes. The integration is in Beta and needs Astro 5 or newer.
How translated pages are served
When you create an Astro project, the Setup Instructions screen asks How should translated pages be served? and offers three cards. Nothing is preselected, and Continue stays disabled until you pick one.
| Card | URL example | What happens |
|---|---|---|
| SDK (Recommended) | website.com/fr/ |
Your Astro server renders translated pages. You install one package. |
| JavaScript | website.com |
One script tag translates the page in the browser. No DNS change, but no search engine visibility, and public pages only. |
| Subdomain | fr.website.com |
Universally serves each language on its own subdomain by fetching your page and translating it. Your Astro app renders only the source language. |
Your site keeps running as it is until you finish the setup. The rest of this section covers the SDK and Subdomain modes.
How the SDK mode works
- Languages are read once, when your Astro config runs. The integration asks Universally for the project's languages, skips any whose Live switch is off, and uses each language's URL prefix as its path segment.
- Translations live in your server's memory. The whole catalog loads when the dev server or a build starts, so
t()is a synchronous lookup with no network call while a page renders. - New strings are reported after the response. A string with no translation yet renders in your source text and is sent to Universally once the visitor already has the page. A later render serves it translated, usually a second or two later.
- Dashboard edits reach your server by a push to your site, or by a check that runs at most once every 60 seconds per language by default.
- The source language costs nothing. On source pages
t()returns its argument and makes no lookup, report, or API call.
Glossary rules apply to every string, and edits you make on the Translations screen reach your server. Translation Rules is hidden for SDK projects, because your code decides what goes through t().
Limits
- No client side
t(). It exists only on the server, inAstro.locals. Islands receive translated text as props. - Static sites translate at build time. New strings and dashboard edits need a rebuild.
- Words come from your project's prepaid total. Once it is spent, strings that are already translated keep being served and new ones stay in the source language. See Usage limits.
- Creating a project needs the Owner or Admin role. See Roles and permissions.