Merge pull request #2394 from benluo/main

Author: SethTisue

_zh-cn/index.md

@@ -12,37 +12,37 @@ scala3-sections:
 - title: "第一步"
   links:
     - title: "Scala 3 中的新东西"
-      description: "Scala 3 现存新特性概览"
+      description: "Scala 3 中令人兴奋的新特性概览"
       icon: "fa fa-star"
       link: /scala3/new-in-scala3.html
     - title: "快速开始"
-      description: "安装 Scala 3 并开始写些 Scala 代码"
+      description: "在你的电脑中安装 Scala 3，然后开始写些 Scala 代码！"
       icon: "fa fa-rocket"
       link: /scala3/getting-started.html
-    - title: "Scala 3 书籍"
-      description: "一部介绍主要语言特性的线上书"
+    - title: "Scala 3 册子"
+      description: "通过一系列小课程来学习 Scala。"
       icon: "fa fa-book"
       link: /scala3/book/introduction.html
 - title: "更多细节"
   links:
     - title: "迁移指引"
-      description: "一份帮你从 Scala 2 迁移到 Scala 3 的指引"
+      description: "一份帮你从 Scala 2 迁移到 Scala 3 的指引。"
       icon: "fa fa-suitcase"
       link: /scala3/guides/migration/compatibility-intro.html
     - title: "导览"
-      description: "关于语言特别之处的详细导览"
+      description: "关于语言特别之处的详细导览。"
       icon: "fa fa-map"
       link: /zh-cn/scala3/guides.html
     - title: "Scala 库 API"
-      description: "Scala 3 标准库API文档（多个小版本）"
+      description: "Scala 3 每一个版本的标准库API文档。"
       icon: "fa fa-file-alt"
       link: https://scala-lang.org/api/3.x/
     - title: "语言参考手册"
-      description: "Scala 3 语言参考手册"
+      description: "Scala 3 语言参考手册。"
       icon: "fa fa-book"
       link: https://docs.scala-lang.org/scala3/reference
     - title: "贡献指南"
-      description: "Scala 3 编译器指南及如何贡献代码"
+      description: "Scala 3 编译器指南及如何修复问题"
       icon: "fa fa-cogs"
       link: /scala3/guides/contribution/contribution-intro.html
     - title: "Scala 3 全新的 Scaladoc"
@@ -109,4 +109,8 @@ scala2-sections:
         description: "Scala改进过程（Scala Improvement Process），语言及编译器进展"
         icon: "fa fa-cogs"
         link: /sips/index.html
+      - title: "为 Scala 作贡献"
+        description: "为 Scala 项目作贡献的完整指南"
+        icon: "fa fa-cogs"
+        link: /contribute/
 ---

_zh-cn/overviews/scala3-book/ca-context-bounds.md

