辞書

概要

このガイドでは、辞書についてご紹介します。 必要に応じて、このページ内を自由に読み進めてください。 以下の内容を扱います：

辞書とは何ですか？

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

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

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

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

1. 集中管理: 辞書はすべての翻訳可能なコンテンツを1つのファイルにまとめて保存します。
2. 歴史的な前例: 辞書パターンは業界で一般的なデザインパターンであり、多くの他のi18nライブラリでも使用されています。

同時に、いくつかの大きな欠点もあります。

1. 複雑さ: 辞書は <T> コンポーネントよりもセットアップや使用が複雑です。
2. 可読性: 辞書は <T> コンポーネントよりも可読性が低く、コンテンツがインラインで記述されていないためです。
3. 保守性: 辞書は <T> コンポーネントよりも保守が難しく、コンテンツがインラインではなく別々に保存されているため、翻訳の管理や更新がより困難になります。
4. デバッグのしやすさ: 同じ理由で、辞書は <T> コンポーネントよりもデバッグが難しくなります。 Reactコンポーネントをデバッグしようとする際、コードベースを直接検索するのではなく、辞書内のどこでそのコンテンツが使われているかを追跡する必要があります。

どちらのデザインパターンも当ライブラリでサポートされており、排他的なものではありません。 辞書と <T> コンポーネントを併用することができます。

私たちのアドバイス

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

辞書の使用方法

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

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

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

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

const dictionary = {
  greetings: {
    hello: 'Hello, world!'
  },
}

export default dictionary;

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

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

import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

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

useTranslations()フックを使用して辞書エントリにアクセスできます。 フックから返される関数を使用して、キーで辞書エントリにアクセスするだけです。

import { useTranslations } from 'gt-react';

export default function MyComponent() {
  const d = useTranslations();
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

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

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

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

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

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

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

辞書の使用

変数

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

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

import { useTranslations } from 'gt-react';

export default async function MyComponent() {
  const d = useTranslations();
  return (
    <div>
      {d('greetings.hello', { name: 'Alice' })}
      {d('greetings.goodbye', { name: 'Bob' })}
    </div>
  );
}

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

gt-react の辞書文字列はICUメッセージフォーマットをサポートしており、変数をフォーマットすることも可能です。

プレフィックス

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

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

import { useTranslations } from 'gt-react';

export default async function MyComponent() {
  // 'hello' などのすべての翻訳パスは 'greetings.common.' でプレフィックスされます
  const d = useTranslations('greetings.common'); 

  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

本番環境での考慮事項

本番環境へのデプロイ

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

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

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

動作：開発環境 vs 本番環境

開発環境では、useTranslations()フックから返される関数は、辞書エントリをオンデマンドで翻訳します。 これは、コンポーネントがレンダリングされるときに、即座に翻訳を実行することを意味します。 これは他の言語での開発を容易にするための便宜的な機能です。

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

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

注意事項

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

次のステップ

• <T> コンポーネントについて学び、Reactアプリケーションでの使い方を理解しましょう。
• デプロイガイドを使って、本番環境へのリリース方法を学びましょう。