Intlayerを使用してViteとLitのウェブサイトを翻訳する | 国際化 (i18n)

目次

代替手段ではなく Interlayer を使用する理由

「lit-localize」や「i18next」などの主要なソリューションと比較して、Intlayer は次のような統合された最適化を備えたソリューションです。

GitHub の Application Template を参照してください。

ViteとLitアプリケーションでIntlayerをセットアップするためのステップバイステップガイド

1. 1

   依存関係のインストール

   npmを使用して必要なパッケージをインストールします：

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npx intlayer init --interactive
   

   --interactive フラグはオプションです。AI エージェントの場合は intlayer-cli init を使用してください。

   このコマンドは環境を検出し、必要なパッケージをインストールします。例えば：

   bash

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   npm install intlayer lit-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

     設定管理、翻訳、コンテンツ宣言、トランスパイル、およびCLIコマンドのための国際化ツールを提供するコアパッケージです。

   • lit-intlayer IntlayerをLitアプリケーションと統合するパッケージです。ReactiveControllerベースのフック（useIntlayer、useLocaleなど）を提供し、言語が変更されたときにLitElementが自動的に再レンダリングされるようにします。

   • vite-intlayer IntlayerをViteバンドラーと統合するためのViteプラグイン、およびユーザーの優先言語の検出、クッキーの管理、URLリダイレクトの処理のためのミドルウェアが含まれています。

2. 2

   プロジェクトの設定

   アプリケーションの言語を設定するための設定ファイルを作成します：

   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ログの無効化などを設定できます。利用可能なパラメータの完全なリストについては、設定ドキュメントを参照してください。

3. 3

   Vite設定にIntlayerを統合する

   Vite設定にintlayerプラグインを追加します。

   vite.config.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

   intlayer() Viteプラグインは、IntlayerをViteと統合するために使用されます。コンテンツ宣言ファイルのビルドを確実にし、開発モードでそれらを監視します。Viteアプリケーション内でIntlayer環境変数を定義します。さらに、パフォーマンスを最適化するためのエイリアスを提供します。

4. 4

   エントリポイントでIntlayerをブートストラップする

   最初の要素が接続されるときにグローバルロケールシングルトンが準備できているように、カスタム要素が登録される前に installIntlayer() を呼び出します。

   src/main.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { installIntlayer } from "lit-intlayer";
   
   // 任意のLitElementがDOMに接続される前に呼び出す必要があります。
   installIntlayer();
   
   // カスタム要素をインポートして登録します。
   import "./my-element.js";
   

   md() コンテンツ宣言（Markdown）も使用する場合は、Markdownレンダラーもインストールしてください：

   src/main.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";
   
   installIntlayer();
   installIntlayerMarkdown();
   
   import "./my-element.js";
   

