refactor(i18n): #376

Author: iohao

common/common-core/src/main/java/com/iohao/game/action/skeleton/protocol/HeadMetadata.java

@@ -33,6 +33,8 @@
 import java.io.Serializable;
 
 /**
+ * Meta information
+ * <p>
  * 元信息
  *
  * @author 渔民小镇
@@ -66,6 +68,11 @@ public final class HeadMetadata implements Serializable {
     int cmdMerge;
 
     /**
+     * Source logic server client ID
+     * <p>
+     * If the request is initiated by an external server,
+     * this value should be the external server's clientId (a server's unique identifier).
+     * <p>
      * 来源逻辑服 client id
      * <pre>
      *     比如是对外服发起的请求，这个来源就是对外服的 clientId
@@ -77,6 +84,17 @@ public final class HeadMetadata implements Serializable {
     int sourceClientId;
 
     /**
+     * Target logic server endPointClientId
+     * Used to specify which server should process the request
+     * <p>
+     * For example, with two chess servers (game logic servers) A and B:
+     * When players Player1 and Player2 are in a match, if they started playing on Chess Server A,
+     * then all subsequent requests must be assigned to Chess Server A for processing.
+     * <p>
+     * endPointClientId refers to the server's unique identifier.
+     * <p>
+     * see {@link com.iohao.game.common.kit.HashKit}
+     * <p>
      * 目标逻辑服 endPointClientId
      * <pre>
      *     用于指定请求由哪个服务器处理
@@ -108,15 +126,23 @@ public final class HeadMetadata implements Serializable {
     byte rpcCommandType;
 
     /**
-     * 扩展字段
-     * <pre>
-     *     开发者有特殊业务可以通过这个字段来扩展元信息，该字段的信息会跟随每一个请求；
-     * </pre>
+     * Extended field. Developers can use this field to extend meta-information for special business needs.
+     * The data in this field will be included with every request.
+     * <p>
+     * 扩展字段，开发者有特殊业务可以通过这个字段来扩展元信息，该字段的信息会跟随每一个请求。
      */
     byte[] attachmentData;
 
     /**
-     * netty 的 channelId。
+     * netty channelId
+     * <p>
+     * The framework stores Netty's channelId to allow the external server to look up the corresponding connection.
+     * <p>
+     * After a player logs in, the framework will use the player's userId to locate the corresponding connection (channel) instead of the channelId,
+     * because the channelId string is too long, and transmitting this value to the logic server each time would slightly impact performance.
+     * <p>
+     * Once the player logs in, the framework will no longer use this property.
+     * However, if needed, developers can repurpose this field for their own use.
      * <pre>
      *     框架存放 netty 的 channelId 是为了能在对外服查找到对应的连接。
      *     当玩家登录后，框架将会使用玩家的 userId 来查找对应的连接（channel），而不是 channelId ；
@@ -130,39 +156,69 @@ public final class HeadMetadata implements Serializable {
     /** 消息标记号；由前端请求时设置，服务器响应时会携带上 */
     int msgId;
 
-    /** 框架自用字段。将来变化可能较大，开发者请不要使用。 */
+    /**
+     * Framework's internal fields. Future changes are likely to be significant, so developers should refrain from using them.
+     * <p>
+     * 框架自用字段。将来变化可能较大，开发者请不要使用。
+     */
     int stick;
 
     /**
+     * The IDs of multiple game logic servers bound to the player
+     * <pre>
+     *     All requests related to this game logic server will be routed to the bound game logic server for processing.
+     *     Even if multiple game logic servers of the same type are running, requests will still be directed to the originally bound server.
+     * </pre>
+     * <p>
      * 玩家绑定的多个游戏逻辑服 id
      * <pre>
      *     所有与该游戏逻辑服相关的请求都将被分配给已绑定的游戏逻辑服处理。
      *     即使启动了多个同类型的游戏逻辑服，该请求仍将被分配给已绑定的游戏逻辑服处理。
      * </pre>
      */
     int[] bindingLogicServerIds;
