【ITニュース解説】Finding missing and unused i18next keys in a React project

ウェブアプリケーション開発において、多くのユーザーにサービスを提供するためには、多言語対応（Internationalization、略してi18n）が不可欠だ。しかし、この多言語対応は単にテキストを翻訳するだけでなく、その裏側にある「翻訳キー」というものの管理に、思わぬ落とし穴がある。翻訳キーとは、プログラムコードの中で「このテキストを表示してください」と指定するために使う、t('checkout.pay_nwo')のような文字列のことだ。このキーが、開発者にとって目に見えにくい形で多くの問題を引き起こす可能性がある。

例えば、ウェブサイトで「今すぐ支払う」というボタンがあるとする。多言語対応されたシステムでは、このボタンのテキストはt('checkout.pay_nwo')という翻訳キーを使って表示される。このキーが、フランス語ではPayer maintenant、英語ではPay nowといった具体的な翻訳テキストと紐付けられている。ところが、開発中にこのキーにスペルミスがあったり、翻訳ファイルにこのキーが抜け落ちていたりしても、多くの場合、プログラムのビルドは成功し、自動テストも問題なくパスしてしまう。その結果、本番環境でユーザーの目に触れるボタンには、翻訳されたテキストではなく「checkout.pay_nwo」という生の状態のキーがそのまま表示されてしまうのだ。これはユーザー体験を著しく損ねるだけでなく、サービスの信頼性にも関わる大きな問題となる。

翻訳キーの管理で発生しやすい問題は、大きく分けて四つある。一つ目は、「コードが参照する翻訳キーが、どの翻訳ファイルにも存在しない」というケースだ。これは、キーの入力ミスや、コードから使われなくなったキーを翻訳ファイルから削除する際にミスが発生した時に起こる。この場合、前述の通り、ユーザーは画面上で翻訳キーそのものを見てしまう。

二つ目は、「ある言語の翻訳ファイルにはキーが存在するが、別の言語のファイルには存在しない」というケースだ。例えば、英語のファイルにはcheckout.pay_nwoがあるのに、フランス語のファイルにはこのキーが存在しない場合だ。i18nextのような多くの多言語ライブラリは、特定の言語でキーが見つからない場合、自動的に別の言語（多くは英語）にフォールバック（代替）する機能を持っている。これは一見便利に思えるが、フランス語のユーザーには意図せず英語のテキストが表示され続けるため、開発者はこの問題に気づきにくく、顧客からの指摘で初めて発覚することもある。

三つ目は、「翻訳ファイルにはキーが存在するが、どのプログラムコードからも使われていない」というケースだ。これは、かつて使われていた機能の翻訳キーが、コードから削除された後も翻訳ファイルに残り続けている場合に発生する。画面上では特に問題は発生しないが、翻訳者は不要なキーの翻訳を続けることになり、無駄な作業が発生する。また、翻訳ファイル自体も不要なデータで肥大化していく。

そして四つ目は、「翻訳キーの中に含まれるプレースホルダーが、翻訳時に正しく扱われない」というケースだ。プレースホルダーとは、Hello {{name}}のように、{{name}}の部分に動的な値（例えばユーザー名）を埋め込むための仕組みだ。しかし、翻訳者がHello {{name}}をフランス語のBonjour {{nom}}のように翻訳する際に、プレースホルダーの名前自体を変えてしまうと、プログラムは正しく値を埋め込むことができず、ユーザーにはBonjour {{nom}}という、変数の名前がそのまま表示されてしまうことになる。

これらの問題は、どれもプログラムのビルドプロセスでは検出されず、テストでも見落とされやすいため、本番環境で実際にユーザーに不具合が届いてしまうまで気づかないことが多い。

これらの問題を解決するために、手動でチェックする方法も存在する。例えば、jqというコマンドとdiffコマンドを組み合わせることで、二つの翻訳ファイル（例えば英語とフランス語）のキーを比較し、どちらか一方にしか存在しないキーを洗い出すことができる。しかし、この方法は一つの名前空間、一つの言語ペアにしか使えず、多くの翻訳ファイルや言語がある大規模なプロジェクトでは非常に手間がかかる。また、未使用のキーを特定するには、全てのキーがコードのどこで使われているかを検索する必要があり、これもまた非常に困難だ。手動でのチェックは、リリース前の最終確認のような一時的な監査には役立つが、日々の開発作業には全く適していない。

