Other Features

Components

Inside src/components/i18n/, you will find several UI components that are useful for generating multilingual sites. Feel free to customize their content and import them as needed.

LocaleSelect.astro

A select UI for switching between languages.

LocaleSelectSingle.astro

A link UI to another language. Use this when you only support two languages.

LocalesHomeList.astro

Returns a list of links to the top pages of each language, wrapped in <li> tags.

LocaleSuggest.astro

Displays a UI at the top suggesting a link to the browser’s language when the user accesses a URL different from their browser’s language.

For example, if a user with English settings accesses the URL /ja/[slug], it suggests a link to /en/[slug].

Once closed, the setting is saved on localhost and will not be displayed again.

LocaleHtmlHead.astro

Allows you to specify <head> tag settings for each locale. The sample code loads the Noto Font for each language and applies the CSS.

NotTranslateCaution.astro

Displays a warning to the user when a specific page is only available in a certain language.

The sample page is Monolingual. When this page is viewed in a language other than English, it displays a warning UI to the user.

The text for the warning UI is set in /src/const.ts in the sample code.

404

The Astro i18n Starter 404 page consists of two files. If you want to customize the design of the 404 page, you generally only need to edit src/pages/[lang]/404.astro.

src/pages/404.astro

This file generates the following:

/404.html

Most deploy services will find and use this file when a page is not found.

When accessed with Astro i18n Starter, it redirects to the following 404 page based on the user’s system language:

Detailed Redirect Conditions

The redirect is performed based on the following conditions. For more details, please refer to the source code.

If the URL contains /ja/... or any other language code.
If the localStorage.selectedLang contains the language code.
- The localStorage.selectedLang is saved when the user selects a language in the UI.
If the referring page contains /ja/... or any other language code.

src/pages/[lang]/404.astro

This file dynamically generates the following:

/en/404/index.html

/ja/404/index.html

…

Actually, by history.replaceState() process displays the URL the user accessed before the redirect in the browser

CSS Tips

Separating CSS for each language

You can separate the definitions using CSS alone by writing as follows:

:lang(en) {
    /* Styles for English */
}
:lang(ar) {
    /* Styles for Arabic */
}

However, in this case, all language CSS will be loaded simultaneously, resulting in wasted resources.

If you are writing inside .astro files, consider writing as follows or separating the definitions within LocaleHtmlHead.astro.

---
import { type Lang } from "@/i18n";
const locale = Astro.currentLocale as Lang;
---

{
    locale === "en" ? (
        <style>
            /* Styles for English */
        </style>
    )
    : locale === "ar" ? (
        <style>
            /* Styles for Arabic */
        </style>
    )
    : null
}

Letter-spacing for Arabic

In some designs, you may want to adjust the letter-spacing for headings and other elements. However, it is important not to add spacing for Arabic text.

Right-to-left Styling

Therefore, please note that Astro i18n Starter defines the following in src/styles/base.css:

:lang(ar) {
    * { letter-spacing: 0 !important; }
}

RTL Icons

In RTL languages, icons such as arrows need to be mirrored.

Right to left | Apple Developer Documentation

Astro i18n Starter uses Material Icon, and the following is defined in src/styles/base.css:

[class^="material-icons"]:dir(rtl).dir {
    scale: -1 1;
}

By adding the .dir class, the icons will be mirrored in RTL languages.

<span class="material-icons-sharp dir">arrow_forward</span>

Actual display: arrow_forward open_in_new