12 KiB
ローカライズされたクライアント Web アプリに貢献する方法
学習プラットフォームを動かす React ベースのクライアント Web アプリは、Gatsby を使用して構築されています。 react-i18next と i18next を使用して、様々な世界の言語に翻訳されています。
開発用クライアントアプリケーションのローカル設定については、こちらの ローカル設定ガイドをご覧ください。 デフォルトでは、アプリケーションは英語でのみ使用できます。
ローカルでプロジェクトを設定したら、利用可能な言語リストから選択した言語でクライアントを実行するために、このドキュメントに従ってください。
これは、ローカライゼーションを含むものを対象にし、例えば別の言語でボタンラベルを検証する必要がある機能に関して作業している場合に役立ちます。
[!TIP] freeCodeCamp のカリキュラムやコントリビューションドキュメントを翻訳するために、このドキュメントに従う必要はありません。 代わりに、このガイド をお読みください。
i18n フレームワークとツールがどのように機能するかを理解しましょう。
ファイル構成
プラットフォームを翻訳するために必要なファイルの多くは、client/i18n
フォルダに入っています。 各言語には、翻訳付きの JSON ファイルを含むディレクトリがあります。
config/i18n
└── all-langs.ts
...
client/i18n
├── configForTests.js
├── config.js
├── locales
│ ├── chinese
│ │ ├── intro.json
│ │ ├── links.json
│ │ ├── meta-tags.json
│ │ ├── motivation.json
│ │ ├── translations.json
│ │ └── trending.json
... ...
│ ├── dothraki
│ │ ├── intro.json
│ │ ├── links.json
│ │ ├── meta-tags.json
│ │ ├── motivation.json
│ │ ├── translations.json
│ │ └── trending.json
... ...
│ ├── english
│ │ ├── intro.json
│ │ ├── links.json
│ │ ├── meta-tags.json
│ │ ├── motivation.json
│ │ ├── translations.json
│ │ └── trending.json
│ └── espanol
│ ├── intro.json
│ ├── links.json
│ ├── meta-tags.json
│ ├── motivation.json
│ ├── translations.json
│ └── trending.json
├── locales.test.js
├── schema-validation.js
└── validate-keys.ts
これらのファイルは翻訳プラットフォーム (Crowdin) で翻訳されていますが、翻訳されていないものもあります。
翻訳プラットフォーム上で翻訳されたファイル:
-
translations.json
ファイルは、ユーザーインターフェース要素に表示されるテキストの大部分を含んでいます。 キーは、設定されるすべての言語で正しいテキストが取得できるように、コードベースで使用されます。 このファイルでは、すべての言語で同じキーが必要です。 -
intro.json
ファイルには、認定講座ページの紹介テキスト用に、キーと値のペアが含まれています。キーの翻訳を追加 / 更新したい場合は、こちらのガイド をご覧ください。
翻訳プラットフォーム上で翻訳されていないファイル:
-
motivation.json
ファイルは、同じ引用符、賛辞、配列の長さを含む必要はありません。 JSON 構造だけは同じです。 -
trending.json
ファイルは、Web サイトのフッターにトレンドニュース記事のタイトルとリンクを含みます。 -
meta-tags.json
ファイルには、Web サイトのメタタグ情報に関する情報が含まれています。これらのファイルの変更は通常、スタッフチームによって行われます。 異常が表示された場合は、contributors チャットルーム に連絡することをお勧めします。
世界の言語でクライアントアプリをテストする
クライアントアプリは、言語リスト にある言語でテストできます。
const availableLangs = {
client: ['english', 'espanol', 'chinese'],
...
};
新しい言語をテストするには、言語名をタイトルとしたフォルダを他の言語の隣に作成し、JSON ファイルを別の言語から新しいフォルダにコピーします。
上記の config/i18n/all-langs.js
ファイルにあるように、client
配列に言語を追加します。
次に、同じファイルのコメント指示に従って、必要に応じて残りの変数を追加 / 更新します。
最後に、.env
ファイルの CLIENT_LOCALE
変数を、ビルドするロケールに設定します。これで準備が整います。
コンポーネントの構築方法
クライアント Web アプリの機能やバグの作業をしていて、例えば、設定ページに新しい UI アイテムを追加する場合は、以下のガイドラインに従ってください。 これらは、サポートされている世界言語へのローカライゼーションで、コンポーネントを準備するのに役立ちます。
関数コンポーネント
import { useTranslation } from 'react-i18next';
// in the render method:
const { t } = useTranslation();
// call the "t" function with a key from the JSON file:
<p>{t('key')}</p>; // more details below
クラスコンポーネント
import { withTranslation } from 'react-i18next';
// withTranslation adds the "t" function to props:
const { t } = this.props;
// call the "t" function with a key from the JSON file:
<h1>{t('key')}</h1> // more details below
// export without redux:
export default withTranslation()(Component);
// or with redux:
export default connect(...)(withTranslation()(Component));
「t」関数を使って翻訳する
基本的な翻訳
// in the component:
<p>{t('p1')}</p>
// in the JSON file:
{
"p1": "My paragraph"
}
// output:
<p>My paragraph</p>
動的データの使用
// in the component:
const username = 'moT';
<p>{t('welcome', { username: username })}</p>
// in the JSON file:
{
"welcome": "Welcome {{username}}"
}
// output:
<p>Welcome moT</p>
上の例では、 username
変数を使用して t
関数にオブジェクトを渡します。 変数は、{{username}}
の JSON 値で使用されます。
Trans
コンポーネントを使用した翻訳
一般的なルールは、「t」関数を使うことです。 しかし、それだけでは不十分な場合のための Trans
コンポーネントがあります。通常、テキストに要素が埋め込まれている場合に使用されます。 どんな型の React コンポーネントでも Trans
コンポーネントを使用できます。
ネストされた基本要素
// in the component:
import { Trans } from 'react-i18next'
<p>
<Trans>fcc.greeting</Trans>
</p>
// in the JSON file:
{
"fcc": {
"greeting": "Welcome to <strong>freeCodeCamp</strong>"
}
}
// output:
<p>Welcome to <strong>freeCodeCamp</strong></p>
上記の例のように、テキストが属性のない「単純な」タグを含む場合、キーをコンポーネントタグの中に置くことができます。 br
、strong
、i
、および p
がデフォルトですが、そのリストは、i18n config で拡張できます。
ネストされた複雑な要素
別の要素内に特定のテキストを持たせたい場合、アンカータグが良い例です。
// in the component:
<p>
<Trans i18nKey='check-forum'>
<a href='https://forum.freecodecamp.org/'>placeholder</a>
</Trans>
</p>
// in the JSON file:
{
"check-forum": "Check out <0>our forum</0>."
}
// output:
<p>Check out <a href='https://forum.freecodecamp.org/'>our forum</a></p>
上記の例では、キーは Trans
コンポーネントの属性に設定されています。 JSON の <0>
と </0>
はコンポーネントの最初の子要素を表します。 この場合、アンカー要素です。 もっと多くの子要素がある場合、同じ構文を使ってそこから数えるだけです。 React 開発ツールで調べることにより、コンポーネントの子要素を見つけることができます。 placeholder
は単にそこにあるだけです。なぜなら、リンターが空の <a>
要素について不平を言うからです。
変数の使用
// in the component:
const email = 'team@freecodecamp.org';
<p>
<Trans email={email} i18nKey='fcc.email'>
<a href={`mailto:${email}`}>
{{ email }}
</a>
</Trans>
</p>
// in the JSON file:
{
"fcc": {
"email": "Send us an email at: <0>{{email}}</0>"
}
}
// output:
<p>Send us an email at: <a href='mailto:team@freecodecamp.org'>team@freecodecamp.org</a><p>
上記の例では、キーと変数は Trans
コンポーネントの属性に設定されています。 {{ email }}
は、Trans
コンポーネントのどこかにある必要がありますが、どこであっても問題はありません。
テキストの変更
クライアント側でテキストを変更するには、関連する .json
ファイルで、React コンポーネントで使用されているキーを見つけて、値を新しいテキストに変更します。 そのキーが他の場所で使用されていないことを確認するために、コードベースを検索する必要があります。 他の場所で使用されていた場合、そのすべての場所で変更が実行されます。
テキストの追加
クライアントに追加するテキストが、関連する .json
ファイルに存在する場合は、既存のキーを使用します。 それ以外の場合は、新しいキーを作成します。
英語ファイルは、同じ名前を共有する .json
ファイルすべてにとって、「真実を語る資料」です。 新しいキーを追加する必要がある場合は、そこに追加します。 そして、そのキーを すべて の translations.json
ファイルに追加します。
[!NOTE] ファイルが Crowdin で翻訳されている場合は、すべての言語に英語のテキストを使用してください。 そうしないと、テストは失敗します。
すべてのファイルで、キーを同じ順序に保つことをお勧めします。 また、コンポーネントやサーバーファイルではなくJSON ファイルに、すべての句読点、スペース、引用符などを 入れるようにしてください。
[!NOTE] アンダースコア (
_
) は、クライアント側ファイルのキー用予約文字です。 使用方法については、 ドキュメント を参照してください。