Thymeleaf中文网

深色模式

使用th:text与文本外部化 ​

文本外部化（Externalizing text） 指将模板代码中的文本片段提取到模板文件之外，存储在独立文件中（通常是 .properties 属性文件），以便轻松替换为其他语言的等效文本（这个过程称为“国际化”，简称 i18n）。被外部化的文本片段通常称为“消息（messages）”。

每条消息都有一个唯一标识的键（key），Thymeleaf 允许你通过 #{...} 语法指定文本对应某条特定消息：

html
<p th:text="#{home.welcome}">Welcome to our grocery store!</p>

这里实际体现了 Thymeleaf 标准方言（Standard Dialect）的两个核心特性：

  1. th:text 属性：会计算其值表达式的结果，并将结果设置为宿主标签的文本内容，最终替换代码中“Welcome to our grocery store!”这段默认文本；
  2. #{home.welcome} 表达式：遵循“标准表达式语法”，指示 th:text 属性要使用的文本，是与模板处理时所用语言环境（locale） 匹配的、键为 home.welcome 的消息。

外部化文本存储在哪里？ ​

Thymeleaf 中外部化文本的存储位置是完全可配置的，具体取决于所使用的 org.thymeleaf.messageresolver.IMessageResolver 接口实现类。通常会使用基于 .properties 文件的实现，但你也可以自定义实现（比如从数据库中读取消息）。

不过我们在初始化模板引擎时，并未指定自定义的消息解析器，这意味着应用会使用 Thymeleaf 内置的 标准消息解析器（Standard Message Resolver）（由 org.thymeleaf.messageresolver.StandardMessageResolver 实现）。

标准消息解析器会在模板所在目录下，查找与模板同名的属性文件来匹配对应语言的消息，以 /WEB-INF/templates/home.html 为例：

  • /WEB-INF/templates/home_en.properties：英文文本；
  • /WEB-INF/templates/home_es.properties：西班牙语文本；
  • /WEB-INF/templates/home_pt_BR.properties：葡萄牙语（巴西）文本；
  • /WEB-INF/templates/home.properties：默认文本（当语言环境不匹配时使用）。

我们来看 home_es.properties 文件的内容：

properties
home.welcome=¡Bienvenido a nuestra tienda de comestibles!

以上就是让 Thymeleaf 处理模板文本所需的全部配置，接下来我们可以创建首页控制器（Home Controller）了。

核心概念解释 ​

  1. 文本外部化的核心价值：
    • 解耦模板与文本内容，无需修改模板代码即可实现多语言切换；
    • 便于文本统一管理（比如由翻译人员单独维护 .properties 文件）。
  2. 标准消息解析器的匹配规则：
    • 优先匹配“模板名_语言代码_国家代码.properties”（如 home_pt_BR.properties）；
    • 若无匹配，降级匹配“模板名_语言代码.properties”（如 home_es.properties）；
    • 最后使用无后缀的 home.properties 作为默认兜底。
  3. th:text 与默认文本的关系：
    • 模板未被 Thymeleaf 处理时（如直接打开 HTML），显示标签内的默认文本；
    • 模板被处理时，th:text 会用 ${...} 表达式结果或 #{...} 消息值替换默认文本，体现“自然模板”特性。

总结 ​

  1. 文本外部化通过 .properties 文件存储多语言文本，配合 #{消息键} 表达式实现国际化，是 Thymeleaf 处理多语言的核心方式。
  2. 标准消息解析器默认在模板同目录下查找同名属性文件，按“语言+国家→仅语言→默认”的优先级匹配消息。
  3. th:text 负责将消息表达式的结果渲染为标签文本，标签内的默认文本保证了静态原型的可读性。