ドキュメント: hono-intlayer における t 関数

hono-intlayer パッケージの t 関数は、Hono アプリケーションでローカライズされたレスポンスを提供するためのコア ユーティリティです。ユーザーの優先言語に基づいてコンテンツを動的に選択することで、国際化 (i18n) を簡素化します。

概要

t 関数は、特定の言語セットに対する翻訳を定義し、取得するために使用されます。Accept-Language ヘッダーなどのクライアントのリクエスト設定に基づいて、返すべき適切な言語を自動的に決定します。優先言語が利用できない場合は、設定で指定されたデフォルトのロケールに適切にフォールバックします。

主な機能

• 動的なローカリゼーション: クライアントにとって最も適切な翻訳を自動的に選択します。
• デフォルト ロケールへのフォールバック: クライアントの優先言語が利用できない場合、デフォルトのロケールにフォールバックし、ユーザー エクスペリエンスの継続性を確保します。
• 軽量で高速: 高パフォーマンスなアプリケーション向けに設計されており、オーバーヘッドを最小限に抑えます。
• 厳格モードのサポート: 信頼性の高い動作のために、宣言されたロケールの厳守を強制します。

関数のシグネチャ

t(translations: Record<string, string>): string;

パラメータ

• translations: キーがロケール コード (例: en、fr、ja) で、値が対応する翻訳文字列であるオブジェクト。

戻り値

• クライアントの優先言語でのコンテンツを表す文字列。

国際化リクエスト ハンドラのロード

hono-intlayer が提供する国際化機能が正しく動作するようにするには、Hono アプリケーションの最初に国際化ミドルウェアをロードする必要があります。これにより t 関数が有効になり、ロケール検出と翻訳が適切に処理されます。

アプリケーションのすべてのルートの前に app.use("*", intlayer()) ミドルウェアを配置し、すべてのルートが国際化の恩恵を受けられるようにしてください。

import { Hono } from "hono";
import { intlayer } from "hono-intlayer";

const app = new Hono();

// 国際化リクエスト ハンドラをロード
app.use("*", intlayer());

// ミドルウェアのロード後にルートを定義
app.get("/", (c) => {
  return c.text(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
      ja: "こんにちは、世界！",
    })
  );
});

これが必要な理由

• ロケール検出: intlayer ミドルウェアは、ヘッダー、クッキー、またはその他の構成された方法に基づいてユーザーの優先ロケールを検出するために、着信リクエストを処理します。
• 翻訳コンテキスト: t 関数が正しく動作するために必要なコンテキストを設定し、翻訳が正しい言語で返されるようにします。
• エラー防止: このミドルウェアがないと、必要なロケール情報が利用できないため、t 関数を使用するとランタイム エラーが発生します。

使用例

基本的な例

異なる言語でローカライズされたコンテンツを提供します。

app.get("/", (c) => {  return c.text(    t({      en: "Welcome!",      fr: "Bienvenue!",      ja: "ようこそ！",    })  );});

クライアント リクエスト:

• Accept-Language: fr のクライアントは Bienvenue! を受け取ります。
• Accept-Language: ja のクライアントは ようこそ！ を受け取ります。
• Accept-Language: de のクライアントは Welcome! (デフォルト ロケール) を受け取ります。

エラー処理

複数の言語でエラー メッセージを提供します。

app.get("/error", (c) => {  return c.text(    t({      en: "An unexpected error occurred.",      fr: "Une erreur inattendue s'est produite.",      ja: "予期しないエラーが発生しました。",    }),    500  );});

ロケール バリアントの使用

ロケール固有のバリアントに対する翻訳を指定します。

app.get("/greet", (c) => {  return c.text(    t({      en: "Hello!",      "en-GB": "Hello, mate!",      fr: "Bonjour!",      ja: "こんにちは！",    })  );});

高度なトピック

フォールバック メカニズム

優先ロケールが利用できない場合、t 関数は設定で定義されたデフォルト ロケールにフォールバックします。

import { Locales, type IntlayerConfig } from "intlayer";const config = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.JAPANESE],    defaultLocale: Locales.ENGLISH,  },} satisfies IntlayerConfig;export default config;

厳格モードの強制

宣言されたロケールの厳守を強制するように t 関数を構成します。

TypeScript の統合

TypeScript と一緒に使用すると、t 関数は型安全になります。型安全な翻訳オブジェクトを定義します。

import { type LanguageContent } from "hono-intlayer";const translations: LanguageContent<string> = {  en: "Good morning!",  fr: "Bonjour!",  ja: "おはようございます！",};app.get("/morning", (c) => {  return c.text(t(translations));});

よくあるエラーとトラブルシューティング

結論

t 関数は、バックエンドの国際化のための強力なツールです。これを効果的に使用することで、グローバルな視聴者にとってより包括的でユーザーフレンドリーなアプリケーションを作成できます。高度な使用法と詳細な構成オプションについては、ドキュメントを参照してください。