@@ -0,0 +1,48 @@
+---
+title: 上下文绑定
+type: section
+description: This page demonstrates Context Bounds in Scala 3.
+num: 61
+previous-page: types-type-classes
+next-page: ca-given-imports
+---
+
+
+{% comment %}
+- TODO: define "context parameter"
+- TODO: define "synthesized" and "synthesized arguments"
+{% endcomment %}
+
+
+在许多情况下，_上下文参数_的名称不必明确提及，因为它仅由编译器在其他上下文参数的合成参数中使用。
+在这种情况下，您不必定义参数名称，只需提供参数类型即可。
+
+## 背景
+
+例如，这个 `maximum` 方法接受 `Ord` 类型的_上下文参数_，只是将它作为参数传递给 `max`：
+
+```scala
+def maximum[A](xs: List[A])(using ord: Ord[A]): A =
+  xs.reduceLeft(max(ord))
+```
+
+在该代码中，参数名称 `ord` 实际上不是必需的；它可以作为推断参数传递给 `max`，因此您只需声明 `maximum` 使用的类型 `Ord[A]` 而不必给它命名：
+
+```scala
+def maximum[A](xs: List[A])(using Ord[A]): A =
+  xs.reduceLeft(max)
+```
+
+## 上下文绑定
+
+鉴于此背景，_上下文绑定_是一种简写语法，用于表达“依赖于类型参数的上下文参数”模式。
+
+使用上下文绑定，`maximum` 方法可以这样写：
+
+```scala
+def maximum[A: Ord](xs: List[A]): A = xs.reduceLeft(max)
+```
+
+方法或类的类型参数 `A`，有类似 `:Ord` 的绑定，它表示有 `Ord[A]` 的上下文参数。
+
+有关上下文绑定的更多信息，请参阅 Scala 常见问题解答的 [“什么是上下文绑定？”](https://docs.scala-lang.org/tutorials/FAQ/context-bounds.html) 部分。

_zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md

@@ -0,0 +1,82 @@
+---
+title: 上下文抽象
+type: chapter
+description: This chapter provides an introduction to the Scala 3 concept of Contextual Abstractions.
+num: 58
+previous-page: types-others
+next-page: ca-given-using-clauses
+---
+
+
+## 背景
+
+隐式是Scala 2中的一个主要的设计特色。隐式是进行上下文抽象的基本方式。它们代表了具有多种用例的统一范式，其中包括：
+
+- 实现类型类
+- 建立上下文
+- 依赖注入
+- 表达能力
+- 计算新类型，并证明它们之间的关系
+
+此后，其他语言也纷纷效仿，例如 Rust 的 traits 或 Swift 的协议扩展。对于编译期的依赖解析方案，Kotlin 的设计方案也被提上日程，而对 C# 而言是 Shapes 和 Extensions 或对 F# 来说是 Traits。Implicits 也是 Coq 或 Agda 等定理证明器的共同特色。
+
+尽管这些设计使用不同的术语，但它们都是*术语推理*核心思想的变体：
+给定一个类型，编译器会合成一个具有该类型的“canonical”术语。
+
+## 重新设计
+
+Scala 3 重新设计了 Scala 中的上下文抽象。
+虽然这些概念是在 Scala 2 中逐渐“发现”的，但它们现在已广为人知和理解，并且重新设计利用了这些知识。
+
+Scala 3 的设计侧重于 **意图** 而不是 **机制**。
+Scala 3 没有提供一个非常强大的隐式特性，而是提供了几个面向用例的特性：
+
+- **抽象上下文信息**。
+  [使用子句][givens] 允许程序员对调用上下文中可用的信息进行抽象，并且应该隐式传递。
+  作为对 Scala 2 隐式的改进，可以按类型指定 using 子句，从而将函数签名从从未显式引用的术语变量名称中释放出来。
+
+- **提供类型类实例**。
+  [给定实例][type-classes]允许程序员定义某种类型的_规范值(canonical value)_。
+  这使得使用类型类的编程更加简单，而不会泄露实现细节。
+
+- **追溯扩展类**。
+  在 Scala 2 中，扩展方法必须使用隐式转换或隐式类进行编码。
+  相比之下，在 Scala 3 [扩展方法][extension-methods] 现在直接内置到语言中，产生了更好的错误消息和改进的类型推断。
+
+- **将一种类型视为另一种类型**。
+  隐式转换已从头开始[重新设计][implicit-conversions]，作为类型类 `Conversion` 的实例。
+
+- **高阶上下文抽象**。
+  [上下文函数][contextual-functions] 的_全新_特性使上下文抽象成为一等公民。
+  它们是库作者的重要工具，可以表达简洁的领域特定语言。
+
+- **来自编译器的可操作反馈**。
+  如果编译器无法解析隐式参数，它现在会为您提供 [导入建议](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html) 来解决问题。
+
+## 好处
+
+Scala 3 中的这些更改实现了术语推理与语言其余部分的更好分离：
+
+- 仅有一种定义 given 的方法
+- 仅有一种方法可以引入隐式参数和自变量
+- [导入 givens][given-imports] 仅有一种单独的方法，不允许它们隐藏在正常导入的海洋中
+- 定义 [隐式转换][implicit-conversions] 的方法仅有一种，它被清楚地标记为这样，并且不需要特殊的语法
+
+这些变化的好处包括：
+
+- 新设计避免了特性交织，从而使语言更加一致
+- 它使隐式更容易学习和更难滥用
+- 它极大地提高了 95% 使用隐式的 Scala 程序的清晰度
+- 它有可能以一种易于理解和友好的原则方式进行术语推理
+
+本章将在以下各节中介绍其中的许多新功能。
+
+
+[givens]: {% link _overviews/scala3-book/ca-given-using-clauses.md %}
+[given-imports]: {% link _overviews/scala3-book/ca-given-imports.md %}
+[implicit-conversions]: {% link _overviews/scala3-book/ca-implicit-conversions.md %}
+[extension-methods]: {% link _overviews/scala3-book/ca-extension-methods.md %}
+[context-bounds]: {% link _overviews/scala3-book/ca-context-bounds.md %}
+[type-classes]: {% link _overviews/scala3-book/ca-type-classes.md %}
+[equality]: {% link _overviews/scala3-book/ca-multiversal-equality.md %}
+[contextual-functions]: {% link _overviews/scala3-book/types-dependent-function.md %}

_zh-cn/overviews/scala3-book/ca-extension-methods.md

@@ -0,0 +1,83 @@
+---
+title: 扩展方法
+type: section
+description: This page demonstrates how Extension Methods work in Scala 3.
+num: 63
+previous-page: ca-given-imports
+next-page: ca-type-classes
+---
+
+
+扩展方法允许您在定义类型后向类型添加方法，即它们允许您向封闭类添加新方法。
+例如，假设其他人创建了一个 `Circle` 类：
+
+```scala
+case class Circle(x: Double, y: Double, radius: Double)
+```
+
+现在想象一下，你需要一个 `circumference` 方法，但是你不能修改它们的源代码。
+在将术语推理的概念引入编程语言之前，您唯一能做的就是在单独的类或对象中编写一个方法，如下所示：
+
+```scala
+object CircleHelpers:
+  def circumference(c: Circle): Double = c.radius * math.Pi * 2
+```
+
+你可以像这样用该方法：
+
+```scala
+val aCircle = Circle(2, 3, 5)
+
+// without extension methods
+CircleHelpers.circumference(aCircle)
+```
+
+但是使用扩展方法，您可以创建一个 `circumference` 方法来处理 `Circle` 实例：
+
+```scala
+extension (c: Circle)
+  def circumference: Double = c.radius * math.Pi * 2
+```
+
+在这段代码中：
+
+- 扩展方法 `circumference` 将添加到 `Circle` 类型里
+- `c: Circle` 语法允许您在扩展方法中引用变量 `c`
+
+然后在您的代码中使用 `circumference`，就像它最初是在 `Circle` 类中定义的一样：
+
+```scala
+aCircle.circumference
+```
+
+### 导入扩展方法
+
+想象一下，`circumference` 定义在`lib` 包中，你可以通过以下方式导入它
+
+```scala
+import lib.circumference
+
+aCircle.circumference
+```
+
+如果缺少导入，编译器还会通过显示详细的编译错误消息来支持您，如下所示：
+
+```text
+value circumference is not a member of Circle, but could be made available as an extension method.
+
+The following import might fix the problem:
+
+   import lib.circumference
+```
+
+## 讨论
+
+`extension` 关键字声明您将要在括号中的类型上定义一个或多个扩展方法。
+要在一个类型上定义多个扩展方法，请使用以下语法：
+
+```scala
+extension (c: Circle)
+  def circumference: Double = c.radius * math.Pi * 2
+  def diameter: Double = c.radius * 2
+  def area: Double = math.Pi * c.radius * c.radius
+```

_zh-cn/overviews/scala3-book/ca-given-imports.md

@@ -0,0 +1,48 @@
+---
+title: Given 导入
+type: section
+description: This page demonstrates how 'given' import statements work in Scala 3.
+num: 62
+previous-page: ca-context-bounds
+next-page: ca-extension-methods
+---
+
+
+为了更清楚地说明当前作用域中的 given 来自何处，我们使用一种特殊形式的 `import` 语句来导入 `given` 实例。
+此示例中显示了基本形式：
+
+```scala
+object A:
+  class TC
+  given tc: TC = ???
+  def f(using TC) = ???
+
+object B:
+  import A.*       // import all non-given members
+  import A.given   // import the given instance
+```
+
+在此代码中，对象 `B` 的 `import A.*` 子句导入 `A` 的所有成员*除了* `given` 实例 `tc`。
+相反，第二个导入 `import A.given` *仅*导入 `given` 实例。
+两个 `import` 子句也可以合并为一个：
+
+```scala
+object B:
+  import A.{given, *}
+```
+
+## 讨论
+
+通配符选择器 `*` 将除 given 或扩展之外的所有定义都导入作用域，而 `given` 选择器将所有 *given* 定义---包括由扩展而来的定义---导入作用域。
+
+这些规则有两个主要优点：
+
+- 更清楚当前作用域内 given 的来源。
+  特别是，在一长串其他通配符导入中无法隐藏导入的 given 。
+- 它可以导入所有 given ，而无需导入任何其他内容。
+  这很重要，因为 given 是可以匿名的，因此通常使用命名导入是不切实际的。
+
+“导入 given”语法的更多示例见 [package 和 import 章节][imports]。
+
+
+[imports]: {% link _overviews/scala3-book/packaging-imports.md %}