feat: add compile-time i18n for log and exception messages (#17613)

Author: JackieTien97

.github/workflows/compile-check.yml

@@ -53,3 +53,7 @@ jobs:
         shell: bash
         run: |
           mvn clean package -P with-integration-tests -DskipTests -ntp
+      - name: Compiler Test (Chinese i18n)
+        shell: bash
+        run: |
+          mvn clean package -P with-integration-tests,with-zh-locale -DskipTests -ntp

CLAUDE.md

@@ -45,6 +45,9 @@ mvn clean test -pl iotdb-core/datanode -Dtest=ClassName
 # Run a single test method
 mvn clean test -pl iotdb-core/datanode -Dtest=ClassName#methodName
 
+# Build with Chinese log & error messages
+mvn clean package -pl distribution -am -DskipTests -P with-zh-locale
+
 # Format code (requires JDK 17+; auto-skipped on JDK <17)
 mvn spotless:apply
 
@@ -170,6 +173,10 @@ Generated source directories that need to be on the source path:
 - **Missing Thrift compiler**: The local machine may not have the `thrift` binary installed. Running `mvn clean package -pl <module> -am -DskipTests` will fail at the `iotdb-thrift` module. **Workaround**: To verify your changes compile, use `mvn compile -pl <module>` (without `-am` or `clean`) to leverage existing target caches.
 - **Pre-existing compilation errors in unrelated modules**: The datanode module may have pre-existing compile errors in other subsystems (e.g., pipe, copyto) that cause `mvn clean test -pl iotdb-core/datanode -Dtest=XxxTest` to fail during compilation. **Workaround**: First run `mvn compile -pl iotdb-core/datanode` to confirm your changed files compile successfully. If the errors are in files you did not modify, they are pre-existing and do not affect your changes.
 
+### i18n (Chinese Messages)
+
+The project uses compile-time i18n via the `build-helper-maven-plugin`. The property `i18n.locale` (default: `en`) controls which source directory is added: `src/main/i18n/${i18n.locale}`. Activating `-P with-zh-locale` sets `i18n.locale=zh`, swapping English message constant classes for Chinese ones. Each module that participates has both `src/main/i18n/en/` and `src/main/i18n/zh/` directories containing Java classes with identical structure but different string literals.
+
 ### Code Style
 
 - **Always run `mvn spotless:apply` after editing Java files**: Spotless runs `spotless:check` automatically during the `compile` phase. Format violations cause an immediate BUILD FAILURE. Make it a habit to run `mvn spotless:apply -pl <module>` right after editing, not at the end. For files under `integration-test/`, add `-P with-integration-tests`.

README.md

@@ -314,6 +314,16 @@ Under the iotdb/iotdb-client path:
 
 After being built, the IoTDB cli is located at the folder "cli/target".
 
+### Build with Chinese Log & Error Messages
+
+IoTDB supports compile-time internationalization (i18n) for log and error messages. By default, messages are in English. To build with Chinese messages, activate the `with-zh-locale` Maven profile:
+
+```
+> mvn clean package -pl distribution -am -DskipTests -P with-zh-locale
+```
+
+This works by swapping the source directory `src/main/i18n/en` (default) with `src/main/i18n/zh`, where each module keeps locale-specific Java constant classes containing translated message strings.
+
 ### Build Others
 
 Use `-P with-cpp` for compiling the cpp client. (For more details, read client-cpp's Readme file.)

README_ZH.md

@@ -170,6 +170,16 @@ git checkout rel/x.x
 
 编译完成后, IoTDB cli 将生成在 "cli/target".
 
+### 编译中文日志和错误信息版本
+
+IoTDB 支持编译时国际化（i18n），可将日志和错误信息切换为中文。默认编译使用英文，如需中文版本，请激活 `with-zh-locale` Maven profile：
+
+```
+> mvn clean package -pl distribution -am -DskipTests -P with-zh-locale
+```
+
+该机制通过在编译时将源码目录从 `src/main/i18n/en`（默认）替换为 `src/main/i18n/zh` 实现，各模块在对应目录下维护翻译后的 Java 消息常量类。
+
 ### 编译其他模块
 
 通过添加 `-P with-cpp` 可以进行c++客户端API的编译。

external-service-impl/mqtt/pom.xml

@@ -172,6 +172,10 @@
                     </ignoredDependencies>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>build-helper-maven-plugin</artifactId>
+            </plugin>
         </plugins>
     </build>
 </project>

external-service-impl/mqtt/src/main/i18n/en/org/apache/iotdb/mqtt/i18n/MqttMessages.java

@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.iotdb.mqtt.i18n;
+
+public final class MqttMessages {
+
+  // --- LinePayloadFormatter ---
+  public static final String INVALID_LINE_PROTOCOL = "Invalid line protocol format ,line is {}";
+  public static final String TAGS_ERROR = "The tags is error , line is {}";
+  public static final String ATTRIBUTES_ERROR = "The attributes is error , line is {}";
+  public static final String FIELDS_ERROR = "The fields is error , line is {}";
+  public static final String TIMESTAMP_ERROR = "The timestamp is error , line is {}";
+
+  // --- MPPPublishHandler ---
+  public static final String ON_PUBLISH_EXCEPTION =
+      "onPublish execution exception, msg is [{}], error is ";
+  public static final String PROCESS_RESULT = "process result: {}";
+
+  // --- MQTTService ---
+  public static final String SERVER_START_EXCEPTION = "Exception while starting server";
+  public static final String STOPPING_MQTT_SERVICE = "Stopping IoTDB MQTT service...";
+  public static final String MQTT_SERVICE_STOPPED = "IoTDB MQTT service stopped.";
+
+  // --- PayloadFormatManager ---
+  public static final String MQTT_DIR = "mqttDir: {}";
+  public static final String PAYLOAD_FORMAT_MANAGER_INIT_ERROR =
+      "MQTT PayloadFormatManager init() error.";
+  public static final String FORMATTER_IS_NULL = "PayloadFormatManager(), formatter is null.";
+  public static final String FIND_MQTT_PLUGIN =
+      "PayloadFormatManager(), find MQTT Payload Plugin {}.";
+  public static final String MQTT_PLUGIN_JAR_URLS = "MQTT Plugin jarURLs: {}";
+
+  // --- JSONPayloadFormatter ---
+  public static final String PAYLOAD_INVALID = "payload is invalidate";
+
+  private MqttMessages() {}
+}

external-service-impl/mqtt/src/main/i18n/zh/org/apache/iotdb/mqtt/i18n/MqttMessages.java

@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.iotdb.mqtt.i18n;
+
+public final class MqttMessages {
+
+  // --- LinePayloadFormatter ---
+  public static final String INVALID_LINE_PROTOCOL = "行协议格式无效，行内容：{}";
+  public static final String TAGS_ERROR = "标签格式错误，行内容：{}";
+  public static final String ATTRIBUTES_ERROR = "属性格式错误，行内容：{}";
+  public static final String FIELDS_ERROR = "字段格式错误，行内容：{}";
+  public static final String TIMESTAMP_ERROR = "时间戳格式错误，行内容：{}";
+
+  // --- MPPPublishHandler ---
+  public static final String ON_PUBLISH_EXCEPTION =
+      "onPublish 执行异常，消息为 [{}]，错误：";
+  public static final String PROCESS_RESULT = "处理结果：{}";
+
+  // --- MQTTService ---
+  public static final String SERVER_START_EXCEPTION = "启动服务器时发生异常";
+  public static final String STOPPING_MQTT_SERVICE = "正在停止 IoTDB MQTT 服务...";
+  public static final String MQTT_SERVICE_STOPPED = "IoTDB MQTT 服务已停止。";
+
+  // --- PayloadFormatManager ---
+  public static final String MQTT_DIR = "mqttDir：{}";
+  public static final String PAYLOAD_FORMAT_MANAGER_INIT_ERROR =
+      "MQTT PayloadFormatManager init() 出错。";
+  public static final String FORMATTER_IS_NULL = "PayloadFormatManager()，formatter 为 null。";
+  public static final String FIND_MQTT_PLUGIN =
+      "PayloadFormatManager()，找到 MQTT Payload 插件 {}。";
+  public static final String MQTT_PLUGIN_JAR_URLS = "MQTT 插件 jarURLs：{}";
+
+  // --- JSONPayloadFormatter ---
+  public static final String PAYLOAD_INVALID = "payload 无效";
+
+  private MqttMessages() {}
+}

external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/JSONPayloadFormatter.java

@@ -18,6 +18,8 @@
 
 package org.apache.iotdb.mqtt;
 
+import org.apache.iotdb.mqtt.i18n.MqttMessages;
+
 import com.google.common.collect.Lists;
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
@@ -79,7 +81,7 @@ public List<Message> format(String topic, ByteBuf payload) {
       }
       return messages;
     }
-    throw new JsonParseException("payload is invalidate");
+    throw new JsonParseException(MqttMessages.PAYLOAD_INVALID);
   }
 
   @Override

