【Thymeleaf】画面に日本語を表示すると文字化け？その対策方法を初心者向けに解説！

新人と先輩の会話形式で理解しよう

新人

「先輩、Thymeleafを使って画面に日本語を表示しようとしたら、文字化けしてしまいました…」

先輩

「それはよくある問題だよ。日本語の文字化けは、エンコーディング設定が正しくないと起きやすいんだ。」

新人

「設定って、どこを見直せばいいんですか？」

先輩

「じゃあ、Thymeleafでの日本語の文字化けについて、原因と対策を順番に説明していこうか。」

1. 日本語の文字化けとは？

Thymeleafを使ったSpring BootのWebアプリケーション開発で、画面に日本語を表示したときに「????」や「ããã«ã¡ã¯」のように意味不明な文字列が出てしまうことがあります。これが「文字化け」です。

例えば、HTMLテンプレートで次のように書いた場合に文字化けが起こることがあります。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>こんにちは</title>
</head>
<body>
    <p th:text="'こんにちは、世界！'"></p>
</body>
</html>

このような記述をしても、エンコーディングが適切でなければ、実際のブラウザ表示で日本語が正しく表示されず、文字化けが発生してしまいます。

2. 文字化けが起きる主な原因

Thymeleafで日本語が文字化けする主な原因は、以下のような「エンコーディング設定の不一致」にあります。

① HTMLファイルの文字コードがUTF-8になっていない

HTMLファイル自体の文字コードがUTF-8以外で保存されていると、Thymeleafで出力される文字列が文字化けしてしまうことがあります。Pleiadesで作業する場合でも、テンプレートファイル（.html）をUTF-8で保存する必要があります。

② `@Controller`のレスポンスで正しいエンコーディングが指定されていない

Spring Bootの@Controllerを使っている場合、ビューに渡される日本語の値が適切にエンコードされないと、ブラウザで文字化けする原因になります。

例えば、以下のようなコードで文字列を渡す場合です。


@Controller
public class HelloController {

    @GetMapping("/hello")
    public String hello(Model model) {
        model.addAttribute("message", "こんにちは、Springの世界！");
        return "hello";
    }
}

③ テンプレートエンジン（Thymeleaf）の設定ミス

Spring BootでThymeleafを使っている場合、application.propertiesに以下のような記述が必要です。これを入れないと、出力されるHTMLのエンコーディングがUTF-8ではなくなり、文字化けが発生することがあります。


spring.thymeleaf.encoding=UTF-8
spring.thymeleaf.content-type=text/html; charset=UTF-8
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true

④ テンプレートのmetaタグにエンコーディングが指定されていない

HTMLテンプレートの<head>内に正しく<meta charset="UTF-8">が記載されていないと、ブラウザ側で文字コードを誤認識し、日本語が文字化けします。

必ず以下のように書いておきましょう。


<head>
    <meta charset="UTF-8">
    <title>Thymeleaf 日本語テスト</title>
</head>

⑤ ビルドツール（Gradle）での文字コード設定が不完全

PleiadesでGradleを使っている場合、build.gradleにUTF-8の指定がないと、ビルドされたテンプレートやJavaファイルが正しくエンコードされません。

次のように明示しておくことが重要です。


tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

これで、Javaソースのコンパイル時にもUTF-8が適用され、日本語の取り扱いに関するトラブルを未然に防ぐことができます。

3. HTMLのmetaタグでエンコーディングを指定する方法

Thymeleafで作成するHTMLテンプレートには、<meta>タグを使って文字コードを明示的に指定することがとても大切です。特に初心者の場合、この設定を忘れることで日本語の文字化けが起きることが多くあります。

HTMLファイルの<head>タグ内に次のように書くことで、ブラウザに「このファイルはUTF-8で書かれています」と伝えることができます。


<head>
    <meta charset="UTF-8">
    <title>日本語テスト</title>
</head>

