Astroサイトのローカライゼーション クイックガイド

Astroで多言語Webサイトを構築する場合、2つの異なる課題に対処する必要があります：言語別のコンテンツページの整理と、ボタンやナビゲーションなどのUI要素の翻訳です。本ガイドでは、基本的な設定から本番環境対応機能まで、Astroで静的および動的ローカライゼーションを設定する方法を詳しく説明します。

静的コンテンツ向けAstro i18nルーティングの設定

多言語サポートのためのastro.config.mjsの設定

まず、astro.config.mjsファイルでAstro組み込みのi18nルーティングを設定します。これにより、サポートする言語とURLの構造をAstroに指示できます：

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    routing: {
      prefixDefaultLocale: true // 英語URLに/en/を使用
    }
  }
});

prefixDefaultLocale: trueを設定することで、すべての言語で一貫したURLパターン（/en/about、/es/about）を使用でき、リンク管理が容易になり、後のルーティング競合を回避できます。

ローカライズされたフォルダー構造の作成

src/pages/内にロケール固有のフォルダーを作成してページを整理します：

src/pages/
  en/
    index.astro
    about.astro
  es/
    index.astro
    about.astro
  fr/
    index.astro
    about.astro

各フォルダーは設定で定義されたロケールに対応します。Astroはこの構造に基づいて自動的に正しいルートを生成します。

Astroでの静的および動的ローカライゼーションの管理

ロケール別のコンテンツコレクションの整理

ブログ投稿、ドキュメント、またはその他のコンテンツコレクションについては、同じロケール構造を反映させます：

src/content/
  blog/
    en/
      first-post.md
    es/
      first-post.md
    fr/
      first-post.md

コンテンツをクエリする際は、現在のロケールでフィルタリングします：

import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ id }) => {
  return id.startsWith(Astro.currentLocale + '/');
});

[locale]フォルダーを使用した動的ルートの実装

各言語でページファイルを重複させる代わりに、動的ルートを使用します。[locale]フォルダーを作成します：

src/pages/
  [locale]/
    index.astro
    about.astro
    blog/
      [slug].astro

ページ内でgetStaticPaths()を使用して、すべてのロケールのルートを生成します：

export function getStaticPaths() {
  return [
    { params: { locale: 'en' } },
    { params: { locale: 'es' } },
    { params: { locale: 'fr' } }
  ];
}

Paraglideを使用した動的UI文字列の処理

AstroでのParaglideのインストールと設定

Astroがページルーティングを処理する一方で、UIテキストには別のソリューションが必要です。Paraglideは優れたTypeScriptサポートと最小限のバンドルサイズを提供します：

npm install @inlang/paraglide-js @inlang/paraglide-astro
npx @inlang/paraglide-js init

翻訳ファイルとメッセージキーの作成

プロジェクトルートのmessages/に翻訳を保存します：

// messages/en.json
{
  "nav.home": "Home",
  "nav.about": "About",
  "button.readMore": "Read more"
}

// messages/es.json
{
  "nav.home": "Inicio",
  "nav.about": "Acerca de",
  "button.readMore": "Leer más"
}

コンポーネント内で翻訳をインポートして使用します：

---
import * as m from '../paraglide/messages.js';
---

<nav>
  <a href={`/${Astro.currentLocale}`}>{m.nav_home()}</a>
  <a href={`/${Astro.currentLocale}/about`}>{m.nav_about()}</a>
</nav>

言語切り替えとナビゲーションの構築

クリーンなURLのためのgetRelativeLocaleUrl()の使用

Astroは適切なローカライズされたURLを生成するヘルパー関数を提供します。手動の文字列結合の代わりに、常にgetRelativeLocaleUrl()を使用してください：

import { getRelativeLocaleUrl } from 'astro:i18n';

const aboutUrl = getRelativeLocaleUrl(Astro.currentLocale, 'about');
const blogUrl = getRelativeLocaleUrl(Astro.currentLocale, 'blog/my-post');

言語切り替えコンポーネントを作成します：

---
import { getRelativeLocaleUrlList } from 'astro:i18n';

const localeUrls = getRelativeLocaleUrlList();
---

<select onchange="window.location.href = this.value">
  {localeUrls.map(url => {
    const locale = url.split('/')[1];
    return (
      <option value={url} selected={Astro.currentLocale === locale}>
        {locale.toUpperCase()}
      </option>
    );
  })}
</select>

二重プレフィックスルートなどの一般的な落とし穴の回避

以下の一般的なミスに注意してください：

1. 二重プレフィックス：動的ルートを使用する際は、/en/blog/en/my-postのようなURLを避けるためにスラッグをクリーンアップします：

const cleanSlug = post.slug.replace(`${locale}/`, '');

2. ハードコードされたロケールパス：文字列結合の代わりに、常にAstroのi18nヘルパーを使用
3. リンクでのロケール不足：すべての内部リンクには適切なローカライゼーションが必要

高度なAstro i18n機能

フォールバック言語の設定

未翻訳コンテンツのフォールバックを設定します：

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    fallback: {
      es: 'en',
      fr: 'en'
    },
    routing: {
      fallbackType: 'rewrite' // リダイレクトせずにフォールバックコンテンツを表示
    }
  }
});

本番環境でのドメインマッピングの設定

言語ごとに別々のドメインを持つ本番サイトの場合：

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    domains: {
      fr: 'https://fr.example.com',
      es: 'https://example.es'
    }
  }
});

これには@astrojs/nodeまたは@astrojs/vercelアダプターでのサーバーサイドレンダリングが必要です。

まとめ

Astroサイトのローカライゼーションは、2つのアプローチを組み合わせます：静的コンテンツ整理のための組み込みi18nルーティングと、動的UI文字列のためのParaglideなどの外部ライブラリです。フォルダー構造とルーティング設定から始めて、翻訳管理を重ねていきます。一般的なルーティング問題を避けるためにAstroのURLヘルパーを使用し、本番デプロイメントではフォールバックとドメインマッピングを検討することを忘れないでください。

よくある質問

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.