rename & relocate zh-CN.md

dianping · Sep 28, 2018 · d5b2f02 · d5b2f02
1 parent 17a7033
commit d5b2f02
Show file tree

Hide file tree

Showing 22 changed files with 218 additions and 145 deletions.
diff --git a/lib/README.md b/lib/README.md
@@ -1,14 +1,17 @@
 # Cat Client
 
+[中文文档](./README.zh-CN.md)
+
 ## Overview
 
 The following programming languages are supported:
 
-* C
-* C++
-* Python
-* Go
-* Node.js
+* [Java](./java)
+* [C](./c)
+* [C++](./cpp)
+* [Python](./python)
+* [Go](./go)
+* [Node.js](./node.js)
 
 And the following programming languages are in our plan:
 
@@ -31,15 +34,15 @@ And the following programming languages are in our plan:
 
 * type
 
-    Represents a category of message, like `SQL`, `RPC` or `HTTP`.
+    Represents the category of a message, like `SQL`, `RPC` or `HTTP`.
 
 * name
 
-    Represents a specified action, for example
+    Represents a specified action, for example:
 
-    * If the **type** is `SQL`, the **name** may be `select <?> from user where id = <?>`, which is the base SQL.
-    * If the **type** is `RPC`, the **name** may be `QueryOrderByUserId(string, int)`, which is the signature of an api.
-    * If the **type** is `HTTP`, the **name** may be `/api/v8/{int}/orders`, which is the base uri.
+    * If the **type** is `SQL`, the **name** could be `select <?> from user where id = <?>`, which is the base SQL.
+    * If the **type** is `RPC`, the **name** could be `QueryOrderByUserId(string, int)`, which is the signature of an api.
+    * If the **type** is `HTTP`, the **name** could be `/api/v8/{int}/orders`, which is the base uri.
 
    > Detailed information should be recorded in the **data** field, like the parameters of an API.
 
@@ -53,11 +56,11 @@ And the following programming languages are in our plan:
 
     Record the detailed information about a message.
 
-    * If the **type** is `SQL`, the **data** may be `id=75442432`
-    * If the **type** is `RPC`, the **data** may be `userType=dianping&userId=9987`
-    * If the **type** is `HTTP`, the **data** may be `orderId=75442432`
+    * If the **type** is `SQL`, the **data** could be `id=75442432`
+    * If the **type** is `RPC`, the **data** could be `userType=dianping&userId=9987`
+    * If the **type** is `HTTP`, the **data** could be `orderId=75442432`
 
-    `data` field may also contain `error stack trace` in some cases. (like represent an exception or an error)
+    `data` field may also contain `error stack traces` in some cases. (like represent an exception or an error)
 
 * timestamp
 

diff --git a/lib/_/zh-CN.md → lib/README.zh-CN.md b/lib/_/zh-CN.md → lib/README.zh-CN.md
@@ -1,14 +1,15 @@
 # Cat Client
 
-## Overview
+## 总览
 
 我们目前支持以下编程语言：
 
-* C
-* C++
-* Python
-* Go
-* Node.js
+* [Java](./java/README.zh-CN.md)
+* [C](./c/README.zh-CN.md)
+* [C++](./cpp/README.zh-CN.md)
+* [Python](./python/README.zh-CN.md)
+* [Go](./go/README.zh-CN.md)
+* [Node.js](./node.js/README.zh-CN.md)
 
 以下编程语言在我们的支持计划中：
 
@@ -37,9 +38,9 @@
 
     表示一个特定的行为，举例来说：
 
-	* 如果 **type** 是 `SQL`, **name** 可以是 `select <?> from user where id = <?>`, 表示一个 SQL 模版。
-	* 如果 **type** 是 `RPC`, **name** 可以是 `QueryOrderByUserId(string, int)`, 表示一个 API 的函数签名。
-	* 如果 **type** 是 `HTTP`, **name** 可以是 `/api/v8/{int}/orders`, 表示基础 URI。
+    * 如果 **type** 是 `SQL`, **name** 可以是 `select <?> from user where id = <?>`, 表示一个 SQL 模版。
+    * 如果 **type** 是 `RPC`, **name** 可以是 `QueryOrderByUserId(string, int)`, 表示一个 API 的函数签名。
+    * 如果 **type** 是 `HTTP`, **name** 可以是 `/api/v8/{int}/orders`, 表示基础 URI。
 
    > 更详细的信息建议在 **data** 字段中记录，比如 api 的参数
 
@@ -53,9 +54,9 @@
 
     记录一个消息的详细信息
 
