Package APIs

@i18n-micro/astro

Exported API of @i18n-micro/astro, generated from the source.

Astro integration for i18n-micro — translations, routing, and islands.

Entry points: @i18n-micro/astro, @i18n-micro/astro/client, @i18n-micro/astro/client/preact, @i18n-micro/astro/client/react, @i18n-micro/astro/client/svelte, @i18n-micro/astro/client/vue, @i18n-micro/astro/middleware, @i18n-micro/astro/node.

`@i18n-micro/astro`

Composables

`useI18n`

Use i18n in Astro pages/components Returns helper functions for translations

function useI18n(astro: Astro): { … }

`useLocaleHead`

function useLocaleHead(astro: Astro, options?: LocaleHeadOptions): LocaleHeadResult

See LocaleHeadOptions · LocaleHeadResult

Functions

`createAstroRouterAdapter`

Prefix-except-default routing over plain paths. Paths here never carry Astro's base: the middleware strips it from what comes in and adds it to what goes out.

function createAstroRouterAdapter(
  locales: Locale[],
  defaultLocale: string,
  getCurrentUrl?: () => URL,
): I18nRoutingStrategy

See Locale · I18nRoutingStrategy

`createI18n`

Create an i18n instance (for a src/middleware.ts of your own).

function createI18n(options: AstroI18nOptions): AstroI18n

See AstroI18nOptions · AstroI18n

`createI18nMiddleware`

Create Astro middleware for i18n locale detection

function createI18nMiddleware(options: I18nMiddlewareOptions): MiddlewareHandler

See I18nMiddlewareOptions

`detectLocale`

Locale a visitor prefers: URL prefix → cookie → Accept-Language → default, the one precedence of resolveLocale. An explicit prefix always wins; autoDetect: false leaves only the URL.

function detectLocale(
  pathname: string,
  cookies: { get: (name: string) => { value: string; } | undefined; },
  headers: Headers,
  defaultLocale: string,
  locales: string[],
  localeCookie?: string | null,
  routingStrategy?: I18nRoutingStrategy | null,
  autoDetect?: boolean,
): string

See I18nRoutingStrategy

`getDefaultLocale`

Get default locale from Astro context

function getDefaultLocale(astro: Pick<AstroGlobal, 'locals'>): string

`getI18n`

Get i18n instance from Astro context

function getI18n(astro: Pick<AstroGlobal, 'locals'>): AstroI18n

See AstroI18n

`getI18nProps`

Props for a client island: what t() can answer on this page (route, root and fallback keys), or only keys of that, which is the way to keep the page small. Stored trees are shared, an island must not write into them.

function getI18nProps(
  astro: Pick<AstroGlobal, 'locals'>,
  keys?: string[],
): I18nClientProps

See I18nClientProps

`getLocale`

Get current locale from Astro context

function getLocale(astro: Pick<AstroGlobal, 'locals'>): string

`getLocaleRewritePath`