そこで役立つのが、統合開発環境（IDE）のプラグインだ。「I18n Support Plus」のようなプラグインは、これらの問題の開発段階での早期発見と解決をサポートする。このプラグインを導入すると、コード内の翻訳キーの横にアイコンが表示されるようになる。このアイコンは、キーが全ての言語で適切に存在する場合は緑色、一部の言語で欠けている場合は黄色、どの言語にも存在しない場合は赤色で表示されるため、開発者は一目で問題の有無を把握できる。

また、このプラグインは翻訳キーの実際の値をインラインヒントとして表示してくれるため、翻訳ファイルを開く手間を省ける。キーにカーソルを合わせると、全ての言語での翻訳内容が一覧表示され、欠けている言語にはその旨が表示される。さらに、Ctrlキーを押しながらキーをクリックすると、直接翻訳ファイル内の該当箇所を開くことも可能だ。もし赤いアイコンのキーが見つかった場合、これはスペルミスか、まだ翻訳ファイルに登録されていないキーであることを示している。このような時でも、プラグインは簡単な操作で、欠けているキーを全ての言語の翻訳ファイルに自動的に生成してくれる機能を持つ。

開発中に翻訳キーを入力する際も、このプラグインは既存のキーを一覧表示し、補完機能を提供してくれるため、スペルミスの発生を大幅に減らすことができる。特定の言語でキーが不足している場合は、専用のツールウィンドウでそのキーを特定し、一括で不足している言語に作成する「Sync Keys」機能を使える。

手動での発見が最も難しい「未使用のキー」についても、プラグインはコード内で各キーがどれだけ参照されているかをカウントし、一度も使われていないキーを候補として提示してくれる。これにより、不要な翻訳キーを安全に削除し、翻訳ファイルの肥大化を防ぐことが可能になる。また、翻訳キーの名前を変更したい場合も、プラグインのリファクタリング機能を使えば、全ての翻訳ファイルとコード内の参照箇所を一括で更新できるため、変更によるバグのリスクを減らせる。

さらに、コード内に直接書かれたテキストを翻訳キーに変換し、全ての言語の翻訳ファイルに書き出す機能も備わっており、既存のアプリケーションを多言語対応させる際の移行作業を大幅に効率化できる。

しかし、IDEのプラグインによるチェックは、そのプラグインを導入している開発者にしか恩恵をもたらさない。チーム開発においては、全ての開発者が同じプラグインを導入しているとは限らない。そこで、IDEでのチェックと同じ内容を、コードの変更を管理するバージョン管理システム（GitHubなど）と連携する「継続的インテグレーション（CI）」の仕組みに組み込むことが重要になる。GitHub ActionsのようなCIツールを使えば、コードが変更され、開発者からプルリクエスト（コードの変更を統合するための提案）が送られた際に、自動的に翻訳キーのチェックを実行できる。

このCIジョブは、翻訳ファイルにキーが欠けていないか、プレースホルダーが正しく使われているか、コードが参照するキーが翻訳ファイルに存在するかといった項目を自動で検査する。オプションで未使用キーのチェックも実行可能だ。もし問題が検出されれば、CIジョブは失敗し、その結果がプルリクエストにコメントとして自動的に追加される。これにより、問題を引き起こした行が特定され、開発者はコードが統合される前に問題を修正できる。これは、個人の努力だけでなく、チーム全体で翻訳品質を担保するための重要な仕組みだ。

ただし、これらのツールも万能ではない。例えば、t(status.${kind})のように、プログラムの実行時に動的にキーの名前が構築されるようなケースでは、プラグインが全ての可能性を正確に追跡することは難しい場合がある。このような動的に生成されるキーは、未使用として誤って報告されるのを避けるため、チェックの対象から外されることもある。また、このプラグインはJetBrains系のIDE向けに開発されており、Visual Studio Codeなどの異なるIDEを使っている場合は、別の同等のツール（例: i18n Ally）を探す必要がある。

これらのツールは、多言語対応という複雑なタスクを、システムエンジニアが日々の開発で直面する煩わしさを解消し、より効率的で高品質なソフトウェア開発に集中できるよう支援してくれるものだ。翻訳キーの管理を自動化し、早期に問題を発見できる仕組みは、開発プロセス全体の品質と生産性を向上させる上で不可欠と言えるだろう。