diff --git a/README.md b/README.md
index 444a1e0ef..9a0e22b0e 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,11 @@
Crystal 是一個程式語言語言，並嘗試完成以下目標：
-* Ruby 風格語法（但不會完全相容 Ruby）
-* 自動型別推導以及靜態型別檢查
-* 容易撰寫 C 函式庫綁紮(Binding)
-* 編譯時期展開巨集並產生最佳化程式碼
-* 產生高效原生碼
+- Ruby 風格語法（但不會完全相容 Ruby）
+- 自動型別推導以及靜態型別檢查
+- 容易撰寫 C 函式庫綁紮(Binding)
+- 編譯時期展開巨集並產生最佳化程式碼
+- 產生高效原生碼
**Crystal's standard library is documented in the [API docs](https://crystal-lang.org/api).**
@@ -64,13 +64,13 @@ gitbook_1 | Restart after change in file node_modules/.bin
雖然慣例僅僅只是慣例，但這邊還是整理出一些大家比較容易掌握的要點：
-* 文字中若需補充原文可以使用 `` 標籤，如：
+- 文字中若需補充原文可以使用 `` 標籤，如：
```
# 字串 String
```
-* 儘量避免使用第二人稱，將 `You` 改以第一人稱複數表達，如：
+- 儘量避免使用第二人稱，將 `You` 改以第一人稱複數表達，如：
```
In type restrictions, generic type arguments and other places where a type is expected, **you** can use a shorter syntax, as explained in the type:
@@ -82,147 +82,146 @@ In type restrictions, generic type arguments and other places where a type is ex
當使用在型別限制時，於任何泛型型別參數或是其他需要填寫型別的地方，「我們」也可以使用簡短的語法來表示序組的型別，這在型別語法一章中會解釋：
```
-* 使用相對路徑以及 .md 後綴來建立不同章節之間的連接。
-
+- 使用相對路徑以及 .md 後綴來建立不同章節之間的連接。
十分感謝您的參與 <(\_ \_)>
### 翻譯清單
-| `○` | `△` | `☓` |
-|:-----:|:-------:|:-----:|
+| `○` | `△` | `☓` |
+| :----: | :------: | :----: |
| 已完成 | 部分翻譯 | 未翻譯 |
-| 檔案 | 狀態 | Owner |
-|-----|:----:|-----|
-| `introduction.md` | `○` | @david50407 |
-| `getting_started/README.md` | `○` | @david50407 |
-| `getting_started/http_server.md` | `○` | @david50407 |
-| `getting_started/cli.md` | `○` | @david50407 |
-| `the_shards_command/README.md` | `☓` | |
-| `using_the_compiler/README.md` | `△` | @david50407 |
-| `syntax_and_semantics/README.md` | `△` | @david50407 |
-| `syntax_and_semantics/comments.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/nil.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/bool.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/integers.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/floats.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/char.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/string.md` | `△` | @david50407 |
-| `syntax_and_semantics/literals/symbol.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/array.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/hash.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/range.md` | `△` | @david50407 |
-| `syntax_and_semantics/literals/regex.md` | `△` | @david50407 |
-| `syntax_and_semantics/literals/tuple.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/named_tuple.md` | `○` | @david50407 |
-| `syntax_and_semantics/literals/proc.md` | `○` | @david50407 |
-| `syntax_and_semantics/assignment.md` | `△` | @david50407 |
-| `syntax_and_semantics/local_variables.md` | `○` | @david50407 |
-| `syntax_and_semantics/control_expressions.md` | `☓` | |
-| `syntax_and_semantics/truthy_and_falsey_values.md` | `☓` | |
-| `syntax_and_semantics/if.md` | `☓` | |
-| `syntax_and_semantics/as_a_suffix.md` | `☓` | |
-| `syntax_and_semantics/as_an_expression.md` | `☓` | |
-| `syntax_and_semantics/ternary_if.md` | `☓` | |
-| `syntax_and_semantics/if_var.md` | `☓` | |
-| `syntax_and_semantics/if_varis_a.md` | `☓` | |
-| `syntax_and_semantics/if_varresponds_to.md` | `☓` | |
-| `syntax_and_semantics/if_var_nil.md` | `☓` | |
-| `syntax_and_semantics/not.md` | `☓` | |
-| `syntax_and_semantics/unless.md` | `☓` | |
-| `syntax_and_semantics/case.md` | `☓` | |
-| `syntax_and_semantics/while.md` | `☓` | |
-| `syntax_and_semantics/break.md` | `☓` | |
-| `syntax_and_semantics/next.md` | `☓` | |
-| `syntax_and_semantics/until.md` | `☓` | |
-| `syntax_and_semantics/and.md` | `☓` | |
-| `syntax_and_semantics/or.md` | `☓` | |
-| `syntax_and_semantics/requiring_files.md` | `☓` | |
-| `syntax_and_semantics/types_and_methods.md` | `☓` | |
-| `syntax_and_semantics/everything_is_an_object.md` | `☓` | |
-| `syntax_and_semantics/the_program.md` | `☓` | |
-| `syntax_and_semantics/classes_and_methods.md` | `☓` | |
-| `syntax_and_semantics/new_initialize_and_allocate.md` | `☓` | |
-| `syntax_and_semantics/methods_and_instance_variables.md` | `☓` | |
-| `syntax_and_semantics/type_inference.md` | `☓` | |
-| `syntax_and_semantics/union_types.md` | `☓` | |
-| `syntax_and_semantics/overloading.md` | `☓` | |
-| `syntax_and_semantics/default_and_named_arguments.md` | `☓` | |
-| `syntax_and_semantics/splats_and_tuples.md` | `☓` | |
-| `syntax_and_semantics/type_restrictions.md` | `☓` | |
-| `syntax_and_semantics/return_types.md` | `☓` | |
-| `syntax_and_semantics/default_values_named_arguments_splats_tuples_and_overloading.md` | `☓` | |
-| `syntax_and_semantics/operators.md` | `☓` | |
-| `syntax_and_semantics/visibility.md` | `☓` | |
-| `syntax_and_semantics/inheritance.md` | `☓` | |
-| `syntax_and_semantics/virtual_and_abstract_types.md` | `☓` | |
-| `syntax_and_semantics/class_methods.md` | `☓` | |
-| `syntax_and_semantics/class_variables.md` | `☓` | |
-| `syntax_and_semantics/finalize.md` | `☓` | |
-| `syntax_and_semantics/modules.md` | `☓` | |
-| `syntax_and_semantics/generics.md` | `☓` | |
-| `syntax_and_semantics/structs.md` | `☓` | |
-| `syntax_and_semantics/constants.md` | `☓` | |
-| `syntax_and_semantics/enum.md` | `☓` | |
-| `syntax_and_semantics/blocks_and_procs.md` | `☓` | |
-| `syntax_and_semantics/capturing_blocks.md` | `☓` | |
-| `syntax_and_semantics/proc_literal.md` | `☓` | |
-| `syntax_and_semantics/block_forwarding.md` | `☓` | |
-| `syntax_and_semantics/closures.md` | `☓` | |
-| `syntax_and_semantics/alias.md` | `☓` | |
-| `syntax_and_semantics/exception_handling.md` | `☓` | |
-| `syntax_and_semantics/type_grammar.md` | `☓` | |
-| `syntax_and_semantics/type_reflection.md` | `☓` | |
-| `syntax_and_semantics/is_a.md` | `☓` | |
-| `syntax_and_semantics/nil_question.md` | `☓` | |
-| `syntax_and_semantics/responds_to.md` | `☓` | |
-| `syntax_and_semantics/as.md` | `☓` | |
-| `syntax_and_semantics/as_question.md` | `☓` | |
-| `syntax_and_semantics/typeof.md` | `☓` | |
-| `syntax_and_semantics/macros.md` | `☓` | |
-| `syntax_and_semantics/macros/macro_methods.md` | `☓` | |
-| `syntax_and_semantics/macros/hooks.md` | `☓` | |
-| `syntax_and_semantics/macros/fresh_variables.md` | `☓` | |
-| `syntax_and_semantics/annotations.md` | `☓` | |
-| `syntax_and_semantics/annotations/built_in_annotations.md` | `☓` | |
-| `syntax_and_semantics/low_level_primitives.md` | `☓` | |
-| `syntax_and_semantics/pointerof.md` | `☓` | |
-| `syntax_and_semantics/sizeof.md` | `☓` | |
-| `syntax_and_semantics/instance_sizeof.md` | `☓` | |
-| `syntax_and_semantics/offsetof.md` | `☓` | |
-| `syntax_and_semantics/declare_var.md` | `☓` | |
-| `syntax_and_semantics/compile_time_flags.md` | `☓` | |
-| `syntax_and_semantics/cross-compilation.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/README.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/lib.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/fun.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/out.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/to_unsafe.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/struct.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/union.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/enum.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/variables.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/constants.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/type.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/alias.md` | `☓` | |
-| `syntax_and_semantics/c_bindings/callbacks.md` | `☓` | |
-| `syntax_and_semantics/unsafe.md` | `☓` | |
-| `conventions/README.md` | `○` | @imo-ininder |
-| `conventions/coding_style.md` | `○` | @imo-ininder |
-| `conventions/documenting_code.md` | `○` | @imo-ininder |
-| `database/README.md` | `☓` | |
-| `database/connection.md` | `☓` | |
-| `database/connection_pool.md` | `☓` | |
-| `database/transactions.md` | `☓` | |
-| `guides/README.md` | `☓` | |
-| `guides/performance.md` | `☓` | |
-| `guides/concurrency.md` | `☓` | |
-| `guides/testing.md` | `☓` | |
-| `guides/writing_shards.md` | `☓` | |
-| `guides/hosting/github.md` | `☓` | |
-| `guides/hosting/gitlab.md` | `☓` | |
-| `guides/continuous_integration.md` | `☓` | |
-| `guides/ci/travis.md` | `☓` | |
-| `guides/ci/circleci.md` | `☓` | |
\ No newline at end of file
+| 檔案 | 狀態 | Owner |
+| -------------------------------------------------------------------------------------- | :--: | ------------ |
+| `introduction.md` | `○` | @david50407 |
+| `getting_started/README.md` | `○` | @david50407 |
+| `getting_started/http_server.md` | `○` | @david50407 |
+| `getting_started/cli.md` | `○` | @david50407 |
+| `the_shards_command/README.md` | `○` | @david50407 |
+| `using_the_compiler/README.md` | `△` | @david50407 |
+| `syntax_and_semantics/README.md` | `△` | @david50407 |
+| `syntax_and_semantics/comments.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/nil.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/bool.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/integers.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/floats.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/char.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/string.md` | `△` | @david50407 |
+| `syntax_and_semantics/literals/symbol.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/array.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/hash.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/range.md` | `△` | @david50407 |
+| `syntax_and_semantics/literals/regex.md` | `△` | @david50407 |
+| `syntax_and_semantics/literals/tuple.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/named_tuple.md` | `○` | @david50407 |
+| `syntax_and_semantics/literals/proc.md` | `○` | @david50407 |
+| `syntax_and_semantics/assignment.md` | `△` | @david50407 |
+| `syntax_and_semantics/local_variables.md` | `○` | @david50407 |
+| `syntax_and_semantics/control_expressions.md` | `☓` | |
+| `syntax_and_semantics/truthy_and_falsey_values.md` | `☓` | |
+| `syntax_and_semantics/if.md` | `☓` | |
+| `syntax_and_semantics/as_a_suffix.md` | `☓` | |
+| `syntax_and_semantics/as_an_expression.md` | `☓` | |
+| `syntax_and_semantics/ternary_if.md` | `☓` | |
+| `syntax_and_semantics/if_var.md` | `☓` | |
+| `syntax_and_semantics/if_varis_a.md` | `☓` | |
+| `syntax_and_semantics/if_varresponds_to.md` | `☓` | |
+| `syntax_and_semantics/if_var_nil.md` | `☓` | |
+| `syntax_and_semantics/not.md` | `☓` | |
+| `syntax_and_semantics/unless.md` | `☓` | |
+| `syntax_and_semantics/case.md` | `☓` | |
+| `syntax_and_semantics/while.md` | `☓` | |
+| `syntax_and_semantics/break.md` | `☓` | |
+| `syntax_and_semantics/next.md` | `☓` | |
+| `syntax_and_semantics/until.md` | `☓` | |
+| `syntax_and_semantics/and.md` | `☓` | |
+| `syntax_and_semantics/or.md` | `☓` | |
+| `syntax_and_semantics/requiring_files.md` | `☓` | |
+| `syntax_and_semantics/types_and_methods.md` | `☓` | |
+| `syntax_and_semantics/everything_is_an_object.md` | `☓` | |
+| `syntax_and_semantics/the_program.md` | `☓` | |
+| `syntax_and_semantics/classes_and_methods.md` | `☓` | |
+| `syntax_and_semantics/new_initialize_and_allocate.md` | `☓` | |
+| `syntax_and_semantics/methods_and_instance_variables.md` | `☓` | |
+| `syntax_and_semantics/type_inference.md` | `☓` | |
+| `syntax_and_semantics/union_types.md` | `☓` | |
+| `syntax_and_semantics/overloading.md` | `☓` | |
+| `syntax_and_semantics/default_and_named_arguments.md` | `☓` | |
+| `syntax_and_semantics/splats_and_tuples.md` | `☓` | |
+| `syntax_and_semantics/type_restrictions.md` | `☓` | |
+| `syntax_and_semantics/return_types.md` | `☓` | |
+| `syntax_and_semantics/default_values_named_arguments_splats_tuples_and_overloading.md` | `☓` | |
+| `syntax_and_semantics/operators.md` | `☓` | |
+| `syntax_and_semantics/visibility.md` | `☓` | |
+| `syntax_and_semantics/inheritance.md` | `☓` | |
+| `syntax_and_semantics/virtual_and_abstract_types.md` | `☓` | |
+| `syntax_and_semantics/class_methods.md` | `☓` | |
+| `syntax_and_semantics/class_variables.md` | `☓` | |
+| `syntax_and_semantics/finalize.md` | `☓` | |
+| `syntax_and_semantics/modules.md` | `☓` | |
+| `syntax_and_semantics/generics.md` | `☓` | |
+| `syntax_and_semantics/structs.md` | `☓` | |
+| `syntax_and_semantics/constants.md` | `☓` | |
+| `syntax_and_semantics/enum.md` | `☓` | |
+| `syntax_and_semantics/blocks_and_procs.md` | `☓` | |
+| `syntax_and_semantics/capturing_blocks.md` | `☓` | |
+| `syntax_and_semantics/proc_literal.md` | `☓` | |
+| `syntax_and_semantics/block_forwarding.md` | `☓` | |
+| `syntax_and_semantics/closures.md` | `☓` | |
+| `syntax_and_semantics/alias.md` | `☓` | |
+| `syntax_and_semantics/exception_handling.md` | `☓` | |
+| `syntax_and_semantics/type_grammar.md` | `☓` | |
+| `syntax_and_semantics/type_reflection.md` | `☓` | |
+| `syntax_and_semantics/is_a.md` | `☓` | |
+| `syntax_and_semantics/nil_question.md` | `☓` | |
+| `syntax_and_semantics/responds_to.md` | `☓` | |
+| `syntax_and_semantics/as.md` | `☓` | |
+| `syntax_and_semantics/as_question.md` | `☓` | |
+| `syntax_and_semantics/typeof.md` | `☓` | |
+| `syntax_and_semantics/macros.md` | `☓` | |
+| `syntax_and_semantics/macros/macro_methods.md` | `☓` | |
+| `syntax_and_semantics/macros/hooks.md` | `☓` | |
+| `syntax_and_semantics/macros/fresh_variables.md` | `☓` | |
+| `syntax_and_semantics/annotations.md` | `☓` | |
+| `syntax_and_semantics/annotations/built_in_annotations.md` | `☓` | |
+| `syntax_and_semantics/low_level_primitives.md` | `☓` | |
+| `syntax_and_semantics/pointerof.md` | `☓` | |
+| `syntax_and_semantics/sizeof.md` | `☓` | |
+| `syntax_and_semantics/instance_sizeof.md` | `☓` | |
+| `syntax_and_semantics/offsetof.md` | `☓` | |
+| `syntax_and_semantics/declare_var.md` | `☓` | |
+| `syntax_and_semantics/compile_time_flags.md` | `☓` | |
+| `syntax_and_semantics/cross-compilation.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/README.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/lib.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/fun.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/out.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/to_unsafe.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/struct.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/union.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/enum.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/variables.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/constants.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/type.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/alias.md` | `☓` | |
+| `syntax_and_semantics/c_bindings/callbacks.md` | `☓` | |
+| `syntax_and_semantics/unsafe.md` | `☓` | |
+| `conventions/README.md` | `○` | @imo-ininder |
+| `conventions/coding_style.md` | `○` | @imo-ininder |
+| `conventions/documenting_code.md` | `○` | @imo-ininder |
+| `database/README.md` | `☓` | |
+| `database/connection.md` | `☓` | |
+| `database/connection_pool.md` | `☓` | |
+| `database/transactions.md` | `☓` | |
+| `guides/README.md` | `☓` | |
+| `guides/performance.md` | `☓` | |
+| `guides/concurrency.md` | `☓` | |
+| `guides/testing.md` | `☓` | |
+| `guides/writing_shards.md` | `☓` | |
+| `guides/hosting/github.md` | `☓` | |
+| `guides/hosting/gitlab.md` | `☓` | |
+| `guides/continuous_integration.md` | `☓` | |
+| `guides/ci/travis.md` | `☓` | |
+| `guides/ci/circleci.md` | `☓` | |
diff --git a/SUMMARY.md b/SUMMARY.md
index be17abbe5..bbfe72373 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -4,7 +4,7 @@
* [讓我們開始吧！](getting_started/README.md)
* [HTTP 伺服器](getting_started/http_server.md)
* [命令列應用程式](getting_started/cli.md)
-* [The shards command](the_shards_command/README.md)
+* [有關 Shards](the_shards_command/README.md)
* [使用編譯器](using_the_compiler/README.md)
* [語法及語意](syntax_and_semantics/README.md)
* [註解](syntax_and_semantics/comments.md)
@@ -125,7 +125,7 @@
* [Performance](guides/performance.md)
* [Concurrency](guides/concurrency.md)
* [Testing](guides/testing.md)
- * [Writing Shards](guides/writing_shards.md)
+ * [撰寫 Shards](guides/writing_shards.md)
* [Hosting on GitHub](guides/hosting/github.md)
* [Hosting on GitLab](guides/hosting/gitlab.md)
* [Continuous Integration](guides/continuous_integration.md)
diff --git a/guides/writing_shards.md b/guides/writing_shards.md
index 8a37f5512..5d29a51d3 100644
--- a/guides/writing_shards.md
+++ b/guides/writing_shards.md
@@ -1,4 +1,4 @@
-# Writing Shards
+# 撰寫 Shards
How to write and release Crystal Shards.
diff --git a/the_shards_command/README.md b/the_shards_command/README.md
index bbeb35b26..a9483ca13 100644
--- a/the_shards_command/README.md
+++ b/the_shards_command/README.md
@@ -1,55 +1,54 @@
-# The shards command
+# 有關 Shards
-Crystal is typically accompanied by Shards, its dependency manager.
+Crystal 是一個被 Shards —— 它的相依管理器 —— 圍繞的語言。
-It manages dependencies for Crystal projects and libraries with reproducible
-installs across computers and systems.
+在 Crystal 的世界裡，我們稱呼每個 Crystal 專案為一個 shard。而 Shards 可以協助我們在專案裡面管理套件們之間的相依性，並在不同的環境中安裝這些套件。
-## Installation
+## 安裝
-Shards is usually distributed with Crystal itself. Alternatively, a separate `shards` package may be available for your system.
+Shards 通常會跟 Crystal 一起散佈，也可以透過直接安裝 `shards` 套件來取得。
-To install from source, download or clone [the repository](https://github.com/crystal-lang/shards) and run `make CRFLAGS=--release`. The compiled binary is in `bin/shards` and should be added to `PATH`.
+如果要從原始碼安裝 Shards，可以從這個 [Git 倉儲（Repository）](https://github.com/crystal-lang/shards)中取得原始碼並執行 `make CRFLAGS=--release`，編譯好的執行檔會被放置於 `bin/shards`，使用前記得加到 `PATH` 中。
-## Usage
+## 用法
-`shards` requires the presence of a `shard.yml` file in the project folder (working directory). This file describes the project and lists dependencies that are required to build it.
-A default file can be created by running [`shards init`](#shards-install).
-The file's contents are explained in the [*Writing a Shard* guide](../guides/writing_shards.md) and a detailed description of the file format is provided by the [shard.yml specification](https://github.com/crystal-lang/shards/blob/master/SPEC.md).
+Shards 需要在一個 shard 專案下使用，每個 shard 專案目錄（工作目錄）下都會有一個 `shard.yml` 檔案，而這個檔案會用來描述整個專案的資訊以及列出其相依清單。
+我們可以透過 [`shards init`](#shards-install) 指令來產生預設的 `shard.yml` 檔案。
+有關 `shard.yml` 內容的解釋可以查看[〈撰寫 Shards 指南〉](../guides/writing_shards.md)一章，而詳細的定義可以查看 [shard.yml specification](https://github.com/crystal-lang/shards/blob/master/SPEC.md) 一頁。
-Running [`shards install`](#shards-install) resolves and installs the specified dependencies.
-The installed versions are written into a `shard.lock` file for using the exact same dependency versions when running `shards install` again.
+執行 [`shards install`](#shards-install) 可以解析所有的相依套件並且安裝他們。
+所有已安裝的版本資訊都會被寫到 `shard.lock` 檔案中，供下次執行 `shards install` 時直接使用相同的版本。
-If your shard builds an application, both `shard.yml` and `shard.lock` should be checked into version control to provide reproducible dependency installs.
-If it is only a library for other shards to depend on, `shard.lock` should *not* be checked in, only `shard.yml`. It's good advice to add it to `.gitignore` (the [`crystal init`](../using_the_compiler/README.md#crystal-init) does this automatically when initializing a `lib` repository).
+如果你的 shard 是一個應用程式專案，那麼 `shard.yml` 及 `shard.lock` 檔案都應該被納入版本控制之中以復現這些相依套件的安裝版本。
+如果你的 shard 是一個函式庫專案，那麼 `shard.lock` 則不該被放入版本控制中，你可以透過 `.gitignore` 來自動忽略他們。而通常 [`crystal init`](../using_the_compiler/README.md#crystal-init) 指令會在建立函式庫專案時順便幫我們做好這件事。
-## Shards commands
+## Shards 指令
```bash
shards [...] []
```
-If no command is given, `install` will be run by default.
+如果沒有給定 ``，則預設會使用 `install`：
-* [`shards build`](#shards-build): Builds an executable
-* [`shards check`](#shards-check): Verifies dependencies are installed
-* [`shards init`](#shards-init): Generates a new `shard.yml`
-* [`shards install`](#shards-install): Resolves and installs dependencies
-* [`shards list`](#shards-list): Lists installed dependencies
-* [`shards prune`](#shards-prune): Removes unused dependencies
-* [`shards update`](#shards-update): Resolves and updates dependencies
-* [`shards version`](#shards-version): Shows version of a shard
+- [`shards build`](#shards-build)：建置執行檔
+- [`shards check`](#shards-check)：驗證所有相依套件皆已安裝
+- [`shards init`](#shards-init)：產生一個全新的 `shard.yml` 檔案
+- [`shards install`](#shards-install)：解析相依並安裝套件
+- [`shards list`](#shards-list)：列出所有已安裝的相依套件
+- [`shards prune`](#shards-prune)：移除未被使用的套件
+- [`shards update`](#shards-update)：重新解析相依並更新套件
+- [`shards version`](#shards-version)：顯示 Shard 的版本資訊
-To see the available options for a particular command, use `--help` after a command.
+如果想知道每個指令的詳細說明，可以在後面加上 `--help`。
-**Common options:**
+**通用選項：**
-* `--version`: Prints the version of `shards`.
-* `-h, --help`: Prints usage synopsis.
-* `--no-color`: Disabled colored output.
-* `--production`: Runs in release mode. Development dependencies won't be installed and only locked dependencies will be installed. Commands will fail if dependencies in `shard.yml` and `shard.lock` are out of sync (used by `install`, `update`, `check` and `list` command)
-* `-q, --quiet`: Decreases the log verbosity, printing only warnings and errors.
-* `-v, --verbose`: Increases the log verbosity, printing all debug statements.
+- `--version`：顯示 `shards` 指令的版本資訊
+- `-h, --help`：印出使用說明
+- `--no-color`：關閉彩色輸出
+- `--production`：發行模式，開發用相依套件不會在此模式下被安裝，而且只有被鎖定的相依套件會被安裝。也就是說如果 `shard.yml` 與 `shard.lock` 之間沒有同步的話指令會失敗（適用於 `install`、`update`、`check` 及 `list`）
+- `-q, --quiet`：減少日誌輸出，僅輸出警告及錯誤
+- `-v, --verbose`：增加日誌輸出，會輸出所有偵錯用資訊
### `shards build`
@@ -57,10 +56,10 @@ To see the available options for a particular command, use `--help` after a comm
shards build [] [...]
```
-Builds the specified targets in `bin` path. If no targets are specified, all are built.
-This command ensures all dependencies are installed, so it is not necessary to run `shards install` before.
+建置指定的目標並放置於 `bin` 目錄中，如果沒有指定目標，則會建置所有目標。
+這個指令會先確保所有的相依套件已安裝，所以在執行這個指令前其實不需要特別執行 `shards install`。
-All options following the command are delegated to `crystal build`.
+所有送給這個指令的參數都會被傳遞到底層呼叫的 `crystal build`。
### `shards check`
@@ -68,12 +67,12 @@ All options following the command are delegated to `crystal build`.
shards check
```
-Verifies that all dependencies are installed and requirements are satisfied.
+驗證所有相依套件是否皆已安裝並滿足需求。
-Exit status:
+狀態碼（Status Code）：
-* `0`: Dependencies are satisfied.
-* `1`: Dependencies are not satisfied.
+- `0`： 所有已安裝的套件皆已滿足相依
+- `1`： 有些相依套件未被安裝
### `shards init`
@@ -81,7 +80,7 @@ Exit status:
shards init
```
-Initializes a shard folder and creates a `shard.yml`.
+初始化一個 shard 專案並產生全新的 `shard.yml` 檔案。
### `shards install`
@@ -89,10 +88,9 @@ Initializes a shard folder and creates a `shard.yml`.
shards install
```
-Resolves and installs dependencies into the `lib` folder. If not already present, generates a `shard.lock` file from resolved dependencies, locking version
-numbers or Git commits.
+解析並安裝相依套件到 `lib` 目錄。如果 `shard.lock` 不存在，`shards` 會將解析完的版本（或 Git 提交）鎖定並描述在 `shard.lock` 中。
-Reads and enforces locked versions and commits if a `shard.lock` file is present. The install command may fail if a locked version doesn't match a requirement, but may succeed if a new dependency was added, as long as it doesn't generate a conflict, thus generating a new `shard.lock` file.
+反之，如果 `shard.lock` 存在，則 `shards install` 會使用已鎖定的版本。若已鎖定的版本與相依需求不符或衝突，則指令可能會失敗。如果有新的依賴套件被加入，在不衝突的情況下會自動更新 `shard.lock`。
### `shards list`
@@ -100,7 +98,7 @@ Reads and enforces locked versions and commits if a `shard.lock` file is present
shards list
```
-Lists the installed dependencies and their versions.
+列出所有已被安裝的相依套件及其版本。
### `shards prune`
@@ -108,7 +106,7 @@ Lists the installed dependencies and their versions.
shards prune
```
-Removes unused dependencies from lib folder.
+從 `lib` 目錄中移除已經不在相依列表中的套件。
### `shards update`
@@ -116,8 +114,7 @@ Removes unused dependencies from lib folder.
shards update
```
-Resolves and updates all dependencies into the lib folder again, whatever the locked versions and commits in the `shard.lock` file. Eventually generates a
-new `shard.lock` file.
+重新解析並安裝相依套件到 `lib` 目錄，並更新 `shard.lock` 檔案。
### `shards version`
@@ -125,4 +122,4 @@ new `shard.lock` file.
shards version []
```
-Prints the version of the shard.
+印出 `shards` 的版本。