@intlayer/docs 8.7.7 → 8.7.8-canary.0

package/docs/ja/intlayer_with_astro_lit.md

@@ -0,0 +1,618 @@
+---
+createdAt: 2026-04-24
+updatedAt: 2026-04-24
+title: Astro + Lit i18n - 2026年にAstro + Litアプリケーションを翻訳する方法
+description: Intlayerを使用してAstro + Litサイトに国際化（i18n）を追加する方法を学びます。このガイドに従って、サイトを多言語化しましょう。
+keywords:
+  - 国際化
+  - ドキュメント
+  - Intlayer
+  - Astro
+  - Lit
+  - ウェブコンポーネント
+  - i18n
+  - JavaScript
+slugs:
+  - doc
+  - environment
+  - astro
+  - lit
+applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
+applicationShowcase: https://intlayer-astro-template.vercel.app
+history:
+  - version: 8.7.7
+    date: 2026-04-24
+    changes: "Astro + Litの初期ドキュメント"
+---
+
+# Intlayerを使用したAstro + Litサイトの翻訳 | 国際化 (i18n)
+
+<Tabs defaultTab="code">
+  <Tab label="コード" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-astro-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Intlayerを使用してアプリケーションを国際化する方法"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+  <Tab label="デモ" value="demo">
+
+<iframe
+  src="https://intlayer-astro-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="デモ — intlayer-astro-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+## 目次
+
+<TOC/>
+
+## Intlayerとは？
+
+**Intlayer**は、現代的なウェブアプリケーションでの多言語サポートを簡素化するために設計された、革新的でオープンソースの国際化 (i18n) ライブラリです。
+
+Intlayerを使用すると、以下のことが可能になります：
+
+- **翻訳の管理が容易**：コンポーネントレベルの宣言型辞書を使用します。
+- **動的なローカライズ**：メタデータ、ルート、コンテンツを動的にローカライズできます。
+- **TypeScriptサポート**：自動生成された型により、オートコンプリートやエラー検出が向上します。
+- **高度な機能**：動的なロケール検出や切り替えなどの機能を利用できます。
+
+---
+
+## Astro + LitへのIntlayer設定ステップバイステップガイド
+
+GitHubで[アプリケーションテンプレート](https://github.com/aymericzip/intlayer-astro-template)を表示。
+
+### ステップ1: 依存関係のインストール
+
+お好みのパッケージマネージャーを使用して、必要なパッケージをインストールします：
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer lit lit-intlayer @astrojs/lit
+
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
+
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
+
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
+
+bun x intlayer init
+```
+
+- **intlayer**
+  設定管理、翻訳、[コンテンツ宣言](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dictionary/content_file.md)、トランスパイル、および[CLIコマンド](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/index.md)のための国際化ツールを提供するコアパッケージ。
+
+- **astro-intlayer**
+  Intlayerを[Viteバンドラー](https://vite.dev/guide/why.html#why-bundle-for-production)と統合するためのAstro統合プラグイン、およびユーザーの優先ロケールの検出、クッキーの管理、URLリダイレクトの処理を行うミドルウェアが含まれています。
+
+- **lit**
+  高速で軽量なウェブコンポーネントを構築するためのコアLitパッケージ。
+
+- **lit-intlayer**
+  IntlayerをLitアプリケーションと統合するパッケージ。言語変更時にLitElementを自動的に再レンダリングするための `ReactiveController` ベースのフック（`useIntlayer`、`useLocale` など）を提供します。
+
+- **@astrojs/lit**
+  Astroページ内でLitカスタム要素の使用を可能にする公式のAstro統合。
+
+### ステップ2: プロジェクトの設定
+
+アプリケーションの言語を設定するための設定ファイルを作成します：
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // その他のロケール
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+> この設定ファイルを使用して、ローカライズされたURL、ミドルウェアのリダイレクト、クッキー名、コンテンツ宣言の場所と拡張子、コンソールでのIntlayerログの無効化などを設定できます。利用可能なパラメータの全リストについては、[設定ドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)を参照してください。
+
+### ステップ3: Astro設定へのIntlayerの統合
+
+Astroの設定にintlayerプラグインとLit統合を追加します。
+
+```typescript fileName="astro.config.ts"
+// @ts-check
+
+import { intlayer } from "astro-intlayer";
+import lit from "@astrojs/lit";
+import { defineConfig } from "astro/config";
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [intlayer(), lit()],
+});
+```
+
+> Astro統合プラグイン `intlayer()` は、IntlayerをAstroと統合するために使用されます。コンテンツ宣言ファイルの構築を確実にし、開発モードで監視します。Astroアプリケーション内でIntlayerの環境変数を定義し、パフォーマンス最適化のためのエイリアスを提供します。
+
+> `lit()` 統合により、Astroページ内でLitカスタム要素を使用できるようになります。
+
+### ステップ4: コンテンツの宣言
+
+翻訳を保存するためのコンテンツ宣言を作成・管理します：
+
+```typescript fileName="src/components/lit/app.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const litDemoContent = {
+  key: "lit-demo",
+  content: {
+    greeting: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola mundo",
+      ja: "こんにちは世界",
+    }),
+    description: t({
+      en: "Welcome to my multilingual Astro + Lit site.",
+      fr: "Bienvenue sur mon site Astro + Lit multilingue.",
+      es: "Bienvenido a mi sitio Astro + Lit multilingüe.",
+      ja: "多言語対応のAstro + Litサイトへようこそ。",
+    }),
+  },
+} satisfies Dictionary;
+
+export default litDemoContent;
+```
+
+> コンテンツ宣言は、`contentDir`（デフォルトは `./src`）に含まれ、コンテンツ宣言ファイルの拡張子（デフォルトは `.content.{json,ts,tsx,js,jsx,mjs,cjs}`）と一致していれば、アプリケーション内のどこにでも定義できます。
+
+> 詳細については、[コンテンツ宣言のドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dictionary/content_file.md)を参照してください。
+
+### ステップ5: Astroでのコンテンツの使用
+
+`intlayer`からエクスポートされたコアヘルパーを使用して、`.astro`ファイル内で直接辞書を消費できます。また、各ページにhreflangや正規リンクなどのSEOメタデータを追加する必要があります。Litカスタム要素はクライアントサイドの `<script>` を通じてインポートされ、bodyに配置されます。
+
+```astro fileName="src/pages/[...locale]/index.astro"
+---
+import {
+  getIntlayer,
+  getLocaleFromPath,
+  getLocalizedUrl,
+  getPrefix,
+  localeMap,
+  defaultLocale,
+  type LocalesValues,
+} from "intlayer";
+
+export const getStaticPaths = () => {
+  return localeMap(({ locale }) => ({
+    params: { locale: getPrefix(locale).localePrefix },
+  }));
+};
+
+const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+const { greeting } = getIntlayer("lit-demo", locale);
+---
+
+<!doctype html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>{greeting}</title>
+
+    <!-- 正規リンク -->
+    <link
+      rel="canonical"
+      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
+    />
+
+    <!-- Hreflangリンク -->
+    {
+      localeMap(({ locale: mapLocale }) => (
+        <link
+          rel="alternate"
+          hreflang={mapLocale}
+          href={new URL(
+            getLocalizedUrl(Astro.url.pathname, mapLocale),
+            Astro.site
+          )}
+        />
+      ))
+    }
+
+    <link
+      rel="alternate"
+      hreflang="x-default"
+      href={new URL(
+        getLocalizedUrl(Astro.url.pathname, defaultLocale),
+        Astro.site
+      )}
+    />
+  </head>
+  <body>
+    <!-- Litカスタム要素 — サーバーで検出されたロケールをプロパティとして受け取ります -->
+    <lit-demo locale={locale}></lit-demo>
+  </body>
+</html>
+
+<script>
+  import "../../components/lit/LitDemo";
+</script>
+```
+
+> **ルーティング設定に関する注意:**
+> 使用するディレクトリ構造は、`intlayer.config.ts` の `middleware.routing` 設定によります：
+>
+> - **`prefix-no-default`（デフォルト）:** ルート（プレフィックスなし）にデフォルト言語を保持し、他の言語にはプレフィックスを付けます。すべてのケースをキャッチするために `[...locale]` を使用します。
+> - **`prefix-all`:** すべてのURLに言語プレフィックスが付きます。ルートを個別に処理する必要がない場合は、標準の `[locale]` を使用できます。
+> - **`search-param` または `no-prefix`:** ロケールフォルダは不要です。ロケールは検索パラメータまたはクッキーを通じて処理されます。
+
+### ステップ6: Litカスタム要素の作成
+
+Litカスタム要素を作成します。クライアントサイドでIntlayerシングルトンを初期化するために、サーバーによって検出された `locale` プロパティを使用して `connectedCallback` で `installIntlayer` を呼び出します。
+
+```typescript fileName="src/components/lit/LitDemo.ts"
+import { LitElement, html } from "lit";
+import { installIntlayer, useIntlayer, useLocale } from "lit-intlayer";
+import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
+
+class LitDemo extends LitElement {
+  static properties = {
+    locale: { type: String },
+  };
+
+  locale: LocalesValues = "en" as LocalesValues;
+
+  private _content = useIntlayer(this, "lit-demo");
+  private _localeCtrl = useLocale(this, {
+    onLocaleChange: (newLocale: LocalesValues) => {
+      window.location.href = getLocalizedUrl(
+        window.location.pathname,
+        newLocale
+      );
+    },
+  });
+
+  override connectedCallback() {
+    super.connectedCallback();
+    // サーバーによって検出されたロケールで初期化
+    installIntlayer({ locale: this.locale as any });
+  }
+
+  override render() {
+    const { greeting, description } = this._content;
+    const {
+      locale: currentLocale,
+      availableLocales,
+      setLocale,
+    } = this._localeCtrl;
+
+    return html`
+      <div>
+        <h1>${greeting}</h1>
+        <p>${description}</p>
+        <!-- 言語切り替え器はLitElement内にレンダリングされます -->
+        <div class="locale-switcher">
+          <span class="switcher-label">言語を切り替える :</span>
+          <div class="locale-buttons">
+            ${availableLocales.map(
+              (localeItem) => html`
+                <button
+                  class="locale-btn ${localeItem === currentLocale
+                    ? "active"
+                    : ""}"
+                  ?disabled=${localeItem === currentLocale}
+                  @click=${() => setLocale(localeItem)}
+                >
+                  <span class="ls-own-name">${getLocaleName(localeItem)}</span>
+                  <span class="ls-current-name"
+                    >${getLocaleName(localeItem, currentLocale)}</span
+                  >
+                  <span class="ls-code">{localeItem.toUpperCase()}</span>
+                </button>
+              `
+            )}
+          </div>
+        </div>
+      </div>
+    `;
+  }
+}
+
+customElements.define("lit-demo", LitDemo);
+```
+
+> `locale` プロップはAstroページ（サーバー検出）から渡され、要素内のすべての `ReactiveController` フックの初期ロケールとするために `connectedCallback` で `installIntlayer` を初期化するために使用されます。
+
+> `useIntlayer` は `ReactiveController` として登録されます。言語が変更されると要素は自動的に再レンダリングされます。追加の設定は不要です。
+
+### ステップ7: 言語切り替え機能の追加
+
+言語切り替え機能は、Litカスタム要素の `render()` メソッド（ステップ6参照）に直接組み込まれています。`lit-intlayer` の `useLocale` を使用し、ユーザーが新しい言語を選択したときにローカライズされたURLに移動します：
+
+```typescript fileName="src/components/lit/LitDemo.ts"
+// LitElementクラス内、useLocale設定（ステップ6参照）の後：
+
+private _localeCtrl = useLocale(this, {
+  onLocaleChange: (newLocale: LocalesValues) => {
+    // 言語変更時にローカライズされたURLに移動
+    window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
+  },
+});
+
+override render() {
+  const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;
+
+  return html`
+    <div class="locale-switcher">
+      <span class="switcher-label">言語を切り替える :</span>
+      <div class="locale-buttons">
+        ${availableLocales.map(
+          (localeItem) => html`
+            <button
+              class="locale-btn ${localeItem === currentLocale ? "active" : ""}"
+              ?disabled=${localeItem === currentLocale}
+              @click=${() => setLocale(localeItem)}
+            >
+              <span class="ls-own-name">${getLocaleName(localeItem)}</span>
+              <span class="ls-current-name">${getLocaleName(localeItem, currentLocale)}</span>
+              <span class="ls-code">${localeItem.toUpperCase()}</span>
+            </button>
+          `
+        )}
+      </div>
+    </div>
+  `;
+}
+```
+
+> **Litのリアクティビティに関する注意:**
+> `useLocale` は `ReactiveController` を返します。`setLocale` が呼び出されると、コントローラーは自動的に再レンダリングをスケジュールします。そのため、手動でDOMを操作することなく、アクティブなボタンの状態が更新されます。
+
+> **固定の維持に関する注意:**
+> `window.location.href` を介したリダイレクトのために `onLocaleChange` を使用することで、新しい言語のURLが確実に訪問され、Intlayerミドルウェアが言語クッキーを設定して、将来の訪問時にユーザーの好みが記憶されるようになります。
+
+### ステップ8: サイトマップとRobots.txt
+
+Intlayerは、動的にローカライズされたサイトマップとrobots.txtファイルを生成するためのユーティリティを提供します。
+
+#### サイトマップ
+
+Intlayer には、アプリケーションのサイトマップを簡単に作成できるサイトマップ ジェネレーターが組み込まれています。ローカライズされたルートを処理し、検索エンジンに必要なメタデータを追加します。
+
+> Intlayer によって生成されたサイトマップは、`xhtml:link` 名前空間 (Hreflang XML Extensions) をサポートしています。生の URL のみを表示するデフォルトのサイトマップ ジェネレーターとは異なり、Intlayer はページのすべての言語バージョン (例: `/about`、`/about?lang=fr`、`/about?lang=es`) 間に必要な双方向リンクを自動的に作成します。これにより、検索エンジンが正しい言語バージョンを正しい対象者に正しくインデックス付けして提供できるようになります。
+
+すべてのローカライズされたルートを含むサイトマップを生成するために、`src/pages/sitemap.xml.ts` を作成します。
+
+```typescript fileName="src/pages/sitemap.xml.ts"
+import type { APIRoute } from "astro";
+import { generateSitemap, type SitemapUrlEntry } from "intlayer";
+
+const pathList: SitemapUrlEntry[] = [
+  { path: "/", changefreq: "daily", priority: 1.0 },
+  { path: "/about", changefreq: "monthly", priority: 0.7 },
+];
+
+const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
+
+export const GET: APIRoute = async ({ site }) => {
+  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+
+  return new Response(xmlOutput, {
+    headers: { "Content-Type": "application/xml" },
+  });
+};
+```
+
+#### Robots.txt
+
+検索エンジンのクロールを制御するために `src/pages/robots.txt.ts` を作成します。
+
+```typescript fileName="src/pages/robots.txt.ts"
+import type { APIRoute } from "astro";
+import { getMultilingualUrls } from "intlayer";
+
+const getAllMultilingualUrls = (urls: string[]) =>
+  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
+
+const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
+
+export const GET: APIRoute = ({ site }) => {
+  const robotsTxt = [
+    "User-agent: *",
+    "Allow: /",
+    ...disallowedPaths.map((path) => `Disallow: ${path}`),
+    "",
+    `Sitemap: ${new URL("/sitemap.xml", site).href}`,
+  ].join("\n");
+
+  return new Response(robotsTxt, {
+    headers: { "Content-Type": "text/plain" },
+  });
+};
+```
+
+### TypeScriptの設定
+
+Intlayerはモジュール拡張を使用してTypeScriptの利点を活かし、コードベースをより堅牢にします。デコレータ構文を使用している場合、Litでは `experimentalDecorators` を有効にする必要があります。
+
+![オートコンプリート](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![翻訳エラー](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+TypeScriptの設定に自動生成された型が含まれていることを確認してください。
+
+```json5 fileName="tsconfig.json"
+{
+  compilerOptions: {
+    // ...
+    experimentalDecorators: true,
+    useDefineForClassFields: false, // デコレータサポートのためにLitで必須
+  },
+  include: [
+    // ... 既存のTypeScript設定
+    ".intlayer/**/*.ts", // 自動生成された型を含める
+  ],
+}
+```
+
+### Gitの設定
+
+Intlayerによって生成されたファイルを無視することをお勧めします。これにより、それらをGitリポジトリにコミットすることを避けることができます。
+
+そのためには、`.gitignore`ファイルに以下の指示を追加してください：
+
+```bash
+# Intlayerによって生成されたファイルを無視
+.intlayer
+```
+
+### VS Code拡張機能
+
+Intlayerを使用した開発体験を向上させるために、**公式のIntlayer VS Code拡張機能**をインストールできます。
+
+[VS Code Marketplaceからインストール](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+この拡張機能は以下を提供します：
+
+- 翻訳キーの**オートコンプリート**。
+- 欠落している翻訳の**リアルタイムエラー検出**。
+- 翻訳されたコンテンツの**インラインプレビュー**。
+- 翻訳を簡単に作成・更新するための**クイックアクション**。
+
+拡張機能の使用方法の詳細については、[Intlayer VS Code拡張機能のドキュメント](https://intlayer.org/doc/vs-code-extension)を参照してください。
+
+---
+
+### (Optional) Step 15: Extract the content of your components
+
+If you have an existing codebase, transforming thousands of files can be time-consuming.
+
+To ease this process, Intlayer propose a [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/extract.md) to transform your components and extract the content.
+
+To set it up, you can add a `compiler` section in your `intlayer.config.ts` file:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Rest of your config
+  compiler: {
+    /**
+     * Indicates if the compiler should be enabled.
+     */
+    enabled: true,
+
+    /**
+     * Defines the output files path
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * Indicates if the components should be saved after being transformed.
+     *
+     * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
+     *
+     * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
+     */
+    saveComponents: false,
+
+    /**
+     * Dictionary key prefix
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+```
+
+<Tabs>
+ <Tab value='Extract command'>
+
+Run the extractor to transform your components and extract the content
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn intlayer extract
+```
+
+```bash packageManager="bun"
+bun x intlayer extract
+```
+
+ </Tab>
+ <Tab value='Babel compiler'>
+
+Update your `vite.config.ts` to include the `intlayerCompiler` plugin:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Adds the compiler plugin
+  ],
+});
+```
+
+```bash packageManager="npm"
+npm run build # Or npm run dev
+```
+
+```bash packageManager="pnpm"
+pnpm run build # Or pnpm run dev
+```
+
+```bash packageManager="yarn"
+yarn build # Or yarn dev
+```
+
+```bash packageManager="bun"
+bun run build # Or bun run dev
+```
+
+ </Tab>
+</Tabs>
+
+---
+
+### さらに詳しく
+
+さらに詳しく知りたい場合は、[ビジュアルエディター](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_visual_editor.md)を実装したり、[CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md)を使用してコンテンツを外部化したりすることもできます。