Fundamentals

LightNet lets you build websites in your community’s language and supports multiple languages, including right-to-left languages. Understanding LightNet’s internationalization model is useful even if your site supports only one language.

Two language layers

LightNet sites distinguish between two kinds of language. In many projects they are the same, but they serve different purposes:

• Site language: The language of the website interface, including button labels, menus, and page text.
• 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/en/about
• https://your.site/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.