このmeta charset="UTF-8"という指定がないと、ブラウザが自動で別の文字コードを適用してしまい、日本語が「????」や「�」といった形で文字化けしてしまう原因になります。

また、<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">という形式もありますが、現在は<meta charset="UTF-8">の方が推奨されています。よりシンプルでわかりやすいため、初心者の方にはこちらを使うことをおすすめします。

4. Thymeleafテンプレートのファイル保存時の文字コード（UTF-8）に注意

Thymeleafで使うテンプレートファイル（.htmlファイル）は、Pleiadesのエディタで作成したときに、正しい文字コードで保存されていないと、どんなに正しい記述をしていても日本語が文字化けしてしまいます。

特にWindows環境では、デフォルトで「Shift-JIS」や「MS932」で保存されてしまうことがあります。これを防ぐためには、Pleiadesのエディタで文字コードを「UTF-8」に設定して保存する必要があります。

設定方法は以下の通りです。

テンプレートファイルを右クリック
「プロパティ」を選択
「リソース」→「テキスト・ファイル・エンコーディング」→「その他」を選び、「UTF-8」に変更

この設定をしていないと、HTML内でいくらmeta charset="UTF-8"を指定していても、ファイル自体が別の文字コードで保存されているため、ブラウザで表示されたときに日本語が崩れてしまうのです。

また、Gradleプロジェクトで作業している場合、Gradleのビルド時にテンプレートファイルが正しい文字コードで扱われるようにするためにも、UTF-8で保存しておくことは基本中の基本です。

5. Springの設定ファイル（application.properties）での文字コード指定方法

Spring BootでThymeleafを使用して日本語を表示する場合、application.propertiesにエンコーディングに関する設定を追加しておくと、より確実に文字化けを防ぐことができます。

以下のように、resourcesのエンコーディングと、Thymeleafテンプレートの出力に関する設定を行います。


# ThymeleafテンプレートのエンコーディングをUTF-8に指定
spring.thymeleaf.encoding=UTF-8

# コンテンツタイプにUTF-8を含めて指定
spring.thymeleaf.content-type=text/html; charset=UTF-8

# HTTPレスポンスのエンコーディング設定
spring.http.encoding.charset=UTF-8
spring.http.encoding.enabled=true
spring.http.encoding.force=true

これらの設定を入れておくことで、Springが出力するすべてのレスポンスに「UTF-8」を適用し、日本語が正しく表示されるようになります。

特にspring.http.encoding.force=trueを指定することで、アプリケーションの起動時に必ずUTF-8でレスポンスを返すようになり、環境によってエンコーディングが変わってしまうという問題を防ぐことができます。

Spring Bootでは、設定ファイルが非常に重要です。初心者の方も早めにapplication.propertiesを使いこなせるようになると、今後の開発がスムーズになります。

また、これらの設定が正しく反映されているかを確認するには、実際にブラウザで画面を開き、ページのソース（Ctrl+U）を見て、meta charset="UTF-8"が出力されているかチェックするのも良い方法です。

6. よくあるミスと解決方法（HTMLファイルの保存形式・BOMあり/なしなど）

Thymeleafで日本語が文字化けする原因として、初心者が見落としがちな点が「ファイル保存形式」です。特に重要なのが「BOM付きUTF-8」か「BOMなしUTF-8」かという違いです。

BOMとは「Byte Order Mark」の略で、ファイルの先頭に付加される特殊な識別子です。WindowsでファイルをUTF-8で保存すると、自動的にBOM付きになることがありますが、これがThymeleafで処理される際に問題を起こすケースがあります。

HTMLテンプレートファイルを保存するときには、必ず「UTF-8（BOMなし）」で保存するようにしましょう。Pleiadesで保存形式を確認するには、以下のように操作します。

対象のHTMLファイルを右クリック
「プロパティ」→「リソース」タブを開く
「テキスト・ファイル・エンコーディング」で「その他：UTF-8」を選択