-    /** 框架自用字段。将来变化可能较大，开发者请不要使用。 */
+    /**
+     * Framework's internal fields. Future changes are likely to be significant, so developers should refrain from using them.
+     * <p>
+     * 框架自用字段。将来变化可能较大，开发者请不要使用。
+     */
     int cacheCondition;
     /**
-     * 自定义数据，专为开发者预留的一个字段，开发者可以利用该字段来传递自定义数据
-     * <pre>
-     *     该字段由开发者自己定义，框架不会对数据做任何处理，也不会做任何检查，
-     *     开发者可以利用该字段来传递任何数据，包括自定义对象。
-     * </pre>
+     * Custom data, a field reserved specifically for developers.
+     * Developers can use this field to pass custom data.
+     * The field is entirely user-defined—the framework will neither process nor validate its contents.
+     * Developers can leverage it to transmit any data, including custom objects.
+     * <p>
+     * 自定义数据，专为开发者预留的一个字段，开发者可以利用该字段来传递自定义数据。
+     * 该字段由开发者自己定义，框架不会对数据做任何处理，也不会做任何检查，开发者可以利用该字段来传递任何数据，包括自定义对象。
      */
     byte[] customData;
-    /** 所选执行器 */
     ExecutorSelectEnum executorSelect;
-    /** traceId */
     String traceId;
-    /** 框架自用字段。将来变化可能较大，开发者请不要使用。 */
+    /**
+     * Framework's internal fields. Future changes are likely to be significant, so developers should refrain from using them.
+     * <p>
+     * 框架自用字段。将来变化可能较大，开发者请不要使用。
+     */
     byte[] userProcessorExecutorSelectorBytes;
-    /** 临时变量 */
+    /**
+     * Temporary variable
+     * <p>
+     * 临时变量
+     */
     transient Object other;
     transient int withNo;
-    /** 请求命令类型: 0 心跳，1 业务 */
+    /**
+     * Request command type: 0 Heartbeat, 1 Business
+     * <p>
+     * 请求命令类型: 0 心跳，1 业务
+     */
     transient int cmdCode;
-    /** 协议开关，用于一些协议级别的开关控制，比如 安全加密校验等。 : 0 不校验 */
+    /**
+     * Protocol switch: Used for protocol-level control (e.g., security encryption verification). 0: No verification
+     * <p>
+     * 协议开关，用于一些协议级别的开关控制，比如 安全加密校验等。 : 0 不校验
+     */
     transient int protocolSwitch;
     /** 预留 inet */
     @Ignore
@@ -176,18 +232,6 @@ public HeadMetadata setCmdInfo(CmdInfo cmdInfo) {
         return this;
     }
 
-    /**
-     * 得到 cmdInfo 命令路由信息
-     * <pre>
-     *     如果只是为了获取 cmd 与 subCmd，下面的方式效率会更高
-     *     cmd = CmdKit.getCmd(cmdMerge);
-     *     subCmd = CmdKit.getSubCmd(cmdMerge);
-     *
-     *     但实际上更推荐使用 CmdInfo，这样使得代码书写简洁，也更容易理解，毕竟代码是给人看的。
-     * </pre>
-     *
-     * @return cmdInfo
-     */
     public CmdInfo getCmdInfo() {
         return CmdInfo.of(this.cmdMerge);
     }
