概要
General Translation の Next.js SDK 概要
はじめに
General Translation の Next.js SDK は、Next.js アプリケーション向けのオープンソースの国際化（i18n）ライブラリです。
この SDK は、他の一般的な i18n ライブラリと機能面で同等であり、Next.js アプリケーションを簡潔かつ保守しやすく国際化するための包括的なツールセットを提供します。React SDK を基盤としており、Next.js 固有の追加機能を備えています。
SDK は General Translation のプラットフォームなしでも単体で利用でき、他の i18n ライブラリと同様に動作します。
また、以下のような拡張機能のために当社プラットフォームと連携することもできます：
- 開発時の翻訳ホットリロード
- 自動 AI 翻訳
- General Translation プラットフォームとの翻訳同期
- 当社の翻訳 CDN とのネイティブ統合
- 本番環境での React コンポーネントのオンデマンド翻訳（サーバーサイド）
コンセプト
この SDK で理解しておくべき主要なコンセプトは 6 つあります。
withGTConfig による初期化
withGTConfig 関数は、Next.js アプリケーションで SDK を初期化します。
SDK を構成するために、next.config.[js|ts] ファイルに追加してください。
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// next.config.ts の options
};
export default withGTConfig(nextConfig, {
// GT の設定
});詳しくはwithGTConfig APIリファレンスをご覧ください。
<GTProvider> コンポーネント
<GTProvider> コンポーネントは、現在の言語や対応する翻訳を含む翻訳コンテキストをアプリケーションに提供します。
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}重要: プロバイダーはアプリケーション全体をラップし、可能な限りコンポーネントツリーの上位、たとえばルートレイアウトに配置してください。
プロバイダーはクライアントサイドの機能にのみ必要です。サーバーサイド専用のアプリケーションでは不要ですが、含めても問題ありません。
詳細は GTProvider のAPIリファレンスを参照してください。
<T> コンポーネント
<T> コンポーネントは、アプリケーション内のコンテンツを翻訳するための推奨手段です。
これは React のコンポーネントで、任意の JSX 要素をラップして使用でき、要素の内容をサポート対象の言語で自動的にレンダリングします。
例
<T>
<div>こんにちは、世界！</div>
</T><T>
<div>
<h1>画像があります</h1>
<img src="https://example.com/image.png" alt="例" />
</div>
</T><T>
`<T>`コンポーネントを使えば、簡単にフォーマットできます。
<Num>{1000}</Num>
<DateTime>{new Date()}</DateTime>
<Currency currency="USD">{1000}</Currency>
</T><T> コンポーネントは、動的コンテンツの整形のために、<Num>、<DateTime>、<Currency> などの variable components と組み合わせて動作します。
<T> コンポーネントガイド では、<T> コンポーネントのさまざまな使用方法を学べます。
useGT フック
useGT フックは、いくつかのトレードオフはあるものの、<T> コンポーネントと同様に使える React フックです。
このフックは、文字列を翻訳するために使用できる関数を返します。
const t = useGT();
t('こんにちは、世界！');<T> コンポーネントと比べると、useGT フックはコードベースにおいてより柔軟に扱えます。
たとえば、ネストされた文字列を含む複雑なデータ構造がある場合は、<T> コンポーネントのほうが扱いづらくなります。
const t = useGT();
const data = {
title: t('こんにちは、世界！'),
description: t('これは説明です'),
};useGT フックの詳しい使い方は、strings ガイドをご覧ください。
msg 関数
msg 関数は、複数のコンポーネントで使われる文字列や、設定オブジェクトに保存される文字列を翻訳対象としてマークするために使用します。
これは、ナビゲーションラベル、フォームメッセージ、またはアプリケーション内の複数箇所に表示されるあらゆるテキストといった共有コンテンツに特に有用です。
// 翻訳対象の文字列をマーク
import { msg } from 'gt-next';
const navItems = [
{ label: msg('ホーム'), href: '/' },
{ label: msg('About'), href: '/about' },
{ label: msg('お問い合わせ'), href: '/contact' }
];// マークされた文字列をデコードして使用する
import { useMessages } from 'gt-next';
function Navigation() {
const m = useMessages();
return (
<nav>
{navItems.map(item => (
<a key={item.href} href={item.href}>
{m(item.label)}
</a>
))}
</nav>
);
}msg 関数は翻訳用のメタデータ付きで文字列をエンコードし、useMessages（サーバーコンポーネントでは getMessages）がそれらをデコードします。
msg 関数の詳細は、shared strings ガイドをご覧ください。
useTranslations フック
useTranslations フックは、指定したキーの翻訳を取得するために使える関数を返す React のフックです。
const dictionary = {
hello: {
world: 'こんにちは、世界！',
},
};const translate = useTranslations();
translate('hello.world');この挙動は、react-i18next や next-intl などの他の翻訳ライブラリと似ています。
アプリケーション内での useTranslations フックの使用は推奨しません。useTranslations フックを頻繁に使うと、コードベースの保守が難しくなり、
大きなテックデットの原因になります。
代わりに、<T> コンポーネントか useGT フックの使用を推奨します。
別の i18n ライブラリから移行中の場合、useTranslations フックはドロップインで置き換え可能で、コードベースを段階的に移行するのに役立ちます。
useTranslations フックについては、dictionaries ガイドもご覧ください。
詳しくは useTranslations APIリファレンス を参照してください。
次のステップ
このガイドはいかがですか?