Merge pull request #7685 from lafirest/feat/chinese_desc_api_exhook

feat(exhook): add i18n support

apps/emqx_exhook/i18n/emqx_exhook_api_i18n.conf

@@ -0,0 +1,177 @@
+emqx_exhook_api {
+
+  list_all_servers {
+    desc {
+      en: "List all servers"
+      zh: "查看ExHook 服务器列表"
+    }
+  }
+
+  add_server {
+    desc {
+      en: "Add a server"
+      zh: "添加 ExHook 服务器"
+    }
+  }
+
+  get_detail {
+    desc {
+      en: "Get the detail information of Exhook server"
+      zh: "查看 Exhook 服务器详细信息"
+    }
+  }
+
+  update_server {
+    desc {
+      en: "Update the server"
+      zh: "更新 Exhook 服务器"
+    }
+  }
+
+  delete_server {
+    desc {
+      en: "Delete the server"
+      zh: "删除 Exhook 服务器"
+    }
+  }
+
+  get_hooks {
+    desc {
+      en: "Get the hooks information of server"
+      zh: "获取 Exhook 服务器的钩子信息"
+    }
+  }
+
+  move_api {
+    desc {
+      en: """Move the server.
+NOTE: The position should be \"front | rear | before:{name} | after:{name}"""
+      zh: """移动 Exhook 服务器顺序。
+注意: 移动的参数只能是：front | rear | before:{name} | after:{name}"""
+    }
+  }
+
+  move_position {
+    desc {
+      en: "The target position to be moved"
+      zh: "移动的方向"
+    }
+  }
+
+  hook_name {
+    desc {
+      en: "The hook's name"
+      zh: "钩子的名称"
+    }
+  }
+
+  server_name {
+    desc {
+      en: "The Exhook server name"
+      zh: "Exhook 服务器的名称"
+    }
+  }
+
+  hook_params {
+    desc {
+      en: "The parameters used when the hook is registered"
+      zh: "钩子注册时使用的参数"
+    }
+  }
+
+  server_metrics {
+    desc {
+      en: "Metrics information of this server in the current node"
+      zh: "当前节点中该服务器的指标信息"
+    }
+  }
+
+  node_metrics {
+    desc {
+      en: "Metrics information of this server in all nodes"
+      zh: "所有节点中该服务器的指标信息"
+    }
+  }
+
+  node_status {
+    desc {
+      en: "status of this server in all nodes"
+      zh: "所有节点中该服务器的状态信息"
+    }
+  }
+
+  hook_metrics {
+    desc {
+      en: "Metrics information of this hook in the current node"
+      zh: "当前节点中该钩子的指标信息"
+    }
+  }
+
+  node_hook_metrics {
+    desc {
+      en: "Metrics information of this hook in all nodes"
+      zh: "所有节点中该钩子的指标信息"
+    }
+  }
+
+  node {
+    desc {
+      en: "Node name"
+      zh: "节点名称"
+    }
+  }
+
+  metrics {
+    desc {
+      en: "Metrics information"
+      zh: "指标信息"
+    }
+  }
+
+  status {
+    desc {
+      en: """The status of Exhook server.
+connected: connection succeeded
+connecting: connection failed, reconnecting
+unconnected: failed to connect and didn't reconnect
+disable: this server is disabled
+error: failed to view the status of this server
+"""
+      zh: """Exhook 服务器的状态。
+connected: 连接成功
+connecting: 连接失败，重连中
+unconnected: 连接失败，且未设置自动重连
+disable: 该服务器未开启
+error: 查看该服务器状态时发生错误"""
+    }
+  }
+
+  metric_succeed {
+    desc {
+      en: "The number of times the hooks execution successful"
+      zh: "钩子执行成功的次数"
+    }
+  }
+
+  metric_failed {
+    desc {
+      en: "The number of times the hook execution failed"
+      zh: "钩子执行失败的次数"
+    }
+  }
+
+  metric_rate {
+    desc {
+      en: "The call rate of hooks"
+      zh: "钩子的调用速率"
+    }
+  }
+
+  metric_max_rate {
+    desc {
+      en: "Maximum call rate of hooks"
+      zh: "钩子的最大调用速率"
+    }
+  }
+
+}

apps/emqx_exhook/i18n/emqx_exhook_i18n.conf