Strip locale prefix from the current URL for Astro.rewrite() on /[locale]/* routes.

function getLocaleRewritePath(astro: Astro): string

`getLocales`

Get all locales from Astro context

function getLocales(astro: Pick<AstroGlobal, 'locals'>): Locale[]

See Locale

`i18nIntegration`

Astro integration for i18n-micro: publishes the config and dictionaries, and installs the middleware.

function i18nIntegration(options: I18nIntegrationOptions): AstroIntegration

See I18nIntegrationOptions

`prepareLocaleRewrite`

Validate :locale, sync i18n/locals, and return the base path for Astro.rewrite(). Returns a Response when the locale param is invalid.

function prepareLocaleRewrite(
  astro: Astro & Pick<AstroGlobal, 'params'>,
): Response | string

Classes

`AstroI18n`

The runtime instance, plus what Astro pages use on top: per-route reads and a reset that keeps messages.

class AstroI18n extends I18n {
  constructor(options: AstroI18nOptions)
}

keepMessages

(messages: Record<string, Translations>, routeMessages: Record<string, Record<string, Translations>>) => void

Dictionaries loaded after the constructor that clearCache keeps too: a directory read at runtime.

getLocaleIso

() => Record<string, string>

The localeIso option: what an island needs to plural in another locale.

getRouteTranslations

(locale: string, routeName: string) => Translations | null

mergeTranslations

(locale: string, routeName: string, translations: Translations) => void

clearCache

() => void

Clear translation and formatter caches.

See I18n · AstroI18nOptions

Types

`AstroI18nOptions`

type AstroI18nOptions = I18nOptions

See I18nOptions

`I18nClientProps`

Props to pass to client islands (Vue, React, Svelte, Preact)

interface I18nClientProps

locale

string required

pluralLocale

string

The tag plurals go by: the locale's iso when it has one.

localeIso

Record<string, string>

Tags of the codes that have one, for setLocale. Absent when there are none.

fallbackLocale

string required

translations

Record<string, Translations> required

currentRoute

string required

`I18nIntegrationOptions`

interface I18nIntegrationOptions

`I18nMiddlewareOptions`

interface I18nMiddlewareOptions

`I18nRoutingStrategy`

Routing strategy interface for i18n in Astro Implement this interface to integrate with any routing logic Matches Vue/Solid/React package interface for consistency Adapted for Astro SSR context (push/replace are optional)

interface I18nRoutingStrategy

`LocaleHeadOptions`

Generate locale head meta tags for SEO

interface LocaleHeadOptions

baseUrl

string

Origin of the absolute URLs. Default: site from the Astro config, else root-relative URLs.

addDirAttribute

boolean

addSeoAttributes

boolean

hreflangBaseLanguage

boolean

Defaultfalse · Also emit bare-language hreflang tags derived from iso (never from routing code).

`LocaleHeadResult`

type LocaleHeadResult = LocaleHead

See LocaleHead

Re-exports

Declared in another package of this repository and documented on its page.

From @i18n-micro/core: defaultPlural · interpolate · localeIsoMap · FormatService
From @i18n-micro/types: CleanTranslation · Getter · Locale · LocaleCode · Params · PluralFunc · Translations

`@i18n-micro/astro/client`

Functions

`hasTranslation`

Checks if a translation exists in the state: a subtree counts, as on the server

function hasTranslation(state: I18nState, key: string, routeName?: string): boolean

See I18nState

`translate`

Pure function to get a translation from state, answering as the server's t() does over the same keys. getI18nProps already merged the root and fallback dictionaries into the state. For Linked Messages (@:path.to.key), use the server-side i18n instance.

function translate(
  state: I18nState,
  key: string,
  params?: Params,
  defaultValue?: string | null,
  routeName?: string,
): string | number | boolean | Translations | null

See I18nState · Params · Translations

Types

`I18nState`

I18n state for client islands

interface I18nState

locale

string required

pluralLocale

string

The tag plurals go by, when it is not locale.

localeIso

Record<string, string>

Tags of the codes that have one: setLocale finds the new locale's here.

fallbackLocale

string required

translations

Record<string, Translations> required

currentRoute

string required

`@i18n-micro/astro/client/preact`

Components

`I18nProvider`

function I18nProvider(
  props: {
    children: ComponentChildren;
    value: I18nClientProps;
  },
): VNode<{}>

See I18nClientProps

Composables

`useAstroI18n`

function useAstroI18n(): { … }

`@i18n-micro/astro/client/react`

Components

`I18nProvider`

function I18nProvider(
  props: {
    children: ReactNode;
    value: I18nClientProps;
  },
): ReactElement<unknown, string | React.JSXElementConstructor<any>>

See I18nClientProps

Composables

`useAstroI18n`

function useAstroI18n(): { … }

`@i18n-micro/astro/client/svelte`

Composables

`useAstroI18n`

Hook for using i18n in Svelte components Use in the component's

function useAstroI18n(store: Writable<I18nState>): { … }

See I18nState

Functions

`createI18nStore`

Creates a Svelte store for i18n state. An island kept by transition:persist follows its new props with $: store.set(i18n) ($effect(() => store.set(i18n)) with runes).

function createI18nStore(props: I18nClientProps): Writable<I18nState>

See I18nClientProps · I18nState

`@i18n-micro/astro/client/vue`

Composables

`useAstroI18n`

Hook for using i18n in Vue components

function useAstroI18n(): { … }

Functions

`provideI18n`

Initializes the i18n provider for a Vue island. Call in the island's root component, with a getter (() => props.i18n) so an island kept by transition:persist follows its new props. shallowRef: translations are never edited in place, and deep tracking costs 11× on every t.

function provideI18n(props: MaybeRefOrGetter<I18nClientProps>): Ref<I18nState>

See I18nClientProps · I18nState

function onRequest(
  context: APIContext<Record<string, any>, Record<string, string | undefined>>,
  next: MiddlewareNext,
): void | Response | Promise<Response> | Promise<void>

function loadTranslationsFromDir(options: LoadTranslationsOptions): LoadedTranslations

See LoadTranslationsOptions · LoadedTranslations

`loadTranslationsIntoI18n`

Load a directory into an instance, replacing the chunks it finds.

function loadTranslationsIntoI18n(
  i18n: {
    addTranslations: (locale: string, translations: Translations, merge?: boolean) => void;
    addRouteTranslations: (locale: string, routeName: string, translations: Translations, merge?: boolean) => void;
    keepMessages?: (messages: Record<string, Translations>, routeMessages: Record<string, Record<string, Translations>>) => void;
  },
  options: LoadTranslationsOptions,
): void

See Translations · LoadTranslationsOptions

`readTranslationDir`

The directory's dictionaries and the files they came from, for the integration's build.

function readTranslationDir(
  options: { translationDir: string; rootDir: URL; disablePageLocales?: boolean; },
): { … }

messages

TranslationFileBuckets<Translations> required

files

string[] required

Types

`LoadedTranslations`

interface LoadedTranslations extends TranslationFileBuckets<Translations>

See TranslationFileBuckets · Translations

`LoadTranslationsOptions`

interface LoadTranslationsOptions

translationDir

string required

rootDir

string

disablePageLocales

boolean

Generated from the TypeScript sources and their JSDoc by pnpm run docs:generate. Back to all packages · Integration guides

Hooks

The i18n:register and i18n:beforeLocaleSwitch runtime hooks: add translations, and confirm, redirect or cancel a locale switch.

@i18n-micro/cli

Exported API of @i18n-micro/cli, generated from the source.