さらに、BOM付きで保存されてしまったファイルは、他のエディタ（Visual Studio Codeなど）を使ってBOMを削除し、保存し直すことも可能です。

実務では、BOMがついているかどうかを意識することは少ないかもしれませんが、日本語の文字化け対策としては非常に大切なチェックポイントです。

7. 実務で使えるチェックポイント（ブラウザの表示確認・開発ツールの使い方）

Thymeleafで日本語を表示したときに文字化けしていないかを確認するには、単にブラウザで見た目を確認するだけでは不十分な場合があります。より確実にチェックするためには、開発ツールやデベロッパーツールを活用しましょう。

ここでは、実務で使える代表的なチェック方法を紹介します。

① ブラウザのソース表示（Ctrl + U）を確認する

ブラウザでページを表示したあと、キーボードの「Ctrl + U」を押すと、そのページのHTMLソースを見ることができます。ここで、<meta charset="UTF-8"> が記述されているかを確認してください。

② ブラウザの開発者ツールでHTTPレスポンスヘッダーを確認

ブラウザの「開発者ツール」（F12キー）を開き、「Network（ネットワーク）」タブを選びます。該当のHTMLリクエストをクリックすると、「Headers（ヘッダー）」情報が表示されます。

ここで、「Content-Type: text/html; charset=UTF-8」がレスポンスヘッダーに含まれていれば、ThymeleafのテンプレートとSpring Bootの設定が正しく働いていることが確認できます。

③ 実際に表示された日本語の文字を観察する

一見して問題がなさそうに見えても、「ひらがな」や「漢字」が「?（はてなマーク）」や「黒い菱形の中に白い？マーク」などに変わっている場合は、エンコーディングに何かしらの不具合がある可能性があります。

このような症状が出たときは、テンプレートファイルの保存形式、metaタグの設定、application.properties、Gradleの設定などを順番に見直してみましょう。

8. 今後の開発で気をつけたいエンコーディングの基本ルール

日本語の文字化けを防ぐためには、ThymeleafやSpring Bootの設定に加えて、日常的な開発作業の中でもエンコーディングに対する意識を持つことが大切です。ここでは、今後のWeb開発で意識したい基本ルールをまとめておきます。

① すべてのファイルは「UTF-8（BOMなし）」で統一

HTML、Java、propertiesファイルなど、プロジェクト内のすべてのテキストファイルはUTF-8で保存しましょう。BOM付きにならないよう、設定を見直す習慣をつけておくと安心です。

② Gradleビルドでもエンコーディングを明示的に設定

Gradleでは、以下のようにビルド時の文字コード設定を追加することで、日本語が正しく扱われるようになります。


tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

③ Springのapplication.propertiesでUTF-8を指定

すでに紹介したように、application.propertiesにはThymeleafやHTTPレスポンスに関するエンコーディング設定を忘れず記述しましょう。

④ HTMLテンプレートには必ずmetaタグを

テンプレートファイルの<head>内に<meta charset="UTF-8">を必ず記述するようにし、ブラウザに正しい文字コードを伝えましょう。

⑤ Pleiadesの設定も確認

Pleiadesでは、プロジェクトのプロパティやファイル単位で文字コードが設定できます。ファイルごとに設定がばらばらにならないよう、プロジェクト全体をUTF-8で統一しておくことが望ましいです。

⑥ 開発チーム全体でルールを共有する

初心者にとっても重要なのが、チーム内で「すべてUTF-8で保存する」というルールを明文化しておくことです。ルールが統一されていないと、プロジェクトの一部で文字化けが発生してしまう原因になります。

これらの基本を日頃から意識しておくことで、Thymeleafを使ったSpring BootのWebアプリ開発においても、安心して日本語を扱うことができます。初心者のうちは特に、テンプレートファイルの保存形式やエンコーディング設定などに細かく注意を払うことが、スムーズな開発につながります。