@@ -0,0 +1,62 @@
+emqx_exhook_schema {
+
+  servers {
+    desc {
+      en: "List of exhook servers"
+      zh: "ExHook 服务器列表"
+    }
+  }
+
+  name {
+    desc {
+      en: "Name of the exhook server"
+      zh: "ExHook 服务器名称"
+    }
+  }
+
+  enable {
+    desc {
+      en: "Enable this Exhook server"
+      zh: "开启这个 Exhook 服务器"
+    }
+  }
+
+  url {
+    desc {
+      en: "URL of the gRPC server"
+      zh: "gRPC 服务器地址"
+    }
+  }
+
+  request_timeout {
+    desc {
+      en: "The timeout of request gRPC server"
+      zh: "gRPC 服务器请求超时时间"
+    }
+  }
+
+  failed_action {
+    desc {
+      en: "The value that is returned when the request to the gRPC server fails for any reason"
+      zh: "当 gRPC 请求失败后的操作"
+    }
+  }
+
+  auto_reconnect {
+    desc {
+      en: """Whether to automatically reconnect (initialize) the gRPC server.
+When gRPC is not available, Exhook tries to request the gRPC service at that interval and reinitialize the list of mounted hooks."""
+      zh: """自动重连到 gRPC 服务器的设置。
+当 gRPC 服务器不可用时，Exhook 将会按照这里设置的间隔时间进行重连，并重新初始化注册的钩子"""
+    }
+  }
+
+  pool_size {
+    desc {
+      en: "The process pool size for gRPC client"
+      zh: "gRPC 客户端进程池大小"
+    }
+  }
+
+
+}

apps/emqx_exhook/src/emqx_exhook_api.erl

@@ -21,6 +21,7 @@
 -include("emqx_exhook.hrl").
 -include_lib("typerefl/include/types.hrl").
 -include_lib("emqx/include/logger.hrl").
+-include_lib("hocon/include/hoconsc.hrl").
 
 -export([api_spec/0, paths/0, schema/1, fields/1, namespace/0]).
 
@@ -56,12 +57,12 @@ schema(("/exhooks")) ->
         'operationId' => exhooks,
         get => #{
             tags => ?TAGS,
-            desc => <<"List all servers">>,
+            desc => ?DESC(list_all_servers),
             responses => #{200 => mk(array(ref(detail_server_info)), #{})}
         },
         post => #{
             tags => ?TAGS,
-            desc => <<"Add a servers">>,
+            desc => ?DESC(add_server),
             'requestBody' => server_conf_schema(),
             responses => #{
                 201 => mk(ref(detail_server_info), #{}),
@@ -74,7 +75,7 @@ schema("/exhooks/:name") ->
         'operationId' => action_with_name,
         get => #{
             tags => ?TAGS,
-            desc => <<"Get the detail information of server">>,
+            desc => ?DESC(get_detail),
             parameters => params_server_name_in_path(),
             responses => #{
                 200 => mk(ref(detail_server_info), #{}),
@@ -83,7 +84,7 @@ schema("/exhooks/:name") ->
         },
         put => #{
             tags => ?TAGS,
-            desc => <<"Update the server">>,
+            desc => ?DESC(update_server),
             parameters => params_server_name_in_path(),
             'requestBody' => server_conf_schema(),
             responses => #{
@@ -94,7 +95,7 @@ schema("/exhooks/:name") ->
         },
         delete => #{
             tags => ?TAGS,
-            desc => <<"Delete the server">>,
+            desc => ?DESC(delete_server),
             parameters => params_server_name_in_path(),
             responses => #{
                 204 => <<>>,
@@ -107,7 +108,7 @@ schema("/exhooks/:name/hooks") ->
         'operationId' => server_hooks,
         get => #{
             tags => ?TAGS,