@@ -198,16 +242,18 @@ public HeadMetadata setCmdMerge(int cmdMerge) {
     }
 
     /**
-     * 类似 clone
+     * Simple clone
      * <p>
-     * 使用场景
+     * Usage scenario （使用场景）
      * <pre>
-     *     与其他游戏逻辑服通信时可以使用
-     *     方法中给 HeadMetadata 赋值了玩家的必要属性：
+     *     Can be used when communicating with other game logic servers.
+     *     The method assigns necessary player attributes to HeadMetadata.
+     *
+     *     （与其他游戏逻辑服通信时可以使用，方法中给 HeadMetadata 赋值了玩家的必要属性）
      *     userId、attachmentData、channelId、bindingLogicServerIds、customData
      *     traceId、executorSelect
      * </pre>
-     * 以下属性不会赋值，如有需要，请自行赋值
+     * Unassigned by default. Set manually when required. （以下属性不会赋值，如有需要，请自行赋值）
      * <pre>
      *     cmdMerge
      *     sourceClientId

common/common-core/src/main/resources/iohao.properties

@@ -3,7 +3,7 @@ gameExternalServer=GameExternalServer
 cmdName=Routing
 # see BrokerClientNodeInfo.java
 gameServerAmount=Number of servers
-# ExternalJoinEnum
+# ExternalJoinEnum.java
 connectionWay=Connection way
 # about brokerServer
 gameBrokerServer=GameBrokerServer
@@ -37,15 +37,15 @@ timeRangeInOutHourTitle=%d:00 execute[%s];
 timeRangeInOutMinuteTitle=[%d~%d minutes, execute:%d]
 # see ActionCommandRegions.java
 cmdMergeLimit=%s exceeds the maximum default value. Please set the capacity manually if necessary. Default maximum capacity %d, current capacity %d
-# see ProtobufCheckActionParserListener
+# see ProtobufCheckActionParserListener.java
 protobufAnnotationCheck=Note that the protocol class does not have the ProtobufClass annotation added
-# see TextDocumentGenerate
+# see TextDocumentGenerate.java
 textDocumentTitle=Game Document Format Description
 textDocumentBroadcastTitle=Other broadcast interfaces
 textDocumentCmd=Routing
 textDocumentBroadcast=Broadcast
 textDocumentErrorCodeTitle=Error Code
-# see DefaultUserHook
+# see DefaultUserHook.java
 userHookInto=[PlayerOnline] CountOnline
 userHookQuit=[PlayerOffline] CountOnline
 # see InternalAboutFlowContext.java

common/common-core/src/main/resources/iohao_zh_CN.properties

@@ -3,7 +3,7 @@ gameExternalServer=游戏对外服
 cmdName=路由
 # see BrokerClientNodeInfo.java
 gameServerAmount=服务器的数量
-# ExternalJoinEnum
+# ExternalJoinEnum.java
 connectionWay=连接方式
 # about brokerServer
 gameBrokerServer=游戏网关(Broker)
@@ -37,17 +37,16 @@ timeRangeInOutHourTitle=%d:00 共 %s 次;
 timeRangeInOutMinuteTitle=[%d~%d分钟，%d 次]
 # see ActionCommandRegions.java
 cmdMergeLimit=%s 超过最大默认值，如有需要请手动设置容量。默认最大容量 %d. 当前容量 %d
-# see ProtobufCheckActionParserListener
+# see ProtobufCheckActionParserListener.java
 protobufAnnotationCheck=注意，协议类没有添加 ProtobufClass 注解
-# see TextDocumentGenerate
+# see TextDocumentGenerate.java
 textDocumentTitle=游戏文档格式说明
 textDocumentBroadcastTitle=其它广播推送
 textDocumentCmd=路由
 textDocumentBroadcast=广播
 textDocumentErrorCodeTitle=错误码
-# see DefaultUserHook
+# see DefaultUserHook.java
 userHookInto=[玩家上线] 在线数量
 userHookQuit=[玩家下线] 在线数量
 # see InternalAboutFlowContext.java
 bindingUserId=请登录后使用该方法. see FlowContext.bindingUserId.
-

common/common-validation/src/main/java/com/iohao/game/common/validation/Validation.java

@@ -77,7 +77,7 @@ public Validator getValidator() throws Exception {
             ClassScanner classScanner = new ClassScanner(packageName, clazz -> clazz.getName().equals(className));
             List<Class<?>> classList = classScanner.listScan();
             if (classList.isEmpty()) {
-                throw new Exception("缺少类: " + className);
+                throw new ClassNotFoundException(className);
             }
 
             Class<?> clazz = classList.getFirst();
@@ -101,7 +101,7 @@ private String getValidatorClassName() {
         try {
             className = ResourceKit.readStr(fileName, StandardCharsets.UTF_8);
         } catch (Exception e) {
-            log.info("读取 {} 失败，将使用默认类 {} 来处理", fileName, defaultValidator);
+            log.info("Use the default class {} to handle it because reading {} failed.", defaultValidator, fileName);
         }
 
         if (StringUtils.isBlank(className)) {

external/external-core/src/main/java/com/iohao/game/external/core/session/UserSession.java

@@ -27,13 +27,13 @@
 import com.iohao.game.external.core.message.ExternalCodecKit;
 
 /**
- * UserSession 接口
- * <pre>
- *     对应的动态属性接口 {@link UserSessionOption}
- * </pre>
+ * UserSession interface
+ * <p>
+ * UserSession 接口， 对应的动态属性接口 {@link UserSessionOption}
  *
  * @author 渔民小镇
  * @date 2023-02-18
+ * @see UserSessionOption UserSessionOption for dynamic properties
  */
 public interface UserSession extends AttrOptionDynamic {
     /**
@@ -61,38 +61,46 @@ public interface UserSession extends AttrOptionDynamic {
     long getUserId();
 
     /**
+     * authVerified
+     * <p>
      * 是否进行身份验证
      *
-     * @return true 已经身份验证了，表示登录过了。
+     * @return true: logged in. （true 已经身份验证了，表示登录过了。）
      */
     boolean isVerifyIdentity();
 
     /**
-     * 当前用户（玩家）的 State
+     * UserSessionState of current player
      *
-     * @return 当前用户（玩家）的 State
+     * @return State
      */
     UserSessionState getState();
 
     /**
+     * UserChannelId of current player
+     * <p>
      * 当前用户（玩家）的 UserChannelId
      *
-     * @return 当前用户（玩家）的 UserChannelId
+     * @return UserChannelId
      */
     UserChannelId getUserChannelId();
 
     /**
+     * Adds user info to request.
+     * <p>
+     * Developers can extend data via HeadMetadata.setAttachmentData(byte[]), which will be forwarded to the logic server.
+     * <p>
      * 给请求消息加上一些 user 自身的数据
-     * <pre>
-     *     如果开发者要扩展数据，可通过 {@link HeadMetadata#setAttachmentData(byte[])} 字段来扩展
-     *     这些数据可以传递到逻辑服
-     * </pre>
+     * <p>
+     * 如果开发者要扩展数据，可通过 {@link HeadMetadata#setAttachmentData(byte[])} 字段来扩展，这些数据可以传递到逻辑服
      *
-     * @param requestMessage 请求消息
+     * @param requestMessage requestMessage
      */
     void employ(BarMessage requestMessage);
 
     /**
+     * Attach user data to HeadMetadata
+     * <p>
      * 给 HeadMetadata 加上一些 user 自身的数据
      *
      * @param headMetadata HeadMetadata
@@ -108,16 +116,18 @@ public interface UserSession extends AttrOptionDynamic {
     <T> T writeAndFlush(Object message);
 
     /**
-     * 获取玩家 ip
+     * Get player IP
      *
      * @return 玩家 ip
      */
     String getIp();
 
     /**
+     * Creates RequestMessage with user's own info.
+     * <p>
      * 创建 RequestMessage，内部会将 User 自身的相关信息设置到 RequestMessage 中。
      *
-     * @param cmdInfo 路由
+     * @param cmdInfo cmdInfo
      * @return RequestMessage
      * @since 21.15
      */