Merge pull request #7665 from lafirest/chore/chinese_desc_api_check_retainer

chore(retainer): add i18n conf

apps/emqx_retainer/i18n/emqx_retainer_api_i18n.conf

@@ -0,0 +1,143 @@
+emqx_retainer_api {
+
+  get_config_api {
+    desc {
+      en: "View config"
+      zh: "查看配置内容"
+      }
+    }
+
+  config_content {
+    desc {
+      en: "The config content"
+      zh: "配置内容"
+      }
+    }
+
+  config_not_found {
+    desc {
+      en: "Config not found."
+      zh: "配置不存在"
+      }
+    }
+
+  update_retainer_api {
+    desc {
+      en: "Update retainer config."
+      zh: "更新配置"
+      }
+    }
+
+  update_config_success {
+    desc {
+      en: "Update configs successfully."
+      zh: "配置更新成功"
+      }
+    }
+
+  update_config_failed {
+    desc {
+      en: "Update config failed"
+      zh: "配置更新失败"
+      }
+    }
+
+  list_retained_api {
+    desc {
+      en: "List retained messages."
+      zh: "查看保留消息列表"
+      }
+    }
+
+  retained_list {
+    desc {
+      en: "Retained messages list."
+      zh: "保留消息列表"
+      }
+    }
+
+  unsupported_backend {
+    desc {
+      en: "Unsupported backend."
+      zh: "不支持的后端"
+      }
+    }
+
+  lookup_api {
+    desc {
+      en: "Lookup a message by a topic without wildcards."
+      zh: "通过不带通配符的主题查看对应的保留消息"
+      }
+    }
+
+  message_detail {
+    desc {
+      en: "Details of the message."
+      zh: "消息详情"
+      }
+    }
+
+  message_not_exist {
+    desc {
+      en: "Viewed message doesn't exist."
+      zh: "消息不存在"
+      }
+    }
+
+  delete_matching_api {
+    desc {
+      en: "Delete matching messages."
+      zh: "删除对应的消息"
+      }
+    }
+
+  topic {
+    desc {
+      en: "Topic."
+      zh: "主题"
+      }
+    }
+
+  msgid {
+    desc {
+      en: "Message ID."
+      zh: "消息 ID"
+      }
+    }
+
+  qos {
+    desc {
+      en: "QoS."
+      zh: "QoS"
+      }
+    }
+
+  publish_at {
+    desc {
+      en: "Message publish time, RFC 3339 format."
+      zh: "消息发送时间, RFC 3339 格式"
+      }
+    }
+
+  from_clientid {
+    desc {
+      en: "The clientid of publisher."
+      zh: "发布者的 ClientID"
+      }
+    }
+
+  from_username {
+    desc {
+      en: "The username of publisher."
+      zh: "发布者的用户名"
+      }
+    }
+
+  payload {
+    desc {
+      en: "Payload."
+      zh: "消息内容"
+      }
+    }
+
+}

apps/emqx_retainer/i18n/emqx_retainer_i18n.conf

