feat: add compile-time i18n for log and exception messages

.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()) {

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

@@ -22,6 +22,7 @@
 import org.apache.iotdb.db.conf.IoTDBConfig;
 import org.apache.iotdb.db.conf.IoTDBDescriptor;
 import org.apache.iotdb.externalservice.api.IExternalService;
+import org.apache.iotdb.mqtt.i18n.MqttMessages;
 
 import io.moquette.BrokerConstants;
 import io.moquette.broker.Server;
@@ -62,7 +63,7 @@ public void startup() {
     try {
       server.startServer(config, handlers, null, authenticator, null);
     } catch (IOException e) {
-      throw new RuntimeException("Exception while starting server", e);
+      throw new RuntimeException(MqttMessages.SERVER_START_EXCEPTION, e);
     }
 
     LOG.info(
@@ -74,9 +75,9 @@ public void startup() {
         .addShutdownHook(
             new Thread(
                 () -> {
-                  LOG.info("Stopping IoTDB MQTT service...");
+                  LOG.info(MqttMessages.STOPPING_MQTT_SERVICE);
                   shutdown();
-                  LOG.info("IoTDB MQTT service stopped.");
+                  LOG.info(MqttMessages.MQTT_SERVICE_STOPPED);
                 }));
   }
 

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

@@ -20,6 +20,7 @@
 
 import org.apache.iotdb.commons.file.SystemFileFactory;
 import org.apache.iotdb.db.conf.IoTDBDescriptor;
+import org.apache.iotdb.mqtt.i18n.MqttMessages;
 
 import com.google.common.base.Preconditions;
 import org.apache.tsfile.external.commons.io.FileUtils;
@@ -54,13 +55,13 @@ private PayloadFormatManager() {}
 
   private static void init() {
     mqttDir = IoTDBDescriptor.getInstance().getConfig().getMqttDir();
-    logger.info("mqttDir: {}", mqttDir);
+    logger.info(MqttMessages.MQTT_DIR, mqttDir);
 
     try {
       makeMqttPluginDir();
       buildMqttPluginMap();
     } catch (IOException e) {
-      logger.error("MQTT PayloadFormatManager init() error.", e);
+      logger.error(MqttMessages.PAYLOAD_FORMAT_MANAGER_INIT_ERROR, e);
     }
   }
 
@@ -83,17 +84,17 @@ private static void buildMqttPluginMap() throws IOException {
         ServiceLoader.load(PayloadFormatter.class, PayloadFormatManager.class.getClassLoader());
     for (PayloadFormatter formatter : payloadFormatters) {
       if (formatter == null) {
-        logger.error("PayloadFormatManager(), formatter is null.");
+        logger.error(MqttMessages.FORMATTER_IS_NULL);
         continue;
       }
 
       String pluginName = formatter.getName();
       mqttPayloadPluginMap.put(pluginName, formatter);
-      logger.info("PayloadFormatManager(), find MQTT Payload Plugin {}.", pluginName);
+      logger.info(MqttMessages.FIND_MQTT_PLUGIN, pluginName);
     }
 
     URL[] jarURLs = getPluginJarURLs(mqttDir);
-    logger.debug("MQTT Plugin jarURLs: {}", Arrays.toString(jarURLs));
+    logger.debug(MqttMessages.MQTT_PLUGIN_JAR_URLS, Arrays.toString(jarURLs));
 
     for (URL jarUrl : jarURLs) {
       ClassLoader classLoader = new URLClassLoader(new URL[] {jarUrl});
@@ -104,7 +105,7 @@ private static void buildMqttPluginMap() throws IOException {
 
       for (PayloadFormatter formatter : payloadFormatters2) {
         if (formatter == null) {
-          logger.error("PayloadFormatManager(), formatter is null.");
+          logger.error(MqttMessages.FORMATTER_IS_NULL);
           continue;
         }
 
@@ -113,7 +114,7 @@ private static void buildMqttPluginMap() throws IOException {
           continue;
         }
         mqttPayloadPluginMap.put(pluginName, formatter);
-        logger.info("PayloadFormatManager(), find MQTT Payload Plugin {}.", pluginName);
+        logger.info(MqttMessages.FIND_MQTT_PLUGIN, pluginName);
       }
     }
   }

external-service-impl/rest/pom.xml

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