Astro.locals.i18n reference

Astro.locals.i18n is added by LightNet middleware. It is available in Astro pages, layouts, and components, so you can read locale metadata and resolve translated text without extra imports.

Use this API when rendering localized UI in .astro files.

t

type: t(key, options?) => string

Translates a translation key using the current locale.

• Use t() for translation keys from src/translations/*.yml and LightNet’s built-in translation files.
• If no supported locale is resolved from the URL pathname, LightNet falls back to the configured default locale before translating.
• The options argument follows i18next conventions, including interpolation, plurals, and context.
• If a key is truly undefined, t() throws an error.

---
const { t } = Astro.locals.i18n
---
<h1>{t("ln.404.page-not-found")}</h1>

{Astro.locals.i18n.t("some.key", { count: 2 })}

Use t() for UI strings such as headings, button labels, and other text defined in translation files.

Note

LightNet uses i18next internally, so t() supports features such as plurals, interpolation, and context using i18next conventions.

Inline translation maps

These helpers resolve values that already contain localized text inline, for example:

{
  en: "Hello",
  de: "Hallo"
}

All inline-map helpers behave the same way once they receive the value:

• They first try currentLocale.
• If that value is missing, they fall back to defaultLocale.
• If neither locale has a value, they throw an error.
• They do not look up translation keys from translation files. Only t() does that.

The difference is how LightNet learns where the field came from:

Helper	Use it when	What you pass
tMap()	You need full manual control	translationMap and { path }
tConfigField()	The translation map comes from LightNet config	translationMap and the resolved config object
tContentField()	The translation map comes from a content entry	translationMap and the owning content entry

tConfigField

type: tConfigField(translationMap, config) => string

Resolves an inline translation map that belongs to LightNet config.

• Use tConfigField() for translated values read from the resolved runtime config, such as config.title, config.footerText, or configured language labels.
• tConfigField() is the preferred helper for config fields because it can derive the field path automatically.
• This gives LightNet better missing-translation errors without requiring you to write path manually.

---
const siteTitle = Astro.locals.i18n.tConfigField(config.title, config)
---
<title>{siteTitle}</title>

tContentField

type: tContentField(translationMap, contentEntry) => string

Resolves an inline translation map that belongs to a content entry.

• Use tContentField() for translated values stored inside content collections, such as category labels, media-type labels, or media-collection labels.
• tContentField() is the preferred helper for content fields because it can derive the field path from the owning entry.
• This keeps content code short while preserving precise error reporting.

---
const collectionLabel = Astro.locals.i18n.tContentField(
  collection.data.label,
  collection,
)
---
<h2>{collectionLabel}</h2>

tMap

type: tMap(translationMap, context) => string

Resolves an inline translation map when you want to provide the field context manually.

• Use tMap() when you already have the translation map but do not have the full config object or content entry available.
• context.path is required so LightNet can point error messages to the exact config or content field.
• In most app code, prefer tConfigField() or tContentField() instead of writing path by hand.

---
const siteTitle = Astro.locals.i18n.tMap(site.title, {
  path: ["pages", "index.astro"],
})
---
<title>{siteTitle}</title>

Use tMap() for advanced or manual cases. Use tConfigField() and tContentField() for everyday config and content reads.

Locale metadata

currentLocale

type: string

The current locale resolved from the URL pathname. LightNet checks the first locale segment in the pathname and falls back to defaultLocale when the pathname does not contain a supported locale.

defaultLocale

type: string

The configured default locale. This is the code of the language with isDefaultSiteLanguage: true.

locales

type: string[]

The configured list of supported locales. This is the codes of the languages with isSiteLanguage: true.

direction

type: "ltr" | "rtl"

The text direction for the current locale. LightNet resolves this from the language settings for currentLocale.

translationKeys

type: string[]

The list of all available translation keys.

Best practices

• Use t() for translation-file keys.
• Use tConfigField() for inline localized objects from LightNet config.
• Use tContentField() for inline localized objects from content entries.
• Use tMap() only when you need to provide the field path manually.
• Avoid hard-coded UI strings when a translation key should be used instead.
• Use currentLocale and direction in markup when building locale-aware or RTL-aware UI.