@@ -0,0 +1,107 @@
+emqx_retainer_schema {
+
+  enable {
+    desc {
+      en: "Enable retainer feature"
+      zh: "是否开启消息保留功能"
+      }
+    }
+
+  msg_expiry_interval {
+    desc {
+      en: "Message retention time. 0 means message will never be expired."
+      zh: "消息保留时间。0 代表永久保留"
+      }
+    }
+
+  flow_control {
+    desc {
+      en: "flow control."
+      zh: "流控设置"
+      }
+    }
+
+  msg_clear_interval {
+    desc {
+      en: """Periodic interval for cleaning up expired messages.
+Never clear if the value is 0.
+      """
+      zh: "消息清理间隔。0 代表不进行清理"
+      }
+    }
+
+  max_payload_size {
+    desc {
+      en: "Maximum retained message size."
+      zh: "消息大小最大值"
+      }
+    }
+
+  stop_publish_clear_msg {
+    desc {
+      en: """When the retained flag of the `PUBLISH` message is set and Payload is empty,
+whether to continue to publish the message.
+See:
+http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718038"""
+      zh: """是否不发送保留消息的清理消息，在 MQTT 5.0 中如果一条保留消息的消息体为空，则会清除掉之前存储
+的对应的保留消息，通过这个值控制是否停止发送清理消息"""
+      }
+    }
+
+  backend {
+    desc {
+      en: "Settings for the database storing the retained messages."
+      zh: "保留消息的存储后端"
+      }
+    }
+
+  mnesia_config_type {
+    desc {
+      en: "Backend type."
+      zh: "后端类型"
+      }
+    }
+
+  mnesia_config_storage_type {
+    desc {
+      en: "Specifies whether the messages are stored in RAM or persisted on disc."
+      zh: "选择消息是存放在磁盘还是内存中"
+      }
+    }
+
+  max_retained_messages {
+    desc {
+      en: "Maximum number of retained messages. 0 means no limit."
+      zh: "消息保留的数量上限。0 表示无限"
+      }
+    }
+
+  batch_read_number {
+    desc {
+      en: "Size of the batch when reading messages from storage. 0 means no limit."
+      zh: "从存储后端批量加载时的每批数量上限，0 代表一次性读取"
+      }
+    }
+
+  batch_deliver_number {
+    desc {
+      en: "The number of retained messages can be delivered per batch."
+      zh: "批量派发时每批的数量。0 代表一次性全部派发"
+      }
+    }
+
+  batch_deliver_limiter {
+    desc {
+      en: """The rate limiter name for retained messages' delivery.
+Limiter helps to avoid delivering too many messages to the client at once, which may cause the client to block or crash, or drop messages due to exceeding the size of the message queue.
+The names of the available rate limiters are taken from the existing rate limiters under `limiter.batch`.
+If this field is empty, limiter is not used."""
+      zh: """批量发送的限流器的名称。
+限流器可以用来防止短时间内向客户端发送太多的消息，从而避免过多的消息导致客户端队列堵塞甚至崩溃。
+这个名称需要是指向 `limiter.batch` 下的一个真实存在的限流器。
+如果这个字段为空，则不使用限流器。
+      """
+      }
+    }
+
+}

apps/emqx_retainer/src/emqx_retainer_api.erl

@@ -20,6 +20,7 @@
 
 -include_lib("emqx/include/emqx.hrl").
 -include_lib("typerefl/include/types.hrl").
+-include_lib("hocon/include/hoconsc.hrl").
 
 %% API
 -export([api_spec/0, paths/0, schema/1, namespace/0, fields/1]).
@@ -51,19 +52,19 @@ schema(?PREFIX) ->
         'operationId' => config,
         get => #{
             tags => ?TAGS,
-            description => <<"Get retainer config">>,
+            description => ?DESC(get_config_api),
             responses => #{
-                200 => mk(conf_schema(), #{desc => "The config content"}),
-                404 => error_codes(['NOT_FOUND'], <<"Config not found">>)
+                200 => mk(conf_schema(), #{desc => ?DESC(config_content)}),
+                404 => error_codes(['NOT_FOUND'], ?DESC(config_not_found))
             }
         },
         put => #{
             tags => ?TAGS,
-            description => <<"Update retainer config">>,
-            'requestBody' => mk(conf_schema(), #{desc => "The config content"}),
+            description => ?DESC(update_retainer_api),
+            'requestBody' => mk(conf_schema(), #{desc => ?DESC(config_content)}),
             responses => #{
-                200 => mk(conf_schema(), #{desc => "Update configs successfully"}),
-                400 => error_codes(['UPDATE_FAILED'], <<"Update config failed">>)
+                200 => mk(conf_schema(), #{desc => ?DESC(update_config_success)}),
+                400 => error_codes(['UPDATE_FAILED'], ?DESC(update_config_failed))
             }
         }
     };
@@ -72,11 +73,11 @@ schema(?PREFIX ++ "/messages") ->
         'operationId' => lookup_retained_warp,
         get => #{
             tags => ?TAGS,
-            description => <<"List retained messages">>,
+            description => ?DESC(list_retained_api),
             parameters => page_params(),
             responses => #{
-                200 => mk(array(ref(message_summary)), #{desc => "The result list"}),
-                400 => error_codes(['BAD_REQUEST'], <<"Unsupported backend">>)
+                200 => mk(array(ref(message_summary)), #{desc => ?DESC(retained_list)}),
+                400 => error_codes(['BAD_REQUEST'], ?DESC(unsupported_backend))
             }
         }
     };
