Add i18n features

Astro doesn’t have built-in internationalization (i18n) support, but you can build your own i18n solution. In this recipe, you’ll learn how to use content collections and dynamic routing to serve content for different languages.

This example serves each language at its own subpath, e.g. example.com/en/blog for English and example.com/fr/blog for French.

Recipe

Set up pages for each language

Create a directory for each language you want to support. For example, en/ and fr/ if you are supporting English and French:
- ディレクトリsrc/
  - ディレクトリpages/
    ディレクトリen/
    about.astro
    index.astro
    ディレクトリfr/
    about.astro
    index.astro
    index.astro
Set up src/pages/index.astro to redirect to your default language.
src/pages/index.astro

--- --- <meta http-equiv="refresh" content="0;url=/en/" />

Copied!

This approach uses a meta refresh and will work however you deploy your site. Some static hosts also let you configure server redirects with a custom configuration file. See your deploy platform’s documentation for more details.
If you are using an SSR adapter, you can use Astro.redirect to redirect to the default language on the server.

src/pages/index.astro

--- return Astro.redirect('/en/'); ---

Copied!

Use collections for translated content

Create a folder in src/content/ for each type of content you want to include and add subdirectories for each supported language. For example, to support English and French blog posts:
- ディレクトリsrc/
  - ディレクトリcontent/
    ディレクトリblog/
    ディレクトリen/ Blog posts in English
    post-1.md
    post-2.md
    ディレクトリfr/ Blog posts in French
    post-1.md
    post-2.md

Create a src/content/config.ts file and export a collection for each type of content.

import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    author: z.string(),
    date: z.date()
  })
});

export const collections = {
  'blog': blogCollection
};

📚 Read more about Content Collections.

Use dynamic routes to fetch and render content based on a lang and a slug parameter.

In static rendering mode, use getStaticPaths to map each content entry to a page:

---
import { getCollection } from 'astro:content'

export async function getStaticPaths() {
  const pages = await getCollection('blog')

  const paths = pages.map(page => {
    const [lang, ...slug] = page.slug.split('/');
    return { params: { lang, slug: slug.join('/') || undefined }, props: page }
  })

  return paths;
}

const { lang, slug } = Astro.params;
const page = Astro.props;
const formattedDate = page.data.date.toLocaleString(lang);

const { Content } = await page.render();
---
<h1>{page.data.title}</h1>
<p>by {page.data.author} • {formattedDate}</p>
<Content/>

In SSR mode, fetch the requested entry directly:

---
import { getEntryBySlug } from 'astro:content';

const { lang, slug } = Astro.params;
const page = await getEntryBySlug('blog', `${lang}/${slug}`);

if (!page) {
  return Astro.redirect('/404');
}

const formattedDate = page.data.date.toLocaleString(lang);
const { Content, headings } = await page.render();
---
<h1>{page.data.title}</h1>
<p>by {page.data.author} • {formattedDate}</p>
<Content/>

📚 Read more about dynamic routing.

Translate UI strings

Create dictionaries of terms to translate the labels for UI elements around your site. This allows your visitors to experience your site fully in their language.

Create a src/i18n/ui.ts file to store your translation strings:

export const languages = {
  en: 'English',
  fr: 'Français',
};

export const defaultLang = 'en';

export const ui = {
  en: {
    'nav.home': 'Home',
    'nav.about': 'About',
    'nav.twitter': 'Twitter',
  },
  fr: {
    'nav.home': 'Acceuil',
    'nav.about': 'À propos',
  },
} as const;

Create two helper functions: one to detect the page language based on the current URL, and one to get translations strings for different parts of the UI in src/i18n/utils.ts:
src/i18n/utils.ts
```
import { ui, defaultLang } from './ui';

export function getLangFromUrl(url: URL) {
  const [, lang] = url.pathname.split('/');
  if (lang in ui) return lang as keyof typeof ui;
  return defaultLang;
}

export function useTranslations(lang: keyof typeof ui) {
  return function t(key: keyof typeof ui[typeof defaultLang]) {
    return ui[lang][key] || ui[defaultLang][key];
  }
}
```
Copied!
In step 1, the nav.twitter string was not translated to French. You may not want every term translated, such as proper names or common industry terms. The useTranslations helper will return the default language’s value if a key is not translated. In this example, French users will also see “Twitter” in the nav bar.

