Add i18n features

In this recipe, you will learn how to use content collections and dynamic routing to build your own internationalization (i18n) solution and serve your content in different languages.

Tip

In v4.0, Astro added built-in support for i18n routing that allows you to configure default and supported languages and includes valuable helper functions to assist you in serving an international audience. If you want to use this instead, see our internationalization guide to learn about these features.

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

If you prefer the default language to not be visible in the URL unlike other languages, there are instructions to hide the default language below.

See the resources section for external links to related topics such as right-to-left (RTL) styling and choosing language tags.

Recipe

Section titled Recipe

Set up pages for each language

Section titled Set up pages for each language

1. Create a directory for each language you want to support. For example, en/ and fr/ if you are supporting English and French:

   • Foldersrc/

     • Folderpages/

       • Folderen/

         • about.astro
         • index.astro
       • Folderfr/

         • about.astro
         • index.astro
       • index.astro

2. Set up src/pages/index.astro to redirect to your default language.

   Statyczne

   src/pages/index.astro

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

   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.

   SSR

   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/');
   ---

Use collections for translated content

Section titled Use collections for translated content

1. 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:

   • Foldersrc/

     • Foldercontent/

       • Folderblog/

         • Folderen/ Blog posts in English

           • post-1.md
           • post-2.md
         • Folderfr/ Blog posts in French

           • post-1.md
           • post-2.md

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

   src/content.config.ts

   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.

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

   Statyczne

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

   src/pages/[lang]/blog/[...slug].astro

   ---
   import { getCollection, render } from 'astro:content';
   
   export async function getStaticPaths() {
     const pages = await getCollection('blog');
   
     const paths = pages.map(page => {
       const [lang, ...slug] = page.id.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 render(page);
   ---
   <h1>{page.data.title}</h1>
   <p>by {page.data.author} • {formattedDate}</p>
   <Content/>

   SSR

   In SSR mode, fetch the requested entry directly:

   src/pages/[lang]/blog/[...slug].astro

   ---
   import { getEntry, render } from 'astro:content';
   
   const { lang, slug } = Astro.params;
   const page = await getEntry('blog', `${lang}/${slug}`);
   
   if (!page) {
     return Astro.redirect('/404');
   }
   
   const formattedDate = page.data.date.toLocaleString(lang);
   const { Content, headings } = await render(page);
   ---
   <h1>{page.data.title}</h1>
   <p>by {page.data.author} • {formattedDate}</p>
   <Content/>

   Read more about dynamic routing.

   Date formatting

   The example above uses the built-in toLocaleString() date-formatting method to create a human-readable string from the frontmatter date. This ensures the date and time are formatted to match the user’s language.

Translate UI strings

Section titled 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.

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

   src/i18n/ui.ts

   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': 'Accueil',
       'nav.about': 'À propos',
     },
   } as const;

2. 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];
     }
   }

   Did you notice?

   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.

3. 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:

   src/components/Nav.astro

   ---
   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>

4. 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:

   src/layouts/Base.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 />
       </body>
   </html>

   Otomatik - 3.33.186.135 CloudFlare DNS Türk Telekom DNS Google DNS Open DNS

   OSZAR »

   ">