-            desc => <<"Get the hooks information of server">>,
+            desc => ?DESC(get_hooks),
             parameters => params_server_name_in_path(),
             responses => #{
                 200 => mk(array(ref(list_hook_info)), #{}),
@@ -120,9 +121,7 @@ schema("/exhooks/:name/move") ->
         'operationId' => move,
         post => #{
             tags => ?TAGS,
-            desc =>
-                <<"Move the server.\n",
-                    "NOTE: The position should be \"front|rear|before:{name}|after:{name}\"\n">>,
+            desc => ?DESC(move_api),
             parameters => params_server_name_in_path(),
             'requestBody' => emqx_dashboard_swagger:schema_with_examples(
                 ref(move_req),
@@ -140,53 +139,47 @@ fields(move_req) ->
     [
         {position,
             mk(string(), #{
-                desc => <<"The target position to be moved.">>,
+                required => true,
+                desc => ?DESC(move_position),
                 example => <<"front">>
             })}
     ];
 fields(detail_server_info) ->
     [
-        {metrics, mk(ref(metrics), #{})},
-        {node_metrics, mk(array(ref(node_metrics)), #{})},
-        {node_status, mk(array(ref(node_status)), #{})},
+        {metrics, mk(ref(metrics), #{desc => ?DESC(server_metrics)})},
+        {node_metrics, mk(array(ref(node_metrics)), #{desc => ?DESC(node_metrics)})},
+        {node_status, mk(array(ref(node_status)), #{desc => ?DESC(node_status)})},
         {hooks, mk(array(ref(hook_info)), #{})}
     ] ++ emqx_exhook_schema:server_config();
 fields(list_hook_info) ->
     [
-        {name, mk(binary(), #{desc => <<"The hook's name">>})},
-        {params,
-            mk(
-                map(name, binary()),
-                #{desc => <<"The parameters used when the hook is registered">>}
-            )},
-        {metrics, mk(ref(metrics), #{})},
-        {node_metrics, mk(array(ref(node_metrics)), #{})}
+        {name, mk(binary(), #{desc => ?DESC(hook_name)})},
+        {params, mk(map(name, binary()), #{desc => ?DESC(hook_params)})},
+        {metrics, mk(ref(metrics), #{desc => ?DESC(hook_metrics)})},
+        {node_metrics, mk(array(ref(node_metrics)), #{desc => ?DESC(node_hook_metrics)})}
     ];
 fields(node_metrics) ->
     [
-        {node, mk(string(), #{})},
-        {metrics, mk(ref(metrics), #{})}
+        {node, mk(string(), #{desc => ?DESC(node)})},
+        {metrics, mk(ref(metrics), #{desc => ?DESC(metrics)})}
     ];
 fields(node_status) ->
     [
-        {node, mk(string(), #{})},
-        {status, mk(enum([connected, connecting, unconnected, disable, error]), #{})}
+        {node, mk(string(), #{desc => ?DESC(node)})},
+        {status,
+            mk(enum([connected, connecting, unconnected, disable, error]), #{desc => ?DESC(status)})}
     ];
 fields(hook_info) ->
     [
-        {name, mk(binary(), #{desc => <<"The hook's name">>})},
-        {params,
-            mk(
-                map(name, binary()),
-                #{desc => <<"The parameters used when the hook is registered">>}
-            )}
+        {name, mk(binary(), #{desc => ?DESC(hook_name)})},
+        {params, mk(map(name, binary()), #{desc => ?DESC(hook_params)})}
     ];
 fields(metrics) ->
     [
-        {succeed, mk(integer(), #{})},
-        {failed, mk(integer(), #{})},
-        {rate, mk(integer(), #{})},
-        {max_rate, mk(integer(), #{})}
+        {succeed, mk(integer(), #{desc => ?DESC(metric_succeed)})},
+        {failed, mk(integer(), #{desc => ?DESC(metric_failed)})},
+        {rate, mk(integer(), #{desc => ?DESC(metric_rate)})},
+        {max_rate, mk(integer(), #{desc => ?DESC(metric_max_rate)})}
     ];
 fields(server_config) ->
     emqx_exhook_schema:server_config().
@@ -195,6 +188,7 @@ params_server_name_in_path() ->
     [
         {name,
             mk(string(), #{
+                desc => ?DESC(server_name),
                 in => path,
                 required => true,
                 example => <<"default">>

apps/emqx_exhook/src/emqx_exhook_schema.erl

@@ -23,6 +23,7 @@
 -dialyzer(no_fail_call).
 
 -include_lib("typerefl/include/types.hrl").
+-include_lib("hocon/include/hoconsc.hrl").
 
 -behaviour(hocon_schema).
 
@@ -45,7 +46,7 @@ fields(exhook) ->
                 hoconsc:array(ref(server)),
                 #{
                     default => [],
-                    desc => "List of exhook servers."
+                    desc => ?DESC(servers)
                 }
             )}
     ];
@@ -54,27 +55,27 @@ fields(server) ->
         {name,
             sc(
                 binary(),
-                #{desc => "Name of the exhook server."}
+                #{required => true, desc => ?DESC(name)}
             )},
         {enable,
             sc(
                 boolean(),
                 #{
                     default => true,
-                    desc => "Enable the exhook server."
+                    desc => ?DESC(enable)
                 }
             )},
         {url,
             sc(
                 binary(),
-                #{desc => "URL of the gRPC server."}
+                #{required => true, desc => ?DESC(url)}
             )},
         {request_timeout,
             sc(
                 duration(),
                 #{
                     default => "5s",
-                    desc => "The timeout to request gRPC server."
+                    desc => ?DESC(request_timeout)
                 }
             )},
         {failed_action, failed_action()},
@@ -84,10 +85,7 @@ fields(server) ->
                 hoconsc:union([false, duration()]),
                 #{
                     default => "60s",
-                    desc =>
-                        "Whether to automatically reconnect (initialize) the gRPC server.<br/>"
-                        "When gRPC is not available, exhook tries to request the gRPC service at "
-                        "that interval and reinitialize the list of mounted hooks."
+                    desc => ?DESC(auto_reconnect)
                 }
             )},
         {pool_size,
@@ -96,7 +94,7 @@ fields(server) ->
                 #{
                     default => 8,
                     example => 8,
-                    desc => "The process pool size for gRPC client."
+                    desc => ?DESC(pool_size)
                 }
             )}
     ];
@@ -124,9 +122,7 @@ failed_action() ->
         hoconsc:enum([deny, ignore]),
         #{
             default => deny,
-            desc =>
-                "The value that is returned when the request "
-                "to the gRPC server fails for any reason."
+            desc => ?DESC(failed_action)
         }
     ).