@@ -85,23 +86,23 @@ schema(?PREFIX ++ "/message/:topic") ->
         'operationId' => with_topic_warp,
         get => #{
             tags => ?TAGS,
-            description => <<"Lookup a message by a topic without wildcards">>,
+            description => ?DESC(lookup_api),
             parameters => parameters(),
             responses => #{
-                200 => mk(ref(message), #{desc => "Details of the message"}),
-                404 => error_codes(['NOT_FOUND'], <<"Viewed message doesn't exist">>),
-                400 => error_codes(['BAD_REQUEST'], <<"Unsupported backend">>)
+                200 => mk(ref(message), #{desc => ?DESC(message_detail)}),
+                404 => error_codes(['NOT_FOUND'], ?DESC(message_not_exist)),
+                400 => error_codes(['BAD_REQUEST'], ?DESC(unsupported_backend))
             }
         },
         delete => #{
             tags => ?TAGS,
-            description => <<"Delete matching messages">>,
+            description => ?DESC(delete_matching_api),
             parameters => parameters(),
             responses => #{
                 204 => <<>>,
                 400 => error_codes(
                     ['BAD_REQUEST'],
-                    <<"Unsupported backend">>
+                    ?DESC(unsupported_backend)
                 )
             }
         }
@@ -119,22 +120,22 @@ parameters() ->
             mk(binary(), #{
                 in => path,
                 required => true,
-                desc => "The target topic"
+                desc => ?DESC(topic)
             })}
     ].
 
 fields(message_summary) ->
     [
-        {msgid, mk(binary(), #{desc => <<"Message ID">>})},
-        {topic, mk(binary(), #{desc => "The topic"})},
-        {qos, mk(emqx_schema:qos(), #{desc => "The QoS"})},
-        {publish_at, mk(string(), #{desc => "Publish datetime, in RFC 3339 format"})},
-        {from_clientid, mk(binary(), #{desc => "Publisher ClientId"})},
-        {from_username, mk(binary(), #{desc => "Publisher Username"})}
+        {msgid, mk(binary(), #{desc => ?DESC(msgid)})},
+        {topic, mk(binary(), #{desc => ?DESC(topic)})},
+        {qos, mk(emqx_schema:qos(), #{desc => ?DESC(qos)})},
+        {publish_at, mk(string(), #{desc => ?DESC(publish_at)})},
+        {from_clientid, mk(binary(), #{desc => ?DESC(from_clientid)})},
+        {from_username, mk(binary(), #{desc => ?DESC(from_username)})}
     ];
 fields(message) ->
     [
-        {payload, mk(binary(), #{desc => "The payload content"})}
+        {payload, mk(binary(), #{desc => ?DESC(payload)})}
         | fields(message_summary)
     ].
 

apps/emqx_retainer/src/emqx_retainer_schema.erl

@@ -1,62 +1,57 @@
 -module(emqx_retainer_schema).
 
 -include_lib("typerefl/include/types.hrl").
+-include_lib("hocon/include/hoconsc.hrl").
 
 -export([roots/0, fields/1, desc/1, namespace/0]).
 
--define(TYPE(Type), hoconsc:mk(Type)).
-
 namespace() -> "retainer".
 
 roots() -> ["retainer"].
 
 fields("retainer") ->
     [
-        {enable, sc(boolean(), "Enable retainer feature.", false)},
+        {enable, sc(boolean(), enable, false)},
         {msg_expiry_interval,
             sc(
                 emqx_schema:duration_ms(),
-                "Message retention time. 0 means message will never be expired.",
+                msg_expiry_interval,
                 "0s"
             )},
         {msg_clear_interval,
             sc(
                 emqx_schema:duration_ms(),
-                "Periodic interval for cleaning up expired messages. "
-                "Never clear if the value is 0.",
+                msg_clear_interval,
                 "0s"
             )},
-        {flow_control, ?TYPE(hoconsc:ref(?MODULE, flow_control))},
+        {flow_control, sc(hoconsc:ref(?MODULE, flow_control), flow_control)},
         {max_payload_size,
             sc(
                 emqx_schema:bytesize(),
-                "Maximum retained message size.",
+                max_payload_size,
                 "1MB"
             )},
         {stop_publish_clear_msg,
             sc(
                 boolean(),
-                "When the retained flag of the `PUBLISH` message is set and Payload is empty, "
-                "whether to continue to publish the message.<br/>"
-                "See: "
-                "http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718038",
+                stop_publish_clear_msg,
                 false
             )},
         {backend, backend_config()}
     ];
 fields(mnesia_config) ->
     [
-        {type, hoconsc:mk(hoconsc:union([built_in_database]), #{desc => "Backend type."})},
+        {type, sc(hoconsc:union([built_in_database]), mnesia_config_type, built_in_database)},
         {storage_type,
             sc(
                 hoconsc:union([ram, disc]),
-                "Specifies whether the messages are stored in RAM or persisted on disc.",
+                mnesia_config_storage_type,
                 ram
             )},
         {max_retained_messages,
             sc(
                 integer(),
-                "Maximum number of retained messages. 0 means no limit.",
+                max_retained_messages,
                 0,
                 fun is_pos_integer/1
             )}
@@ -66,27 +61,20 @@ fields(flow_control) ->
         {batch_read_number,
             sc(
                 integer(),
-                "Size of the batch when reading messages from storage. 0 means no limit.",
+                batch_read_number,
                 0,
                 fun is_pos_integer/1
             )},
         {batch_deliver_number,
             sc(
                 range(0, 1000),
-                "The number of retained messages can be delivered per batch.",
+                batch_deliver_number,
                 0
             )},
         {batch_deliver_limiter,
             sc(
                 emqx_limiter_schema:bucket_name(),
-                "The rate limiter name for retained messages' delivery.<br/>"
-                "Limiter helps to avoid delivering too many messages to the client at once, "
-                "which may cause the client "
-                "to block or crash, or drop messages due to exceeding the size of the message"
-                " queue.<br/>"
-                "The names of the available rate limiters are taken from the existing rate "
-                "limiters under `limiter.batch`.<br/>"
-                "If this field is empty, limiter is not used.",
+                batch_deliver_limiter,
                 undefined
             )}
     ].
@@ -103,13 +91,16 @@ desc(_) ->
 %%--------------------------------------------------------------------
 %% Internal functions
 %%--------------------------------------------------------------------
-sc(Type, Desc, Default) ->
-    hoconsc:mk(Type, #{default => Default, desc => Desc}).
+sc(Type, DescId) ->
+    hoconsc:mk(Type, #{required => true, desc => ?DESC(DescId)}).
+
+sc(Type, DescId, Default) ->
+    hoconsc:mk(Type, #{default => Default, desc => ?DESC(DescId)}).
 
-sc(Type, Desc, Default, Validator) ->
+sc(Type, DescId, Default, Validator) ->
     hoconsc:mk(Type, #{
         default => Default,
-        desc => Desc,
+        desc => ?DESC(DescId),
         validator => Validator
     }).
 
@@ -117,7 +108,8 @@ is_pos_integer(V) ->
     V >= 0.
 
 backend_config() ->
-    #{
-        type => hoconsc:union([hoconsc:ref(?MODULE, mnesia_config)]),
-        desc => "Settings for the database storing the retained messages."
-    }.
+    sc(
+        hoconsc:union([hoconsc:ref(?MODULE, mnesia_config)]),
+        backend,
+        mnesia_config
+    ).