General Translation  
ダッシュボードブログDiscord

辞書リファレンス

辞書パターンの概要

概要

このリファレンスガイドでは、ディクショナリパターンについて紹介します。 必要に応じてこのページを自由に読み飛ばしてください。 以下の内容を取り上げます：

辞書とは何ですか？

General Translationでは、翻訳可能なコンテンツを辞書ファイルに保存することができます。 辞書は、翻訳可能なコンテンツを保存するために使用できる文字列値を持つネストされたオブジェクトです。 この辞書ファイル（.ts、.js、または.json）は、その後翻訳を生成するために使用されます。

辞書は単独で使用することも、<T>コンポーネントと組み合わせて使用することもできます。

辞書と<T>コンポーネントの比較

辞書パターンには<T>コンポーネントに比べていくつかの利点があります：

  1. 一元化された保存: 辞書はすべての翻訳可能なコンテンツを単一のファイルに保存するため、管理や更新が容易になります。
  2. 歴史的な先例: 辞書パターンは業界で一般的な設計パターンであり、多くの他のライブラリでも使用されています。

同時に、いくつかの欠点もあります：

  1. 複雑さ: 辞書は<T>コンポーネントよりもセットアップと使用が複雑です。
  2. 読みやすさ: 辞書はコンテンツがインラインではないため、<T>コンポーネントよりも読みにくいです。
  3. 保守性: 辞書はコンテンツがインラインではなく、別々に保存されるため、<T>コンポーネントよりも保守が難しいです。これにより、翻訳のデバッグと保守がはるかに困難になります。

両方の設計パターンは当社のライブラリでサポートされており、相互に排他的ではありません。 辞書と<T>コンポーネントを併用することができます。

私たちのアドバイス

特に国際化（i18n）が初めての場合は、シンプルさから<T>コンポーネントの使用をお勧めします。 過去の経験からこの設計パターンを好む方や、既存のコードベースとの統合を容易にするために、辞書のサポートを提供しています。

辞書の使い方

このセクションでは、Next.jsアプリケーションで基本的な辞書実装をセットアップする方法を紹介します。 以下のステップを順に説明します：

辞書を作成する

辞書を参照する

ステップ1：辞書を作成する

最初のステップは辞書を作成することです。 これは翻訳したいすべてのコンテンツを含むdictionary.js（.tsまたは.json）ファイルです。 辞書をsrc/ディレクトリに作成します。

dictionary.js <--- ここに辞書ファイルを追加
middleware.js
next.config.js

src/フォルダを使用していない場合は、next.config.jsファイルで辞書のディレクトリを指定することもできます。

dictionary.jsファイルに以下の内容を追加します：

src/dictionary.js
const dictionary = {
  greetings: {
    goodbye: 'Goodbye, World!'
  },
}
export default dictionary;

辞書を保存するためにdictionary.jsonファイルを使用することもできます。これは別のライブラリから移行する場合や、JSONファイルを使用したい場合に便利です。 以下はdictionary.jsonファイルの例です：

src/dictionary.json
{
  "greetings": {
    "goodbye": "Goodbye, World!"
  }
}

ステップ2：辞書を参照する

辞書を使用する方法はいくつかあり、辞書を使用しようとしているコンテキストによって異なります。 例えば、クライアントサイドコンポーネントではuseDict()フックを使用し、 サーバーサイドコンポーネントではawait getDict()を使用します。

以下はクライアントサイドコンポーネントで辞書を使用する例です：

"use client";
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
 
  const d = useDict(); // クライアントサイドではuseDictフックを使用します
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

そして、サーバーサイドコンポーネントで翻訳にアクセスする例です：

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
 
  const d = await getDict(); // サーバーサイドではプロミスをawaitする必要があります
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

他の言語の辞書を読み込む

デフォルトでは、開発者はデフォルト言語の辞書のみを提供します。

General Translationは他の言語の辞書を自動的に生成し、loadTranslations関数でそれらを読み込みます。

