From 2175962fde2b64b0cf768bca95fcf32c595bf486 Mon Sep 17 00:00:00 2001 From: Savorboard Date: Sat, 13 Jul 2019 15:04:52 +0800 Subject: [PATCH] Translate docs to english. --- .../user-guide/en/persistent/general.md | 39 +++++++++++-------- .../user-guide/en/persistent/mongodb.md | 1 + .../content/user-guide/en/persistent/mysql.md | 10 ++--- .../user-guide/en/persistent/postgresql.md | 10 ++--- .../user-guide/en/persistent/sqlserver.md | 10 ++--- .../en/samples/eshoponcontainers.md | 2 +- docs/content/user-guide/en/samples/github.md | 4 +- .../en/transports/azure-service-bus.md | 4 +- .../user-guide/en/transports/general.md | 8 ++-- .../en/transports/in-memory-queue.md | 9 ++--- .../content/user-guide/en/transports/kafka.md | 22 +++++------ .../user-guide/en/transports/rabbitmq.md | 28 ++++++------- 12 files changed, 75 insertions(+), 72 deletions(-) diff --git a/docs/content/user-guide/en/persistent/general.md b/docs/content/user-guide/en/persistent/general.md index f2267ac..675a8a1 100644 --- a/docs/content/user-guide/en/persistent/general.md +++ b/docs/content/user-guide/en/persistent/general.md @@ -1,30 +1,33 @@ # General -CAP 需要使用具有持久化功能的存储介质来存储事件消息，例如通过数据库或者其他NoSql设施。CAP 使用这种方式来应对一切环境或者网络异常导致消息丢失的情况，消息的可靠性是分布式事务的基石，所以在任何情况下消息都不能丢失。 +CAP need to use storage media with persistence capabilities to store event messages, such as through databases or other NoSql facilities. CAP uses this approach to deal with the loss of messages in all environments or network anomalies. The reliability of messages is the cornerstone of distributed transactions, so messages cannot be lost under any circumstances. ## Persistent ### Before sent -在消息进入到消息队列之前，CAP使用本地数据库表对消息进行持久化，这样可以保证当消息队列出现异常或者网络错误时候消息是没有丢失的。 +Before the message enters the message queue, the CAP uses the local database table to persist the message, which ensures that the message is not lost when the message queue is abnormal or a network error occurs. -为了保证这种机制的可靠性，CAP使用和业务代码相同的数据库事务来保证业务操作和CAP的消息在持久化的过程中是强一致的。也就是说在进行消息持久化的过程中，任何一方发生异常情况数据库都会进行回滚操作。 +To ensure the reliability of this mechanism, CAP uses the same database transactions as the business code to ensure that business operations and CAP messages are consistent in the persistence process. That is to say, in the process of message persistence, the database will be rolled back when any one of the exceptions occurs. ### After sent -消息进入到消息队列之后，CAP会启动消息队列的持久化功能，我们需要说明一下在 RabbitMQ 和 Kafka 中CAP的消息是如何持久化的。 +After the message enters the message queue, the CAP will start the persistence function of the message queue. We need to explain how the CAP message is persisted in RabbitMQ and Kafka. -针对于 RabbitMQ 中的消息持久化，CAP 使用的是具有消息持久化功能的消费者队列，但是这里面可能有例外情况，参加 2.2.1 章节。 +For message persistence in RabbitMQ, CAP uses a consumer queue with message persistence, but there may be exceptions here. -由于 Kafka 天生设计的就是使用文件进行的消息持久化，在所以在消息进入到Kafka之后，Kafka会保证消息能够正确被持久化而不丢失。 +!!! info "Ready for production?" + By default, queues registered by CAP in RabbitMQ are persistent. When used in a production environment, we recommend that you start all consumers once to create the queues with persistence, which ensures that all queues are created before the message is sent. + +Since Kafka is born with message persistence using files, Kafka will ensure that messages are properly persisted without loss after the message enters Kafka. ## Storage -在 CAP 启动后，会向持久化介质中生成两个表，默认情况下名称为：`Cap.Published` `Cap.Received`。 +After the CAP started, two tables are generated into the persistent, by default the name is `Cap.Published` and `Cap.Received`. ### Storage Data Structure -**Published** 表结构： +Table structure of **Published** : NAME | DESCRIPTION | TYPE :---|:---|:--- @@ -36,8 +39,8 @@ Added | Added Time | DateTime ExpiresAt | Expire time | DateTime Retries | Retry times | int StatusName | Status Name | string - -**Received** 表结构： + +Table structure of **Received** : NAME | DESCRIPTION | TYPE :---|:---|:--- @@ -50,16 +53,18 @@ Added | Added Time | DateTime ExpiresAt | Expire time | DateTime Retries | Retry times | int StatusName | Status Name | string - + ### Wapper Object -CAP 在进行消息发送到时候，会对原始消息对象进行一个二次包装存储到 `Content` 字段中，以下为包装 Content 的 Message 对象数据结构： +When the CAP sends a message, it will store the original message object in a second package in the `Content` field. + +The following is the **Wapper Object** data structure of Content field. NAME | DESCRIPTION | TYPE :---|:---|:--- -Id | CAP生成的消息编号 | string -Timestamp | 消息创建时间 | string -Content | 内容 | string -CallbackName | 回调的订阅者名称 | string +Id | Message Id | string +Timestamp | Message created time | string +Content | Message content | string +CallbackName | Consumer callback topic name | string -其中 Id 字段，CAP 采用的 MongoDB 中的 ObjectId 分布式Id生成算法生成。 \ No newline at end of file +The `Id` field is generate using the mongo [objectid algorithm](https://www.mongodb.com/blog/post/generating-globally-unique-identifiers-for-use-with-mongodb). \ No newline at end of file diff --git a/docs/content/user-guide/en/persistent/mongodb.md b/docs/content/user-guide/en/persistent/mongodb.md index 7f1a803..d4d99d3 100644 --- a/docs/content/user-guide/en/persistent/mongodb.md +++ b/docs/content/user-guide/en/persistent/mongodb.md @@ -50,6 +50,7 @@ PublishedCollection | Database published message collection name | string | cap. The following example shows how to leverage CAP and MongoDB for local transaction integration. + ```csharp //NOTE: Before your test, your need to create database and collection at first. diff --git a/docs/content/user-guide/en/persistent/mysql.md b/docs/content/user-guide/en/persistent/mysql.md index 66bae6e..d369527 100644 --- a/docs/content/user-guide/en/persistent/mysql.md +++ b/docs/content/user-guide/en/persistent/mysql.md @@ -1,11 +1,11 @@ # MySQL -MySQL 是一个开源的关系型数据库，你可以使用 MySQL 来作为 CAP 消息的持久化。 +MySQL is an open-source relational database management system. CAP has supported MySQL as persistent. ## Configuration -要使用 MySQL 存储，你需要从 NuGet 安装以下扩展包： - +To use MySQL storage, you need to install the following extensions from NuGet: + ```ps Install-Package DotNetCore.CAP.MySql @@ -35,8 +35,8 @@ public void ConfigureServices(IServiceCollection services) NAME | DESCRIPTION | TYPE | DEFAULT :---|:---|---|:--- -TableNamePrefix | Cap表名前缀 | string | cap -ConnectionString | 数据库连接字符串 | string | null +TableNamePrefix | CAP table name prefix | string | cap +ConnectionString | Database connection string | string | null ## Publish with transaction diff --git a/docs/content/user-guide/en/persistent/postgresql.md b/docs/content/user-guide/en/persistent/postgresql.md index dc4fa5e..459c00a 100644 --- a/docs/content/user-guide/en/persistent/postgresql.md +++ b/docs/content/user-guide/en/persistent/postgresql.md @@ -1,10 +1,10 @@ # Postgre SQL -PostgreSQL 是一个开源的关系型数据库，它已经变得越来越流行，你可以使用 Postgre SQL 来作为 CAP 消息的持久化。 +PostgreSQL is an open-source relational database management system. CAP has supported PostgreSQL as persistent. ## Configuration -要使用 PostgreSQL 存储，你需要从 NuGet 安装以下扩展包： +To use PostgreSQL storage, you need to install the following extensions from NuGet: ```shell @@ -12,7 +12,7 @@ Install-Package DotNetCore.CAP.PostgreSql ``` -然后，你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。 +Next, add configuration items to the `ConfigureServices` method of `Startup.cs`. ```csharp @@ -35,8 +35,8 @@ public void ConfigureServices(IServiceCollection services) NAME | DESCRIPTION | TYPE | DEFAULT :---|:---|---|:--- -Schema | 数据库架构 | string | cap -ConnectionString | 数据库连接字符串 | string | +Schema | Database schema | string | cap +ConnectionString | Database connection string | string | ## Publish with transaction diff --git a/docs/content/user-guide/en/persistent/sqlserver.md b/docs/content/user-guide/en/persistent/sqlserver.md index ecdf3f3..38fce7e 100644 --- a/docs/content/user-guide/en/persistent/sqlserver.md +++ b/docs/content/user-guide/en/persistent/sqlserver.md @@ -1,10 +1,10 @@ # SQL Server -SQL Server 是由微软开发的一个关系型数据库，你可以使用 SQL Server 来作为 CAP 消息的持久化。 +SQL Server is a relational database management system developed by Microsoft. CAP has supported SQL Server as persistent. ## Configuration -要使用 SQL Server 存储，你需要从 NuGet 安装以下扩展包： +To use SQL Server storage, you need to install the following extensions from NuGet: ```shell @@ -12,7 +12,7 @@ Install-Package DotNetCore.CAP.SqlServer ``` -然后，你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。 +Next, add configuration items to the `ConfigureServices` method of `Startup.cs`. ```csharp @@ -35,8 +35,8 @@ public void ConfigureServices(IServiceCollection services) NAME | DESCRIPTION | TYPE | DEFAULT :---|:---|---|:--- -Schema | 数据库架构 | string | Cap -ConnectionString | 数据库连接字符串 | string | +Schema | Database schema | string | Cap +ConnectionString | Database connection string | string | ## Publish with transaction diff --git a/docs/content/user-guide/en/samples/eshoponcontainers.md b/docs/content/user-guide/en/samples/eshoponcontainers.md index b8d18cf..2cf4668 100644 --- a/docs/content/user-guide/en/samples/eshoponcontainers.md +++ b/docs/content/user-guide/en/samples/eshoponcontainers.md @@ -10,6 +10,6 @@ eShopOnContainers is a sample application written in C# running on .NET Core usi ## eShopOnContainers with CAP -你可以在下面的地址看到如何在 eShopOnContainers 中使用 CAP。 +You can see how to use caps in eShopOnContainers at the Github repository. https://github.com/yang-xiaodong/eShopOnContainers \ No newline at end of file diff --git a/docs/content/user-guide/en/samples/github.md b/docs/content/user-guide/en/samples/github.md index b7df025..3f5f6ff 100644 --- a/docs/content/user-guide/en/samples/github.md +++ b/docs/content/user-guide/en/samples/github.md @@ -1,5 +1,5 @@ -# Github 上的示例 +# Github Samples -你可以在下面的地址找到相关示例代码： +You can find the sample code at Github repository : https://github.com/dotnetcore/CAP/tree/master/samples \ No newline at end of file diff --git a/docs/content/user-guide/en/transports/azure-service-bus.md b/docs/content/user-guide/en/transports/azure-service-bus.md index a44e354..c3e45a4 100644 --- a/docs/content/user-guide/en/transports/azure-service-bus.md +++ b/docs/content/user-guide/en/transports/azure-service-bus.md @@ -1,8 +1,8 @@ # Azure Service Bus -Azure 服务总线是一种多租户云消息服务，可用于在应用程序和服务之间发送信息。 异步操作可实现灵活的中转消息传送、结构化的先进先出 (FIFO) 消息传送以及发布/订阅功能。 +Microsoft Azure Service Bus is a fully managed enterprise integration message broker. Service Bus is most commonly used to decouple applications and services from each other, and is a reliable and secure platform for asynchronous data and state transfer. -CAP 支持使用 Azure Service Bus 作为消息传输器。 +CAP supports Azure Service Bus as a message transporter. ## Configuration diff --git a/docs/content/user-guide/en/transports/general.md b/docs/content/user-guide/en/transports/general.md index b358c42..1272bf4 100644 --- a/docs/content/user-guide/en/transports/general.md +++ b/docs/content/user-guide/en/transports/general.md @@ -15,10 +15,10 @@ CAP supports several transport methods: 🏳‍🌈 | RabbitMQ | Kafka | Azure Service Bus | In-Memory :-- | :--: | :--: | :--: | :-- : -**定位** | 可靠消息传输 | 实时数据处理 | 云 | 内存型，测试 -**分布式** | ✔ | ✔ | ✔ |❌ -**持久化** | ✔ | ✔ | ✔ | ❌ -**性能** | Medium | High | Medium | High +**Positioning** | Reliable message transmission | Real time data processing | Cloud | In-Memory, testing +**Distributed** | ✔ | ✔ | ✔ |❌ +**Persistence** | ✔ | ✔ | ✔ | ❌ +**Performance** | Medium | High | Medium | High > `Azure Service Bus` vs `RabbitMQ` : diff --git a/docs/content/user-guide/en/transports/in-memory-queue.md b/docs/content/user-guide/en/transports/in-memory-queue.md index 167499e..532a479 100644 --- a/docs/content/user-guide/en/transports/in-memory-queue.md +++ b/docs/content/user-guide/en/transports/in-memory-queue.md @@ -1,18 +1,17 @@ # In-Memory Queue -In Memory Queue 为基于内存的消息队列，该扩展由 [社区](https://github.com/yang-xiaodong/Savorboard.CAP.InMemoryMessageQueue) 进行提供。 +In Memory Queue is a memory-based message queue provided by [Community](https://github.com/yang-xiaodong/Savorboard.CAP.InMemoryMessageQueue). -## 配置 +## Configuration -要使用 In Memory Queue 作为消息传输器，你需要从 NuGet 安装以下扩展包： +To use In Memory Queue as a message transporter, you need to install the following extensions from NuGet: ```shell Install-Package Savorboard.CAP.InMemoryMessageQueue ``` - -然后，你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。 +Then you can add memory-based configuration items to the `ConfigureServices` method of `Startup.cs`. ```csharp diff --git a/docs/content/user-guide/en/transports/kafka.md b/docs/content/user-guide/en/transports/kafka.md index d3bf7a4..21a68b4 100644 --- a/docs/content/user-guide/en/transports/kafka.md +++ b/docs/content/user-guide/en/transports/kafka.md @@ -1,12 +1,12 @@ # Apache Kafka® -[Apache Kafka®](https://kafka.apache.org/) 是一个开源流处理软件平台，由 LinkedIn 开发并捐赠给 Apache Software Foundation，用 Scala 和 Java 编写。 - -CAP 支持使用 Apache Kafka® 作为消息传输器。 +[Apache Kafka®](https://kafka.apache.org/) is an open-source stream-processing software platform developed by LinkedIn and donated to the Apache Software Foundation, written in Scala and Java. + +CAP has supported Kafka® as message transporter. ## Configuration -要使用 Kafka 作为消息传输器，你需要从 NuGet 安装以下扩展包： +To use Kafka transporter, you need to install the following extensions from NuGet: ```shell @@ -14,7 +14,7 @@ Install-Package DotNetCore.CAP.Kafka ``` -然后，你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。 +Then you can add memory-based configuration items to the `ConfigureServices` method of `Startup.cs`. ```csharp @@ -35,18 +35,16 @@ public void ConfigureServices(IServiceCollection services) #### Kafka Options -CAP 直接对外提供的 Kafka 配置参数如下： +The Kafka configuration parameters provided directly by the CAP are as follows: NAME | DESCRIPTION | TYPE | DEFAULT :---|:---|---|:--- -Servers | Broker 地址 | string | -ConnectionPoolSize | 用户名 | int | 10 - +Servers | Broker server address | string | +ConnectionPoolSize | connection pool size | int | 10 #### Kafka MainConfig Options -如果你需要 **更多** 原生 Kakfa 相关的配置项，可以通过 `MainConfig` 配置项进行设定： - +If you need **more** native Kakfa related configuration items, you can set it with the `MainConfig` configuration option: ```csharp services.AddCap(capOptions => @@ -59,6 +57,6 @@ services.AddCap(capOptions => }); ``` -MainConfig 为配置字典，你可以通过以下链接找到其支持的配置项列表。 +`MainConfig` is a configuration dictionary, you can find a list of supported configuration items through the following link. [https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md](https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md) diff --git a/docs/content/user-guide/en/transports/rabbitmq.md b/docs/content/user-guide/en/transports/rabbitmq.md index 9c08d3d..415e9cc 100644 --- a/docs/content/user-guide/en/transports/rabbitmq.md +++ b/docs/content/user-guide/en/transports/rabbitmq.md @@ -1,12 +1,12 @@ # RabbitMQ -RabbitMQ是实现了高级消息队列协议（AMQP）的开源消息代理软件（亦称面向消息的中间件）。RabbitMQ 服务器是用 Erlang 语言编写的，而聚类和故障转移是构建在开源的通讯平台框架上的。所有主要的编程语言均有与代理接口通讯的客户端库。 +RabbitMQ is an open-source message-broker software that originally implemented the Advanced Message Queuing Protocol and has since been extended with a plug-in architecture to support Streaming Text Oriented Messaging Protocol, Message Queuing Telemetry Transport, and other protocols. -CAP 支持使用 RabbitMQ 作为消息传输器。 +CAP has supported RabbitMQ as message transporter. -## 配置 +## Configuration -要使用 RabbitMQ 作为消息传输器，你需要从 NuGet 安装以下扩展包： +To use RabbitMQ transporter, you need to install the following extensions from NuGet: ```shell @@ -14,7 +14,7 @@ Install-Package DotNetCore.CAP.RabbitMQ ``` -然后，你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。 +Next, add configuration items to the `ConfigureServices` method of `Startup.cs`. ```csharp @@ -36,21 +36,21 @@ public void ConfigureServices(IServiceCollection services) #### RabbitMQ Options -CAP 直接对外提供的 RabbitMQ 配置参数如下： +The RabbitMQ configuration parameters provided directly by the CAP are as follows: NAME | DESCRIPTION | TYPE | DEFAULT :---|:---|---|:--- -HostName | 宿主地址 | string | localhost -UserName | 用户名 | string | guest -Password | 密码 | string | guest -VirtualHost | 虚拟主机 | string | / -Port | 端口号 | int | -1 -TopicExchangeName | CAP默认Exchange名称 | string | cap.default.topic -QueueMessageExpires | 队列中消息自动删除时间 | int | (10天) 毫秒 +HostName | Broker host address | string | localhost +UserName | Broker user name | string | guest +Password | Broker password | string | guest +VirtualHost | Broker virtual host | string | / +Port | Port | int | -1 +TopicExchangeName | Default exchange name of cap created | string | cap.default.topic +QueueMessageExpires | Message expries after to delete, in milliseconds | int | (10 days) milliseconds #### ConnectionFactory Options -如果你需要 **更多** 原生 `ConnectionFactory` 相关的配置项，可以通过 `ConnectionFactoryOptions` 配置项进行设定： +If you need **more** native `ConnectionFactory` configuration options, you can set it by 'ConnectionFactoryOptions' option: ```csharp