辞書リファレンス

概要

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

• ディクショナリとは何か？
• ディクショナリの使い方
• 他の言語のディクショナリの読み込み
• ディクショナリの使用
• 本番環境での考慮事項

辞書とは何ですか？

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

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

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

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

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

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

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

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

私たちのアドバイス

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

辞書の使い方

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

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

最初のステップは辞書を作成することです。 これは翻訳したいすべてのコンテンツを含むdictionary.js（.json）ファイルです。

dictionary.jsファイルに以下の内容を追加してください：

const dictionary = {
  greetings: {
    hello: 'Hello, World!'
  },
}
 
export default dictionary;

{
  "greetings": {
    "hello": "Hello, World!"
  }
}

次に、それを<GTProvider>コンポーネントに渡します：

import dictionary from "./dictionary.js";
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);

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

useDict()フックを使用して辞書エントリにアクセスできます。 識別子を使って辞書エントリにアクセスするには、d()関数を使用するだけです。

import { useDict } from 'gt-react';
 
export default function MyComponent() {
 
  const d = useDict(); 
 
  return (
    <div>
      {d('greetings.hello')} // [!code highlight]
    </div>
  );
}

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

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

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

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

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

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

辞書の使用

変数

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

const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',    // -> Hello, Alice!
    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
  },
}
export default dictionary;

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'Alice' }})}
      {d('greetings.goodbye', { variables: { name: 'Bob' }})}
    </div>
  );
}

辞書に変数を追加する方法については、DictionaryTranslationOptions 型を参照してください。

プレフィックス

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

const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, World!',
      goodbye: 'Goodbye, World!'
    },
  },
}
export default dictionary;

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  // 'hello' などのすべての翻訳パスは 'greetings' でプレフィックスされます
  const d = useDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

本番環境での考慮事項

本番環境へのデプロイ

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

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

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

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

動作: 開発 vs 本番

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

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

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

メモ

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

次のステップ

• Reactアプリケーションでの<T>コンポーネントの使用方法について学びましょう。
• デプロイメントガイドを使用して本番環境に出荷する方法を学びましょう。