-	* 如果 **type** 是 `SQL`, **data** 可以是 `id=75442432`
-	* 如果 **type** 是 `RPC`, **data** 可以是 `userType=dianping&userId=9987`
-	* 如果 **type** 是 `HTTP`, **data** 可以是 `orderId=75442432`
+    * 如果 **type** 是 `SQL`, **data** 可以是 `id=75442432`
+    * 如果 **type** 是 `RPC`, **data** 可以是 `userType=dianping&userId=9987`
+    * 如果 **type** 是 `HTTP`, **data** 可以是 `orderId=75442432`
 
     在一些情况下，`data` 字段会包含错误堆栈信息（比如代表一个 exception 或者 error）
 
@@ -73,7 +74,7 @@
 
     会在 transaction 被完成时计算。
 
-	> duration = currentTimestamp() - durationStart
+    > duration = currentTimestamp() - durationStart
 
     你可以通过相关 API 在 transaction 被完成前指定 `duration` 的值，并且跳过计算过程。
 

diff --git a/lib/_/preparations.md b/lib/_/preparations.md
@@ -8,7 +8,7 @@
 
     This directory is used for preserving debug logs, which can be very useful while debugging, **read and write** permission is also required.
 
-3. Create `/data/appdatas/cat/client.xml` with following contents.
+3. Create `/data/appdatas/cat/client.xml` with the following contents.
 
     ```xml
     <?xml version="1.0" encoding="utf-8"?>

diff --git a/lib/c/README.md b/lib/c/README.md
@@ -1,8 +1,8 @@
 # Cat Client for C
 
-[中文文档](./docs/zh-CN.md)
+[中文文档](./README.zh-CN.md)
 
-The cat client can be compiled and used on both Linux (both glibc and musl-libc) and OSX.
+The `ccat` can be compiled and used on both Linux (both glibc and musl-libc) and OSX.
 
 The following Operating Systems are tested:
 
@@ -47,7 +47,7 @@ gcc -lcatclient x.c
 
 ## Initialization
 
-Some [preparations](../_/preparations.md) needs to be done before initialize `ccat`.
+Some [preparations](../_/preparations.md) needs to be done before initializing `ccat`.
 
 With all the preparations have been done, it's easy to initialize `ccat` in your c codes.
 
@@ -59,7 +59,7 @@ catClientInit("appkey");
 
 > Only English characters (a-z, A-Z), numbers (0-9), underscore (\_) and dash (-) is allowed in appkey.
 
-Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [apidoc](./docs/api.md).
+Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [API doc](./docs/api.md).
 
 ## Documentation
 

diff --git a/lib/c/docs/zh-CN.md → lib/c/README.zh-CN.md b/lib/c/docs/zh-CN.md → lib/c/README.zh-CN.md
@@ -1,6 +1,6 @@
 # Cat Client for C
 
-`ccat` 同时支持 linux (glibc 和 musl-libc) 和 osx 两个平台。
+`ccat` 同时支持 Linux (glibc 和 musl-libc) 和 OSX 两个平台。
 
 下述列出的操作系统是经过测试可用的：
 
@@ -12,7 +12,7 @@
 * Ubuntu 16.04 LTS
 * Ubuntu 18.04 LTS
 
-我们也提供了 c++ 版本的客户端，参考 [cppcat](../../cpp/docs/zh-CN.md)
+我们也提供了 c++ 版本的客户端，参考 [cppcat](../cpp/README.zh-CN.md)
 
 ## 编译
 
@@ -62,4 +62,4 @@ catClientInit("appkey");
 
 ## Documentation
 
-[API 文档](./api.zh-CN.md)
+[API 文档](./docs/api.zh-CN.md)
diff --git a/lib/c/docs/api.md b/lib/c/docs/api.md
@@ -1,4 +1,4 @@
-# cat c client
+# Cat Client for C
 
 ## Quickstart
 
@@ -268,15 +268,15 @@ void logMetricForCount(const char *name, int quantity);
 
 The metric will be sent every 1 second.
 
-For example, if you called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server.
+For example, if you have called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server.
 
 #### logMetricForDuration
 
 ```c
 void logMetricForDuration(const char *name, unsigned long long duration);
 ```
 
-Like `logMetricForCount`, the metrics reported in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value.
+Like `logMetricForCount`, the metrics that have been logged in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value.
 
 ### Heartbeat
 

diff --git a/lib/c/docs/api.zh-CN.md b/lib/c/docs/api.zh-CN.md
@@ -1,4 +1,4 @@
-# cat c client
+# Cat client for C
 
 ## 快速起步
 

diff --git a/lib/cpp/README.md b/lib/cpp/README.md
@@ -1,8 +1,8 @@
 # Cat Client for C++
 
-[中文文档](./docs/zh-CN.md)
+[中文文档](./README.zh-CN.md)
 
-The cat client can be compiled and used both on Linux (both glibc and musl-libc) and OSX.
+The `cppcat` can be compiled and used both on Linux (both glibc and musl-libc) and OSX.
 
 The following Operating Systems are tested:
 
@@ -53,7 +53,7 @@ g++ -lcatclient x.cpp
 
 ## Initialization
 
-Some [preparations](../_/preparations.md) needs to be done before initialize `cppcat`.
+Some [preparations](../_/preparations.md) needs to be done before initializing `cppcat`.
 
 With all the preparations have been done, it's easy to initialize `cppcat` in your c++ codes.
 
@@ -65,7 +65,7 @@ cat::init("appkey");
 
 > Only English characters (a-z, A-Z), numbers (0-9), underscore (\_) and dash (-) is allowed in appkey.
 
-Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [apidoc](./docs/api.md).
+Note that `sampling`, built-in `heartbeat` and `binary` encoder is enabled by default, which you may want to disable it. We also offered an API to customize your initialization, please refer to our [API doc](./docs/api.md).
 
 ## Documentation
 

diff --git a/lib/cpp/docs/zh-CN.md → lib/cpp/README.zh-CN.md b/lib/cpp/docs/zh-CN.md → lib/cpp/README.zh-CN.md
@@ -1,6 +1,6 @@
 # Cat Client for C++
 
-`cppcat` 同时支持 linux (glibc 和 musl-libc) 和 osx 两个平台。
+`cppcat` 同时支持 Linux (glibc 和 musl-libc) 和 OSX 两个平台。
 
 下述列出的操作系统是经过测试可用的：
 
@@ -48,7 +48,7 @@ gcc -lcatclient x.cpp
 
 ## 初始化
 
-一些[准备工作](../../_/preparations.zh-CN.md)需要在初始化 `cppcat` 之前完成。
+一些[准备工作](../_/preparations.zh-CN.md)需要在初始化 `cppcat` 之前完成。
 
 当你完成这些准备工作后，在你的 c++ 代码中初始化 `cppcat` 就很简单了。
 
@@ -60,8 +60,8 @@ cat::init("appkey");
 
 > appkey 只能包含英文字母 (a-z, A-Z)、数字 (0-9)、下划线 (\_) 和中划线 (-)
 
-注意，**采样**，内置**心跳**，**二进制**序列化在默认情况下是开启的，你可能会想要禁用他们。我们同时提供了一个 API 可以使你自定义启动参数，请参考 [API 文档](./api.zh-CN.md)
+注意，**采样**，内置**心跳**，**二进制**序列化在默认情况下是开启的，你可能会想要禁用他们。我们同时提供了一个 API 可以使你自定义启动参数，请参考 [API 文档](./docs/api.zh-CN.md)
 
 ## Documentation
 
-[API 文档](./api.zh-CN.md)
+[API 文档](./docs/api.zh-CN.md)
diff --git a/lib/cpp/docs/api.md b/lib/cpp/docs/api.md
@@ -1,4 +1,4 @@
-# cat c++ client
+# Cat Client for C++
 
 ## Quickstart
 
@@ -168,12 +168,12 @@ void logMetricForCount(const string& key, unsigned int count = 1);
 
 The metric will be sent every 1 second.
 
-For example, if you called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server.
+For example, if you have called this API 3 times in one second (can be in different threads, we use a concurrent hash map to cache the value), only the aggregated value (summarized) will be reported to the server.
 
 #### logMetricForDuration
 
 ```cpp
 void logMetricForDuration(const string& key, unsigned long ms);
 ```
 
-Like `logMetricForCount`, the metrics reported in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value.
+Like `logMetricForCount`, the metrics that have been logged in the same second will be aggregated, the only difference is `averaged` value is used instead of `summarized` value.
diff --git a/lib/cpp/docs/api.zh-CN.md b/lib/cpp/docs/api.zh-CN.md
@@ -1,4 +1,4 @@
-# cat c++ client
+# Cat Client for C++
 
 ## Quickstart
 
@@ -140,7 +140,7 @@ t.Complete();
 
 这里有一些你可能想要知道的：
 
-1. 你可以调用 `addData` 和 `addKV` 多次，他们会被 `&` 连接起来。
+1. 你可以调用 `AddData` 多次，他们会被 `&` 连接起来。
 2. 同时指定 `duration` 和 `durationStart` 是没有意义的，尽管我们在样例中这样做了。
 3. 不要忘记完成 transaction！否则你会得到一个毁坏的消息树以及内存泄漏！
 

diff --git a/lib/go/README.md b/lib/go/README.md
@@ -1,12 +1,12 @@
 # Cat Client for Go
 
-[中文文档](./docs/zh-CN.md)
+[中文文档](./README.zh-CN.md)
 
-Gocat supports Go 1.8+
+`gocat` supports Go 1.8+
 
-Gocat is highly dependent on `ccat`. (through CGO)
+`gocat` is highly dependent on `ccat`. (through CGO)
 
-Since we using the thread local to storage the transaction stack in `ccat`, which is necessary to build a message tree. It's hard for us to let it work appropriately with goroutines. (Because a goroutine can be run in different threads, due to the MPG model)
+Since we are using the thread local to storage the transaction stack in `ccat`, which is necessary to build a `message tree`. It's hard for us to let it work appropriately with goroutines. (Because a goroutine can be run in different threads, due to the MPG model)
 
 So we don't support `message tree` in this version. Don't worry, we are still working on it and have some great ideas at the moment.
 
@@ -20,9 +20,9 @@ $ go get github.com/dianping/cat/lib/go/...
 
 ## Initialization
 
-Some [preparations](../_/preparations.md) needs to be done before initialize `ccat`.
+Some [preparations](../_/preparations.md) needs to be done before initializing `gocat`.
 
-And then you can initialize `gocat` with following codes:
+And then you can initialize `gocat` with the following codes:
 
 ```c
 import (
@@ -45,11 +45,11 @@ t := cat.NewTransaction(TTYPE, "test")
 defer t.Complete()
 ```
 
-We strongly recommend using `defer` keyword to make sure the transaction be completed, or it may cause problems.
+We strongly recommend using `defer` keyword to make sure that the transaction completed, or it may cause problems.
 
 #### Transaction apis
 
-We offered a list of APIs to modify the transaction.
+We offered a series of APIs to modify the transaction.
 
 * AddData
 * SetStatus
@@ -58,7 +58,7 @@ We offered a list of APIs to modify the transaction.
 * SetTimestamp
 * Complete
 
-These APIs can be easily used as the following codes.
+These APIs can be easily used with the following codes.
 
 ```go
 t := cat.NewTransaction(TTYPE, "test")
@@ -113,13 +113,13 @@ cat.LogEvent("Event", "E4", "failed", "some debug info")
 
 #### LogError
 
-Log an error with error stack trace.
+Log an error with error stack traces.
 
 Error is a special event, `type = Exception` and `name = error` by default.
 
 `name` can be overwritten by the 2nd parameter.
 
-`error stack trace` will be collected and add to `data`
+`error stack traces` will be collected and added to `data`.
 
 ```go
 err := errors.New("error")
@@ -133,7 +133,7 @@ cat.LogError(err, 'error-name')
 
 We do aggregate metrics every second.
 
-For example, if you called count 3 times in the same second (with the same name), we will just summarise the value of them and reported once to the server.
+For example, if you have called count 3 times in the same second (with the same name), we will just summarise the value of them and report once to the server.
 
 In the case of `duration`, we use `averaged` value instead of `summarised` value.
 

diff --git a/lib/go/docs/zh-CN.md → lib/go/README.zh-CN.md b/lib/go/docs/zh-CN.md → lib/go/README.zh-CN.md
@@ -1,8 +1,8 @@
 # Cat Client for Go
 
-Gocat 支持 Go 1.8 及以上版本。
+`gocat` 支持 Go 1.8 及以上版本。
 
-Gocat 高度依赖 `ccat`（基于 CGO 实现）
+`gocat` 高度依赖 `ccat`（基于 CGO 实现）
 
 鉴于我们在 `ccat` 中使用**线程空间**来存储 transaction 栈，并用于构建消息树，我们很难让它和 goroutine 共同工作。（因为 MPG 模型的关系，一个 goroutine 可能会在不同的线程中运行）
 
@@ -71,7 +71,7 @@ t.SetDuration(time.Millisecond.Nanoseconds() * 1000)
 
 在使用 Transaction 提供的 API 时，你可能需要注意以下几点：
 
-1. 你可以调用 `AddData`，他们会被 `&` 连接起来。
+1. 你可以调用 `AddData` 多次，他们会被 `&` 连接起来。
 2. 同时指定 `duration` 和 `durationStart` 是没有意义的，尽管我们在样例中这样做了。
 3. 不要忘记完成 transaction！否则你会得到一个毁坏的消息树以及内存泄漏！