Intlayer を使用して Nest バックエンド Web サイトを多言語化する | 国際化 (i18n)

express-intlayer は Express アプリケーション向けの強力な国際化 (i18n) ミドルウェアであり、クライアントの設定に基づいたローカライズされたレスポンスを提供することで、バックエンド サービスをグローバルにアクセス可能にするよう設計されています。NestJS は Express の上に構築されているため、express-intlayer を NestJS アプリケーションにシームレスに統合して、多言語コンテンツを効果的に処理できます。

tical Use Cases

• ユーザーの言語でバックエンドエラーを表示する: エラーが発生した場合、ユーザーの母国語でメッセージを表示することで、理解が向上し、フラストレーションが軽減されます。これは、トーストやモーダルなどのフロントエンドコンポーネントに表示される可能性のある動的なエラーメッセージに特に役立ちます。

• 多言語コンテンツの取得: データベースからコンテンツを取得するアプリケーションの場合、国際化により、複数の言語でこのコンテンツを提供できることが保証されます。これは、製品説明、記事、およびユーザーが希望する言語でその他のコンテンツを表示する必要があるe-commerceサイトやコンテンツ管理システムなどのプラットフォームにとって重要です。

• 多言語メールの送信: トランザクションメール、マーケティングキャンペーン、通知など、受信者の言語でメールを送信することで、エンゲージメントと効果を大幅に向上させることができます。

• 多言語プッシュ通知: モバイルアプリケーションの場合、ユーザーの優先言語でプッシュ通知を送信することで、インタラクションと保持率を向上させることができます。この個人的なタッチにより、通知がより関連性が高く、実用的に感じられるようになります。

• その他の通信: SMS メッセージ、システムアラート、またはユーザーインターフェースの更新など、バックエンドからのあらゆる形式の通信は、ユーザーの言語で行われることで、明確性を確保し、全体的なユーザーエクスペリエンスを向上させます。

バックエンドを国際化することで、アプリケーションは文化的な違いを尊重するだけでなく、グローバル市場のニーズにより適切に対応し、サービスを世界規模で拡張するための重要なステップとなります。

はじめに

新しい NestJS プロジェクトの作成

npm install -g @nestjs/cli
nest new my-nest-app

インストール

express-intlayer を使い始めるには、npm を使ってパッケージをインストールします。

npx intlayer init --interactive

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

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

npm install intlayer express-intlayer

tsconfig.json の設定

TypeScriptでIntlayerを使用するには、tsconfig.jsonがESモジュールをサポートするように設定されていることを確認してください。これは、moduleとmoduleResolutionのオプションをnodenextに設定することで実現できます。

{
  compilerOptions: {
    module: "nodenext",
    moduleResolution: "nodenext",
    // ... その他のオプション
  },
}

セットアップ

プロジェクトのルートに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;

コンテンツの宣言

翻訳を格納するためのコンテンツ宣言を作成および管理します:

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

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

Express ミドルウェアのセットアップ

express-intlayer ミドルウェアを NestJS アプリケーションに統合して、国際化を処理します：

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { intlayer } from "express-intlayer";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(intlayer()).forRoutes("*"); // 全てのルートに適用
  }
}

サービスまたはコントローラーで翻訳を使用する

これで、getIntlayer 関数を使用してサービスやコントローラー内で翻訳にアクセスできます：

import { Injectable } from "@nestjs/common";
import { getIntlayer } from "express-intlayer";

@Injectable()
export class AppService {
  getHello(): string {
    return getIntlayer("app").greet; // 翻訳された挨拶を取得
  }
}

互換性

express-intlayer は以下と完全に互換性があります：

• Reactアプリケーション向けの react-intlayer
• Next.jsアプリケーション向けの next-intlayer
• Viteアプリケーション向けの vite-intlayer

また、ブラウザやAPIリクエストを含む様々な環境での国際化ソリューションともシームレスに連携します。ミドルウェアをカスタマイズして、ヘッダーやクッキーを通じてロケールを検出することも可能です：

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... その他の設定オプション
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

デフォルトでは、express-intlayer は Accept-Language ヘッダーを解釈してクライアントの優先言語を判別します。

設定や高度なトピックの詳細については、ドキュメントをご覧ください。

TypeScriptの設定

express-intlayer は、国際化プロセスを強化するために TypeScript の強力な機能を活用しています。TypeScript の静的型付けにより、すべての翻訳キーが確実に管理され、翻訳漏れのリスクを減らし、保守性を向上させます。

自動生成される型定義ファイル（デフォルトでは ./types/intlayer.d.ts）が tsconfig.json ファイルに含まれていることを確認してください。

{
  // ... 既存の TypeScript 設定
  include: [
    // ... 既存の TypeScript 設定
    ".intlayer/**/*.ts", // 自動生成された型定義を含める
  ],
}

VS Code 拡張機能

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

VS Code Marketplaceからインストール

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

• 翻訳キーの オートコンプリート。
• 欠落している翻訳の リアルタイムエラー検出。
• 翻訳された内容の インラインプレビュー。
• 翻訳の作成や更新を簡単に行うための クイックアクション。

拡張機能の使い方の詳細については、Intlayer VS Code 拡張機能のドキュメントを参照してください。

Git 設定

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

これを行うには、以下の指示を .gitignore ファイルに追加してください。

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