Internationalization

LightNet comes with full support for internationalization (i18n). This allows you to create a multilingual site with ease. This guide will show you how to set up a new language, translate LightNet into a new language, and translate your own UI strings.

Add a new UI language

Follow this steps to add a new UI language to your LightNet site:

1. Add translations file: Create a new file in the src/translations folder. The file must be named with the language code (e.g. de.yml for German). The content of the file should look like this:

   src/translations/de.yml

   # Your description of the translation.
   x.hello-world: Hallo Welt

   The left side of the colon is the key and the right side is the translation value. You may add a description by starting the line with #.
2. Translate LightNet strings: Some languages are built-in to LightNet. This languages are maintained by the community. So it might be there is missing translation. If your language is not built-in add LightNet translations to the new file. All required keys can be found here. Translate the keys to your new language. If you choose a built-in language your translations will override the internal translations. Please consider sharing your LightNet translations with the community.
3. Translate your own UI strings: Add your own UI strings to the file. More details on custom UI strings can be found below.
4. Add to config: Add the new language to the languages array in your astro.config.mjs file.

   astro.config.mjs

   export default defineConfig({
       integrations: [
           lightnet({
               languages: [
                   {
                       // Language code must match the translation
                       // file name. For example "de.yml" has the code "de"
                       code: "de",
                       // Display name for the language selector.
                       label: "Deutsch",
                       // Use this as an user interface language
                       isUILanguage: true
                   },
               ],
           }),
       ],
   })

5. Set default language (Optional): Inside astro.config.mjs set the new language as the default language by setting isDefaultUILanguage: true in the language config object.
6. Validate: Run the development server with npm run dev and check if the new language is available in the language selector. Select the new language and check if the translations are working as expected.

Use custom UI strings

LightNet allows you to add custom UI strings to your site. This is useful if you want to add custom text to your site that is not part of LightNet. Custom strings can be used for example to add custom text to the navigation or to add a text to the homepage. Follow this steps to add custom UI strings to your LightNet site:

1. Use your translations file from the previous chapter to add the custom UI string as a key-value pair. For example this is how you would add a custom string to the English translations file:

   src/translations/en.yml

   x.hello-world: Hello World
   x.my-custom-string: My custom text

   Choose a unique key (left side of the colon) for your custom string. By convention all your keys should be prefixed with x.. LightNet’s internal keys are prefixed with ln.. This helps to avoid naming collisions and will improve the validation of your keys. The key will be used to referenced your custom string in your site. We recommend to use English keys for your custom strings.
2. Add the translation for your custom string to the other translations files. This is important if you want to support multiple languages.

   src/translations/de.yml

    x.hello-world: Hallo Welt
    x.my-custom-string: Mein eigener Text

   Caution

   Notice how the key is the same in all translations files. Keys must not be translated. Only the values should be translated.

3. Use the custom string in your site. We provide a translation function with Astro.locals.i18n.t. You can use this function to get the translation of your custom string.

   src/pages/[locale]/index.astro

   ---
   export { getLocalePaths as getStaticPaths } from "lightnet/i18n"
   import { Page } from "lightnet/components"
   ---
   <Page>
       <h1>{Astro.locals.i18n.t("x.my-custom-string")}</h1>
   </Page>

   The translation function will return the translation of the key my-custom-string in the current language. If the key is not found in the translations file, the function will return the value of the default translations file. If the key is not found in the default translations file, the function will throw an Error.

   Tip

   We provide internationalization helpers with the Astro.locals.i18n object. This object will additionally give you access to all locales the defaultLocale and more. You can access the i18n object inside all your .astro files.

   Some config options require you to pass the translation key instead of the translated string. For example the title property in the astro.config.mjs file. Check the config reference to see where a translation key is required.

How translations are resolved

1. User translations are merged with built-in translations. User translations will override built-in translations.
2. Lookup translation key in exactly matching translation file
3. Lookup translation key in base language. E.g. for en_US this will use en to resolve the key.
4. Lookup translation key in fallbackLanguages defined for this language. Starting from first item. Stopping on first match.
5. Lookup translation key in default user-interface language.
6. Lookup translation key in english translations
7. Return key if nothing is found. If key starts with ln. or x. throw an error.

Share your translations

explain how to share translations.