ただし、別のi18nライブラリから移行している場合や、すでに他の言語の辞書がある場合は、それらをloadDictionary関数に渡すことができます。

gt-nextはuseDict()フックまたはgetDict()関数を使用する際に、要求されたロケールに対応する辞書を自動的に読み込みます。

詳細については、APIリファレンスを参照してください。

辞書の使用

変数

{variable} 構文を使用して辞書に変数を追加できます：

src/dictionary.js
const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',
    goodbye: 'Goodbye, {name}!'
  },
}
export default dictionary;
src/components/MyComponent.js
import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  const d = await getDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'World' }})}
      {d('greetings.goodbye', { variables: { name: 'World' }})}
    </div>
  );
}

辞書に変数を追加する方法の詳細については、DictionaryTranslationOptions 型をご覧ください。

プレフィックス

さらに、useDict()とgetDict()では、辞書内の共有パスを指定するためのプレフィックスを関数に渡すことができます。 これは、複数のコンポーネントで使用したい辞書内の共有パスがある場合に便利です。

const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, World!',
      goodbye: 'Goodbye, World!'
    },
  },
}
export default dictionary;
src/components/MyComponent.js
import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  // 'hello'などの翻訳パスはすべて'greetings'でプレフィックスされます
  const d = await getDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

<GTProvider>によるサブセット

<GTProvider>コンポーネントでプレフィックスを指定することもできます。 これにより、辞書のサブセットがクライアントに渡されるため、辞書全体をロードする必要がなくなります。 これはクライアントサイドコンポーネントにのみ適用されます。

layout.js
import { GTProvider } from 'gt-next';
 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                <GTProvider id="nested.dictionary.key"> // [!code highlight]
                    {children}
                </GTProvider> // [!code highlight]
            </body>
        </html>
    );
}

辞書内のキーを参照する際には、完全なパスを指定する必要があります。

"use client";
 
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('nested.dictionary.key.greeting')} // [!code highlight]
    </div>
  );
}

本番環境での考慮事項

本番環境へのデプロイ

本番環境にデプロイする前に、翻訳コマンドを実行して、すべての翻訳が実行時に利用可能であることを確認してください。 CDパイプラインに追加するか、ビルドスクリプトの一部として追加することをお勧めします。

package.json
{
  "scripts": {
    "build": "npx gtx-cli translate --languages fr es ja && <YOUR_BUILD_COMMAND>",
  }
}

これで完了です！ アプリケーションがフランス語、スペイン語、日本語に正常に翻訳されました。

アプリケーションのデプロイに関する詳細なガイドについては、デプロイメントガイドを参照してください。 コマンドに関する詳細情報については、CLIツールリファレンスガイドを参照してください。

動作: 開発 vs 本番

開発環境では、d() 関数は辞書エントリをオンデマンドで翻訳します。 これは、コンポーネントがレンダリングされるときに、即座に翻訳を実行することを意味します。 これは、他の言語での開発を容易にするための便宜上の措置です。

この動作を有効にするには、環境にDev APIキーを追加するだけです。

本番環境では、d() 関数はビルド時にコンテンツを翻訳します。 これは、アプリケーションをデプロイする前に翻訳コマンドを実行する必要があることを意味します。

ヒント: 開発環境で本番環境の動作をシミュレートしたい場合は、開発ビルドで本番APIキーを使用するだけです。

注意事項

  • 辞書は<T>コンポーネントの代替手段です。<T>コンポーネントと併用することも、単独で使用することもできます。
  • 辞書の翻訳はビルド時に行われるため、ビルドプロセスにtranslateコマンドを追加する必要があります。
  • 辞書はプレフィックスと共に使用して、辞書のサブセットを指定することができます。

次のステップ

GitHubで編集

<T> リファレンス

<T> コンポーネントと gt-next ライブラリについての詳細な解説です。

ロケールを管理する

アプリのロケールを管理する方法

このページについて