5. 5

   コンテンツの宣言

   翻訳を保存するためのコンテンツ宣言を作成および管理します：

   src/app.content.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Lit",
   
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       litLogo: t({
         en: "Lit logo",
         fr: "Logo Lit",
         es: "Logo Lit",
       }),
   
       count: t({
         en: "count is {{count}}",
         fr: "le compte est {{count}}",
         es: "el recuento es {{count}}",
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and Lit logos to learn more",
         fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   コンテンツ宣言は、contentDir ディレクトリ（デフォルトは ./src）に含まれ、コンテンツ宣言ファイルの拡張子（デフォルトは .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）と一致する限り、アプリケーション内のどこにでも定義できます。

   詳細については、コンテンツ宣言のドキュメントを参照してください。

6. 6

   LitElementでIntlayerを活用する

   LitElement 内で useIntlayer を使用します。これは、アクティブなロケールが変更されるたびに自動的に再レンダリングをトリガーする ReactiveController プロキシを返します。追加の設定は不要です。

   src/my-element.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { LitElement, html } from "lit";
   import { customElement, property } from "lit/decorators.js";
   import { useIntlayer } from "lit-intlayer";
   
   @customElement("my-element")
   export class MyElement extends LitElement {
     @property({ type: Number })
     count = 0;
   
     // useIntlayerはReactiveControllerとして自身を登録します。
     // 要素は言語が変更されると自動的に再レンダリングされます。
     private content = useIntlayer(this, "app");
   
     override render() {
       const { content } = this;
   
       return html`
         <h1>${content.title}</h1>
   
         <img src="/vite.svg" alt=${content.viteLogo.value} />
         <img src="/lit.svg" alt=${content.litLogo.value} />
   
         <button @click=${() => this.count++}>
           ${content.count({ count: this.count })}
         </button>
   
         <p>${content.readTheDocs}</p>
       `;
     }
   }
   

   ネイティブHTML属性（例：alt、aria-label、title）で翻訳された文字列が必要な場合は、リーフノードで .value を呼び出します：

   typescript

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   html`<img alt=${content.viteLogo.value} />`;
   html`<img alt=${content.viteLogo.toString()} />`;
   html`<img alt=${String(content.viteLogo)} />`;
   

7. 7

   コンテンツの言語を変更する

   オプション

   コンテンツの言語を変更するには、useLocale コントローラーによって公開されている setLocale メソッドを使用します。

   src/locale-switcher.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { LitElement, html } from "lit";
   import { customElement } from "lit/decorators.js";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "lit-intlayer";
   
   @customElement("locale-switcher")
   export class LocaleSwitcher extends LitElement {
     private locale = useLocale(this);
   
     private _onChange(e: Event) {
       const select = e.target as HTMLSelectElement;
       this.locale.setLocale(select.value as any);
     }
   
     override render() {
       return html`
         <select @change=${this._onChange}>
           ${this.locale.availableLocales.map(
             (loc) => html`
               <option value=${loc} ?selected=${loc === this.locale.locale}>
                 ${getLocaleName(loc)}
               </option>
             `
           )}
         </select>
       `;
     }
   }
   

8. 8

   MarkdownとHTMLコンテンツのレンダリング

   オプション

   Intlayerは md() および html() コンテンツ宣言をサポートしています。Litでは、コンパイルされた出力は unsafeHTML ディレクティブを介して生HTMLとして挿入されます。

   コンパイルされたHTMLを要素内でレンダリングします：

   src/my-element.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { LitElement, html } from "lit";
   import { customElement } from "lit/decorators.js";
   import { unsafeHTML } from "lit/directives/unsafe-html.js";
   import { useIntlayer } from "lit-intlayer";
   import { compileMarkdown } from "lit-intlayer/markdown";
   
   @customElement("my-element")
   export class MyElement extends LitElement {
     private content = useIntlayer(this, "app");
   
     override render() {
       return html`
         <div class="edit-note">
           ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}
         </div>
       `;
     }
   }
   

   TIP

   String(content.editNote) は、生のMarkdown文字列を返す IntlayerNode の toString() を呼び出します。それを compileMarkdown に渡してHTML文字列を取得し、Litの unsafeHTML ディレクティブでレンダリングします。

9. 9

   アプリケーションにローカライズされたルーティングを追加する

   オプション

   言語ごとに固有のルートを作成するには（SEOに有用）、クライアントサイドのルーターをIntlayerの localeMap / localeFlatMap ヘルパー、およびサーバーサイドの言語検出用の intlayerProxy Viteプラグインと共に使用できます。

   まず、Vite設定に intlayerProxy を追加します：

   プロダクション環境で intlayerProxy を使用するには、vite-intlayer を devDependencies から dependencies に移動する必要があることに注意してください。

   Intlayer v9 以降、intlayerProxy() は intlayer() プラグインに直接バンドルされており、routing.enableProxy オプション（デフォルトで true）を通じてデフォルトで有効になっています。以下に示すように個別に登録することはオプションになりました — これはbackward compatibility のため、またプラグインの順序を制御する必要があるセットアップのために保持されています。routing.enableProxy: false を設定してオプトアウトできます。v9 release notes を参照してください。

   vite.config.ts

   コンテンツをコピー

   コードをコピー

   コードをクリップボードにコピー

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

10. 10

    言語が変更されたときにURLを変更する

    オプション

    言語が変更されたときにブラウザのURLを更新するには、ロケールスイッチャーと共に useRewriteURL を使用します：

    src/locale-switcher.ts

    コンテンツをコピー

    コードをコピー

    コードをクリップボードにコピー

    import { LitElement, html } from "lit";
    import { customElement } from "lit/decorators.js";
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale, useRewriteURL } from "lit-intlayer";
    
    @customElement("locale-switcher")
    export class LocaleSwitcher extends LitElement {
      private locale = useLocale(this);
    
      // 言語が変更されたときに現在のURLを自動的に書き換えます。
      private _rewriteURL = useRewriteURL(this);
    
      private _onChange(e: Event) {
        const select = e.target as HTMLSelectElement;
        this.locale.setLocale(select.value as any);
      }
    
      override render() {
        return html`
          <select @change=${this._onChange}>
            ${this.locale.availableLocales.map(
              (loc) => html`
                <option value=${loc} ?selected=${loc === this.locale.locale}>
                  ${getLocaleName(loc)}
                </option>
              `
            )}
          </select>
        `;
      }
    }
    

11. 11

    HTMLの言語と方向属性を切り替える

    オプション

    アクセシビリティとSEOのために、現在の言語に合わせて <html> タグの lang および dir 属性を更新します。

    src/my-element.ts

    コンテンツをコピー

    コードをコピー

    コードをクリップボードにコピー

    import { LitElement, html } from "lit";
    import { customElement } from "lit/decorators.js";
    import { getHTMLTextDir } from "intlayer";
    import { useLocale } from "lit-intlayer";
    
    @customElement("my-element")
    export class MyElement extends LitElement {
      private locale = useLocale(this, {
        onLocaleChange: (loc) => {
          document.documentElement.lang = loc;
          document.documentElement.dir = getHTMLTextDir(loc);
        },
      });
    
      override render() {
        return html`<!-- コンテンツ -->`;
      }
    }
    

12. 12

    コンポーネントのコンテンツを抽出する

    オプション

    既存のコードベースがある場合、数千ものファイルを変換するのは時間がかかる場合があります。

    このプロセスを容易にするために、Intlayerはコンポーネントを変換してコンテンツを抽出するための コンパイラ / 抽出器 を提案しています。

    セットアップするには、intlayer.config.ts ファイルに compiler セクションを追加します：

    intlayer.config.ts

    コンテンツをコピー

    コードをコピー

    コードをクリップボードにコピー

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... その他の設定
      compiler: {
        /**
         * コンパイラを有効にするかどうかを指定します。
         */
        enabled: true,
    
        /**
         * 出力ファイルのパスを定義します
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * コンポーネントを変換した後に保存するかどうかを指定します。
         * これにより、コンパイラを一度だけ実行してアプリを変換し、その後削除することができます。
         */
        saveComponents: false,
    
        /**
         * 辞書キーのプレフィックス
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

（任意）サイトマップと robots.txt（ビルド時生成）

Intlayer は generateSitemap と getMultilingualUrls により、クローラ向けに整形した多言語の sitemap.xml と robots.txt を public/ に自動で書き出せます。通常は Vite より前に小さな Node スクリプトを走らせます（例: npm の predev / prebuild）。

サイトマップ

Intlayer のサイトマップ生成はロケール設定を踏まえ、クローラ向けのメタデータを含めます。

生成されるサイトマップは xhtml:link（hreflang）をサポートします。単純な URL 列挙ではなく、各ページの言語版同士を双方向で結びます（例: /about、/fr/about、/about?lang=fr などルーティングに依存）。

Robots.txt

getMultilingualUrls で Disallow を、機微パスのすべての言語 URLに効かせます。

1. プロジェクトルートに generate-seo.mjs を置く

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

intlayer がインストールされている必要があります。本番では環境変数 SITE_URL を設定してください（CI など）。

Node の ESM では generate-seo.mjs を推奨します。generate-seo.js にする場合は package.json の "type": "module" などで ESM を有効にしてください。

2. Vite より前にスクリプトを実行する

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

pnpm や yarn を使う場合はコマンドを読み替えてください。CI から呼び出しても構いません。

TypeScriptの設定

TypeScriptの設定に自動生成された型が含まれていることを確認してください。

{
  "compilerOptions": {
    // ...
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

experimentalDecorators と useDefineForClassFields: false は、Litのデコレーターサポートに必要です。

Gitの設定

Intlayerによって生成されたファイルは無視することをお勧めします。これにより、それらをGitリポジトリにコミットすることを避けることができます。

これを行うには、.gitignore ファイルに以下の指示を追加します：

# Intlayerによって生成されたファイルを無視
.intlayer

VS Code拡張機能

Intlayerでの開発体験を向上させるために、公式の Intlayer VS Code Extension をインストールできます。

VS Code Marketplaceからインストール

この拡張機能は以下を提供します：

• 翻訳キーの自動補完。
• 翻訳漏れのリアルタイムなエラー検出。
• 翻訳されたコンテンツのインラインプレビュー。
• 翻訳を簡単に作成および更新できるクイックアクション。

詳細な使用方法については、Intlayer VS Code Extensionドキュメントを参照してください。

さらに詳しく

さらに詳しく知りたい場合は、ビジュアルエディタを実装したり、CMSを使用してコンテンツを外部化したりすることができます。

よくある質問