external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/LinePayloadFormatter.java

@@ -18,6 +18,8 @@
 
 package org.apache.iotdb.mqtt;
 
+import org.apache.iotdb.mqtt.i18n.MqttMessages;
+
 import io.netty.buffer.ByteBuf;
 import org.apache.tsfile.enums.TSDataType;
 import org.apache.tsfile.external.commons.lang3.NotImplementedException;
@@ -83,7 +85,7 @@ public List<Message> format(String topic, ByteBuf payload) {
       try {
         Matcher matcher = pattern.matcher(line.trim());
         if (!matcher.matches()) {
-          log.warn("Invalid line protocol format ,line is {}", line);
+          log.warn(MqttMessages.INVALID_LINE_PROTOCOL, line);
           continue;
         }
 
@@ -95,25 +97,25 @@ public List<Message> format(String topic, ByteBuf payload) {
 
         // Parsing Tags
         if (!setTags(matcher, message)) {
-          log.warn("The tags is error , line is {}", line);
+          log.warn(MqttMessages.TAGS_ERROR, line);
           continue;
         }
 
         // Parsing Attributes
         if (!setAttributes(matcher, message)) {
-          log.warn("The attributes is error , line is {}", line);
+          log.warn(MqttMessages.ATTRIBUTES_ERROR, line);
           continue;
         }
 
         // Parsing Fields
         if (!setFields(matcher, message)) {
-          log.warn("The fields is error , line is {}", line);
+          log.warn(MqttMessages.FIELDS_ERROR, line);
           continue;
         }
 
         // Parsing timestamp
         if (!setTimestamp(matcher, message)) {
-          log.warn("The timestamp is error , line is {}", line);
+          log.warn(MqttMessages.TIMESTAMP_ERROR, line);
           continue;
         }
 

external-service-impl/mqtt/src/main/java/org/apache/iotdb/mqtt/MPPPublishHandler.java

@@ -43,6 +43,7 @@
 import org.apache.iotdb.db.queryengine.plan.statement.crud.InsertRowStatement;
 import org.apache.iotdb.db.queryengine.plan.statement.crud.InsertTabletStatement;
 import org.apache.iotdb.db.utils.CommonUtils;
+import org.apache.iotdb.mqtt.i18n.MqttMessages;
 import org.apache.iotdb.rpc.TSStatusCode;
 import org.apache.iotdb.service.rpc.thrift.TSProtocolVersion;
 
@@ -159,7 +160,7 @@ public void onPublish(InterceptPublishMessage msg) {
         }
       }
     } catch (Throwable t) {
-      LOG.warn("onPublish execution exception, msg is [{}], error is ", msg, t);
+      LOG.warn(MqttMessages.ON_PUBLISH_EXCEPTION, msg, t);
     } finally {
       // release the payload of the message
       super.onPublish(msg);
@@ -191,7 +192,7 @@ private void insertTable(TableMessage message, MqttClientSession session) {
 
       tsStatus = result.status;
       if (LOG.isDebugEnabled()) {
-        LOG.debug("process result: {}", tsStatus);
+        LOG.debug(MqttMessages.PROCESS_RESULT, tsStatus);
       }
       if (tsStatus.getCode() != TSStatusCode.SUCCESS_STATUS.getStatusCode()
           && tsStatus.getCode() != TSStatusCode.REDIRECTION_RECOMMEND.getStatusCode()) {
@@ -310,7 +311,7 @@ private void insertTree(TreeMessage message, MqttClientSession session) {
                     false);
         tsStatus = result.status;
         if (LOG.isDebugEnabled()) {
-          LOG.debug("process result: {}", tsStatus);
+          LOG.debug(MqttMessages.PROCESS_RESULT, tsStatus);
         }
         if (tsStatus.getCode() != TSStatusCode.SUCCESS_STATUS.getStatusCode()
             && tsStatus.getCode() != TSStatusCode.REDIRECTION_RECOMMEND.getStatusCode()) {