Import the helpers where needed and use them to choose the UI string that corresponds to the current language. For example, a nav component might look like:

---
import { getLangFromUrl, useTranslations } from '../i18n/utils';

const lang = getLangFromUrl(Astro.url);
const t = useTranslations(lang);
---
<ul>
    <li>
        <a href={`/${lang}/home/`}>
          {t('nav.home')}
        </a>
    </li>
    <li>
        <a href={`/${lang}/about/`}>
          {t('nav.about')}
        </a>
    </li>
    <li>
        <a href="https://twitter.com/astrodotbuild">
          {t('nav.twitter')}
        </a>
    </li>
</ul>

Each page must have a lang attribute on the <html> element that matches the language on the page. In this example, a reusable layout extracts the language from the current route:

---
import { getLangFromUrl } from '../i18n/utils';

const lang = getLangFromUrl(Astro.url);
---
<html lang={lang}>
    <head>
        <meta charset="utf-8" />
        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
        <meta name="viewport" content="width=device-width" />
        <title>Astro</title>
    </head>
    <body>
        <slot />
    </body>
</html>

You can then use this base layout to ensure that pages use the correct lang attribute automatically.

---
import Base from "../../layouts/Base.astro"
---
<Base>
    <h1>About me</h1>
    ...
</Base>

Let users switch between languages

Create links to the different languages you support so users can choose the language they want to read your site in.

Create a component to show a link for each language:

---
import { languages } from '../i18n/ui';
---
<ul>
  {Object.entries(languages).map(([lang, label]) => (
    <li>
      <a href={`/${lang}/`}>{label}</a>
    </li>
  ))}
</ul>

Add <LanguagePicker /> to your site so it is shown on every page. The example below adds it to the site footer in a base layout:

---
import LanguagePicker from '../components/LanguagePicker.astro';
import { getLangFromUrl } from '../i18n/utils';

const lang = getLangFromUrl(Astro.url);
---
<html lang={lang}>
    <head>
        <meta charset="utf-8" />
        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
        <meta name="viewport" content="width=device-width" />
        <title>Astro</title>
    </head>
    <body>
        <slot />
        <footer>
          <LanguagePicker />
        </footer>
    </body>
</html>

Resources

Community libraries

astro-i18next — An Astro integration for i18next including some utility components.
astro-i18n — A TypeScript-first internationalization library for Astro.

その他のレシピ

Share State Between Islands

Learn how to share state across components — and frameworks! — with Nano Stores.
RSS

AstroのRSS入門
Installing a Vite or Rollup plugin

Learn how you can import YAML data by adding a Rollup plugin to your project.
Build Forms With API Routes

Learn how to use JavaScript to send form submissions to an API Route
Build HTML Forms in Astro Pages

Learn how to build HTML forms and handle submissions in your frontmatter
Use Bun with Astro

Learn how to use Bun with your Astro site.
Verify a Captcha

Learn how to create an API route and fetch it from the client.
Build your Astro Site with Docker

Learn how to build your Astro site using Docker.
Add icons to external links

Learn how to install a rehype plugin to add icons to external links in your Markdown files
Add i18n features

Use dynamic routing and content collections to add internationalization support to your Astro site.
Add Reading Time

Build a remark plugin to add reading time to your Markdown or MDX files.

どんなことを？

どんなことを？

Add i18n features

Recipe

Set up pages for each language

Use collections for translated content

Translate UI strings

Let users switch between languages

Resources

Community libraries

その他のレシピ

Share State Between Islands

RSS

Installing a Vite or Rollup plugin

Build Forms With API Routes

Build HTML Forms in Astro Pages

Use Bun with Astro

Verify a Captcha

Build your Astro Site with Docker

Add icons to external links

Add i18n features

Add Reading Time