Reference

Dictionary API

Read typed dictionaries, configure active languages, and keep visitor text in separate translation domains.

getDictionary(Astro.currentLocale) is the server-rendering entry. Dictionaries remain modular under each locale/domain, with index.ts and types.ts per domain. Normal components read their own Astro locale. Server Islands receive locale explicitly because their request is isolated. This feature adds no custom router.

Optional browser payload

Choose a dictionary owner by meaning: shared control labels/placeholders belong to forms, reusable actions to buttons, menu labels to navigation, legal document names to their legal owner, and general failures to an existing error domain. Keep page editorial text with its page domain. Reuse a canonical semantic key instead of copying a shared field label into each page. Equal words can have different meanings; do not add a global string deduplicator.

Keep modules statically inspectable by locale tooling. Store typed keys in UI configuration and resolve them in the consuming component rather than importing runtime dictionary values into another domain’s data. Provider validation messages project the shared owners; they are not a second copy of UI translations.

When a section needs several translated browser messages, configure Main:

<Main path='/' clientTranslations={['common', 'buttons']}>
  <ContentSection />
</Main>

The default empty array emits no payload. Domains are typed dictionary keys and deduplicated. Main emits one inert application/json script with id="kit-translations" and { locale, translations }. Only the selected domains for the active locale are included. HTML-sensitive opening brackets are escaped so dictionary text cannot terminate the script. This is public UI data, never a place for environment values, credentials or private API responses.

Read it in the owning section’s processed browser script:

import type { ClientTranslations } from '@/i18n/types'

const setup = () => {
  const node = document.getElementById('kit-translations')
  if (!node?.textContent) return
  const { locale, translations } = JSON.parse(
    node.textContent
  ) as ClientTranslations<'common' | 'buttons'>
  // Wire this section's UI with translations.common and translations.buttons.
}
setup()
document.addEventListener('astro:page-load', setup)

Choose the same domains in Main and the type argument. The static type is a consumer contract, not validation of arbitrary external JSON. Read the current DOM after each navigation; do not cache a dictionary globally across locales. Own listener cleanup/idempotency in the consuming section as usual.

There is no Base64 conversion, window dictionary, new client helper or default whole-dictionary download. Existing components using a few data attributes can keep doing that without enabling this payload. Importing getDictionary directly in browser code remains possible but includes the dictionaries in that bundle; prefer this scoped payload when the section only needs a few domains.

API content and translated routes

Before integrating API/CMS content or language-dependent slugs, read Localized content routes. It defines translation-group identity, provider normalization, SSG/SSR/live/browser resolution, missing translations, caching and consistent navigation/SEO. Each locale owns dictionaries/<locale>/routes.ts beside its dictionary index. Shared names/types live in src/config/routes.ts; route-tables.ts registers the tables without duplicating URLs. Use null for unavailable pages. These structural files stay outside UI domains and browser translation payloads. The resolver share path, routeName or localizedPaths between Main, SEO and LanguagePicker. Link/Button also accept routeName; routeEntries(locale) exposes real named destinations for navigation or an HTML sitemap. Astro still owns route generation.

Language scaffolding and validation

Initial installation emits only selected languages/domains. Built-in presets are en-us, es-mx and es-es. Later language additions inspect current dictionary keys and create empty translations, preserving custom domains and structural arrays. No posts, products, pages or translated slugs are created.

Draft languages remain in availableLocales but out of locales in config.ts. Fill translations and language labels before deliberately activating their routes. check:i18n validates active dictionaries as well as Astro markup; empty active strings fail. If a key is intentionally empty, document it explicitly in an optionalTranslationKeys array in config.ts using domain.path keys. Do not use that exception to disguise untranslated content. Dynamic dictionaries and string-literal type constraints require review rather than execution or guessing.

Pseudo-locale stress test

Start the dev server with PUBLIC_I18N_PSEUDO=true to render every dictionary string bracketed, accented and lengthened (short labels grow about 80%, long copy about 35%, like real translations). {placeholder} tokens are kept.

# Use the project's runner: bun, npm or pnpm.
PUBLIC_I18N_PSEUDO=true bun run dev

In PowerShell, set $env:PUBLIC_I18N_PSEUDO = 'true' before running the dev script.

Check each page at 320px and the configured breakpoints: nothing should overflow, overlap or truncate meaning. Visible text without brackets did not come from a dictionary. The transform runs only in astro dev; builds and previews always render the real copy. The variable must be set in the shell that starts the server; restart the server to toggle it.