Fundamentals

LightNet provides internationalization features for configuring the languages supported by a LightNet Site. A Site Administrator configures one or more Site Languages for the user interface, including right-to-left languages, while each Media Item has its own Content Language. This distinction matters even when a site supports only one language.

Two language layers

LightNet uses two language layers, each with a different purpose:

• Site language: The language of the user interface, including button labels, menus, and other user interface elements.
• Content language: The language of a media item itself. For example, an English video has an English title and description.

Languages are configured with languages in astro.config.mjs. Each language entry includes the language code, its display label, and optional site-language flags.

Configure site languages

This example configures English as the default site language and German as an additional locale:

astro.config.mjs

import lightnet from "lightnet";
import { defineConfig } from "astro/config";

export default defineConfig({
  integrations: [
    lightnet({
      languages: [
        {
          code: "en",
          label: {
            en: "English",
            de: "Englisch"
          },
          isDefaultSiteLanguage: true
        },
        {
          code: "de",
          label: {
            en: "German",
            de: "Deutsch"
          },
          isSiteLanguage: true
        }
      ],
    }),
  ],
});

For step-by-step and reference details, see:

• Add a site language
• Configuration reference

Route localization

Every page of a LightNet site is available in all configured site languages. Routes are localized by prefixing the path with the configured locale code.

For example:

• https://your-site.example/en/about
• https://your-site.example/de/about

Translation files and keys

LightNet uses translation keys that resolve to translated values based on the current locale. Translation files live in src/translations/, with one file per site language named [language-code].yml.

For example:

src/translations/en.yml

# Optional description...
homepage.title: Welcome to my page!

You can use a translation key inside an Astro component like this:

MyComponent.astro

<h1>{Astro.locals.i18n.t("homepage.title")}</h1>

The Astro.locals.i18n.t(...) helper is available in all Astro files. It resolves the key using the current locale derived from the page URL. For the full API, including locale metadata and tMap(...) for inline locale maps, see Astro.locals.i18n reference.

Caution

Enclose translation values in quotes if they contain special characters, such as :, #, or -.

• The translation key is on the left, and the translation value is on the right.
• Use periods (.) in keys to add context (e.g., homepage.title).

LightNet uses the same mechanism for built-in strings, for example the search page title (ln.search.title). All built-in keys are defined in the English translation file on GitHub. Additional locale files in that folder are maintained by the community, and contributions are welcome.

By convention, LightNet’s built-in translation keys start with ln.. Your own project keys can use any other prefix, or no prefix at all, for example homepage.title.

Translation resolution order

LightNet resolves translation keys in the following order:

1. Merge custom and built-in translations, with project translations taking precedence.
2. Check the translation file for the exact current locale.
3. Fallback to the base language (e.g., en for en_US).
4. Use any fallbackLanguages defined for the current language in languages.
5. Fallback to the default site language.
6. Lastly, fallback to English translations.
7. If unresolved, t(...) throws an error because string inputs are treated strictly as translation keys.