Updated Spanish translations and logos (ostafen#28)

README-CN.md

@@ -1,5 +1,6 @@
 <p align="center">
-<img width="300" src=".github/logo.png" border="0" alt="kelindar/column">
+<img alt="CloverDB Logo" src=".github/logo.png#gh-light-mode-only" width="300px">
+<img alt="CloverDB Logo" src=".github/logo-white.png#gh-dark-mode-only" width="300px">
 </p>
 <h2 align="center">轻量级面向文档的NoSQL数据库</h2>
 

README-ES.md

@@ -1,5 +1,6 @@
 <p align="center">
-<img width="300" src=".github/logo.png" border="0" alt="kelindar/column">
+<img alt="CloverDB Logo" src=".github/logo.png#gh-light-mode-only" width="300px">
+<img alt="CloverDB Logo" src=".github/logo-white.png#gh-dark-mode-only" width="300px">
 </p>
 <h2 align="center">Base de datos NoSQL ligera orientada a documentos</h2>
 
@@ -35,7 +36,13 @@ Asegúrate de que tienes un entorno Go funcional (Se requiere Go 1.13 o superior
   go get github.com/ostafen/clover
 ```
 
-## Uso de la API
+## Bases de datos y colecciones
+
+CloverDB guardar los registros como documentos JSON, los cuales son agrupados en colecciones. Una base de datos por lo tanto está formada de una o más colecciones.
+
+### Base de datos
+
+Para guardar documentos dentro de colecciones, deberás de abrir una base de datos Clover utilizando la función `Open()`.
 
 ```go
 import (
@@ -45,31 +52,37 @@ import (
 
 ...
 
+db, _ := c.Open("clover-db")
+defer db.Close() // recuerda cerrar la base de datos cuando hayas acabado
 ```
 
-### Crear una nueva colección
-```go
+### Colecciones
 
+CloverDB guarda los documentos dentro de colecciones. Las colecciones de bases de datos sin esquema son el equivalente a las tablas en bases de datos relacionales. Una colección se crea llamando a la función `CreateCollection()` en una instancia de la base de datos. Los nuevos documentos pueden ser insertados utilizando los métodos `Insert()` o `InsertOne()`. Cada documento se identifica de forma única por una **Version 4 UUID** guardada en el campo especial **_id** y generado durante la inserción.
+
+```go
 db, _ := c.Open("clover-db")
-db.CreateCollection("myCollection")
+db.CreateCollection("myCollection") // crear una nueva colección llamada "myCollection"
 
+// insertar un nuevo documento dentro de una colección
 doc := c.NewDocument()
 doc.Set("hello", "clover!")
 
+// InsertOne devuelve el campo id del documento insertado
 docId, _ := db.InsertOne("myCollection", doc)
+fmt.Println(docId)
+```
 
-doc, _ = db.Query("myCollection").FindById(docId)
-log.Println(doc.Get("hello"))
+## Consultas
 
-```
+CloverDB está equipada con una API fluida y elegante para consultar tus datos. Una consulta está representada por el objeto **Query**, que permite devolver documentos que coincidan con unos determinados parámetros. Una consulta puede ser creada pasando como parámetro un nombre de colección válido en el método `Query()`.
 
-### Consultar a una base de datos existente
+### Seleccionar Todos los Documentos en una colección
 
-```go
-db, _ := c.Open("../test-data/todos")
+El método `FindAll()` es utilizado para devolver todos los documentos que coincidan con una determinada consulta.
 
-// buscar todos los "por hacer" (todos) pertenecientes al usuario con id 5 y 8
-docs, _ := db.Query("todos").Where(c.Field("completed").Eq(true).And(c.Field("userId").In(5, 8))).FindAll()
+```go
+docs, _ := db.Query("myCollection").FindAll()
 
 todo := &struct {
     Completed bool   `json:"completed"`
@@ -83,38 +96,73 @@ for _, doc := range docs {
 }
 ```
 
-### Actualizar y eliminar documentos
+
+### Filter Documents with Criteria
+
+Para filtrar los documentos devueltos por `FindAll()`, deberás de especificar ciertos parámetros determinados por el objeto **Criteria** utilizando el método `Where()`. Un objeto **Criteria** simplemente representa una afirmación en un documento, evaluándose como verdadero (true) solo si coinciden todas las condiciones expuestas en la consulta.
+
+El siguiente ejemplo muestra como construir un objeto **Criteria**, que coincida con todos los documentos cuyo campo **completed** sea verdadero (true).
 
 ```go
-db, _ := c.Open("../test-data/todos")
+db.Query("todos").Where(c.Field("completed").Eq(true)).FindAll()
 
-// marcar todos los "por hacer" (todos) pertenecientes al usuario con id 1 como completados
-updates := make(map[string]interface{})
-updates["completed"] = true
+// o su equivalente
+db.Query("todos").Where(c.Field("completed").IsTrue()).FindAll()
+```
 
-db.Query("todos").Where(c.Field("userId").Eq(1)).Update(updates)
+Con el objetivo de construir consultas más complejas, encadenaremos diferentes objetos Criteria utilizando los métodos `And()` y `Or()`, each returning a new Criteria obtained by appling the corresponding logical operator.
 
-// eliminar todos los "por hacer" (todos) pertenecientes al usuario con id 5 y 8
-db.Query("todos").Where(c.Field("userId").In(5,8)).Delete()
+```go
+// encontrar todos los documentos por hacer (todos) que pertenezcan a los usuarios con id 5 y 8
+db.Query("todos").Where(c.Field("completed").Eq(true).And(c.Field("userId").In(5, 8))).FindAll()
 ```
 
-### Actualizar un único documento
+### Ordenar Documentos
+
+Para ordenar documentos en CloverDB, necesitarás usar `Sort()`. Es una función variable que acepta una secuencia de SortOption, cada cual permitirá especificar un campo y una dirección de ordenamiento.
+La dirección de ordenamiento puede ser 1 o -1, respectivamente corresponden a orden ascendente y descendente. Si no se proporciona ninguna SortOption, `Sort()` utilizará el campo **_id** por defecto.
+
 ```go
-db, _ := c.Open("../test-data/todos")
+// Encontrar cualquier "por hacer" (todo) perteneciente al usuario insertado más reciente
+db.Query("todos").Sort(c.SortOption{"userId", -1}).FindFirst()
+```
+
+### Saltar/Limitar Documentos
+
+En ocasiones, puede ser útil eliminar ciertos documentos del resultado o simplemente establecer un límite del máximo número de elementos devueltos en una consulta. Para este propósito CloverDB proporciona las funciones `Skip()` y `Limit()`, ambos aceptando un número entero $n$ como parámetro.
+
+```go
+// descartar los primeros 10 documentos del resultado,
+// y además limitar el número máximo de resultados de la consulta a 100
+db.Query("todos").Skip(10).Limit(100).FindAll()
+```
+### Actualizar/Eliminar Documentos
 
+El método `Update()` es utilizado para modificar campos específicos de documentos en una colección. El método `Delete()` se utiliza para eliminar documentos. Ambos métodos pertenecen al objeto Query, de modo que sea fácil actualizar y eliminar documentos que coincidan con una consulta determinada.
+
+```go
+// marcar todos los "por hacer" (todos) que pertenezcan al usuario con id 1 como completado
 updates := make(map[string]interface{})
 updates["completed"] = true
 
-// puedes, o bien obtener la _id
-doc, _ := db.Query("todos").Where(c.Field("userId").Eq(2)).FindFirst()
-docId := doc.Get("_id")
+db.Query("todos").Where(c.Field("userId").Eq(1)).Update(updates)
 
-// o utilizar una cadena de texto, por ejemplo:
-// docId := "1dbce353-d3c6-43b3-b5a8-80d8d876389b"
+// eliminar todos los "por hacer" (todos) que pertenezcan a los usuarios con id 5 y 8
+db.Query("todos").Where(c.Field("userId").In(5,8)).Delete()
+```
 
-// actualizar un único documento con el campo _id
-db.Query("todos").Where(c.Field("_id").Eq(docId)).Update(updates)
+Actualizar o eliminar un único documento utilizando la id se puede lograr de la misma forma, using an equality condition on the **_id** field, like shown in the following snippet:
+
+```go
+docId := "1dbce353-d3c6-43b3-b5a8-80d8d876389b"
+db.Query("todos").Where(c.Field("_id").Eq(docId)).Delete()
 ```
 ## Contribuir
 
 **CloverDB** se desarrolla de forma activa. Cualquier contribución, en forma de sugerencia, reporte de errores o pull request es bienvenido :blush:
+
+Se han recibido con gratitud, las principales contribuciones y sugerencias de (en orden alfabético):
+
+- [ASWLaunchs](https://github.com/ASWLaunchs)
+- [jsgm](https://github.com/jsgm)
+- [segfault99](https://github.com/segfault99)