国際化ガイド

機能概要

• スマートリダイレクト：Cookie またはブラウザの言語設定に基づいて、対応する言語のトップページへ自動的にリダイレクトします。
• Props 不要のコンテキスト注入：ts-intl-astro を採用し、Astro コンポーネント間で lang をバケツリレーすることなく、直接 useTranslations や useLocale を利用できます。
• 多言語記事の自動リンク：サブディレクトリを作成することなく、Frontmatter の translationKey で各言語の記事を関連付け、適切な SEO タグ（canonical / hreflang）を自動生成します。

ファイル構成

翻訳関数の使い方

本プロジェクトの国際化は ts-intl-astro （新しいタブで開く） を採用しており、Astro コンポーネントツリーに現在のロケールコンテキストを自動注入します。

基本的な使い方（名前空間のバインド）

コンポーネントで名前空間を指定して初期化すると、キー名を指定するだけで翻訳を取得できます：

---
import { useTranslations } from "~/i18n";

// `common` 名前空間をバインド
const t = useTranslations("common");
---

<header>
  <h1>{t("header_title")}</h1>
  <a href="/">{t("home")}</a>
</header>

グローバル名前空間アクセス

引数なしで useTranslations を呼び出すと、ドット記法（namespace.key）で任意のエントリを取得できます：

---
import { useTranslations } from "~/i18n";

const t = useTranslations();
---

<p>{t("common.home")}</p>
<p>{t("search.placeholder")}</p>

現在の言語コードの取得

多言語 URL の組み立てや外部コンポーネントへの受け渡しには、useLocale() を使用します：

---
import { useLocale } from "~/i18n";

const lang = useLocale();
---

<a href={`/${lang}/about`}>概要</a>

パラメータの補間

辞書内の {param} プレースホルダーに対応する値をオブジェクトで渡します：

---
import { useTranslations } from "~/i18n";

const t = useTranslations("common");
// 辞書定義: link_to: "{title}へのリンク"
---

<p>{t("link_to", { title: "Astro" })}</p>
{/* 出力: Astroへのリンク */}

コンポーネント外での呼び出し

API エンドポイント（rss.xml.ts）や静的パス生成（getStaticPaths）など、Astro コンテキストが存在しない環境では、言語コードを明示的に指定する getTranslations を使用します：

import { getTranslations } from "~/i18n";

const t = getTranslations("ja-JP", "common");
const siteTitle = t("site_title");

新しい言語の追加

サイトに新しい言語（例：フランス語 fr-FR）を追加する手順は以下の 4 ステップです：

1. サイト設定に言語マッピングを追加

   site.config.ts の languageNameMap に新しい言語コードと表示名を追加します：

   const SiteConfig = {
     // ...
     languageNameMap: {
       "en-US": "English",
       "ja-JP": "日本語",
       "zh-Hans": "简体中文",
       "fr-FR": "Français",
     },
   };

2. 翻訳辞書ファイルを作成

   i18n/messages/ 配下に fr-FR.ts を新規作成します。既存のファイルを複製して書き換えることを推奨します：

   const frFR = {
     common: {
       home: "Accueil",
       about: "À propos",
       link_to: "Lien vers {title}",
       page_num: "Page {num}",
       // ... その他のキー
     },
   } as const;
   
   export default frFR;

3. 新しい辞書を登録

   i18n/index.ts で辞書をインポートし、createAstroI18n に登録します：

   import zhHans from "./messages/zh-Hans";
   import enUS from "./messages/en-US";
   import jaJP from "./messages/ja-JP";
   import frFR from "./messages/fr-FR";
   
   export const {
     useTranslations,
     useLocale,
     useFormatter,
     getTranslations,
     // ...
   } = createAstroI18n({
     defaultLanguage: "zh-Hans",
     messages: {
       "zh-Hans": zhHans,
       "en-US": enUS,
       "ja-JP": jaJP,
       "fr-FR": frFR,
     },
   });

4. 著者情報とヒーローコンテンツを追加

   src/content/author/ および src/content/mdx/ 配下にディレクトリとファイルを作成します：

   • src/content/author/fr-FR/default.mdx
   • src/content/mdx/fr-FR/hero.mdx

多言語記事の執筆

すべてのブログ記事は言語ごとのサブディレクトリを作らず、src/content/blog/ に直接配置します。Frontmatter の translationKey に基づき、各言語バージョンが自動的に関連付けられます：

---
title: "Astro Plain 介绍"
summary: "博客模板介绍"
translationKey: "my-first-post"
language: "zh-Hans"
date: "2026-09-01T12:00:00Z"
isCanonical: true
---
文章中文内容...

---
title: "Introducing Astro Plain"
summary: "Introduction to the blog template"
translationKey: "my-first-post"
language: "en-US"
date: "2026-09-01T12:00:00Z"
isCanonical: false
---
Post content in English...