init translation of publishing

docs/documentation/zh/declaration-files/Publishing.md

@@ -1,26 +1,23 @@
 ---
-title: Publishing
+title: 发布
 layout: docs
 permalink: /zh/docs/handbook/declaration-files/publishing.html
-oneline: How to get your d.ts files to users
+oneline: 如何向用户提供 d.ts 文件
 ---
 
-Now that you have authored a declaration file following the steps of this guide, it is time to publish it to npm.
-There are two main ways you can publish your declaration files to npm:
+现在你已经按照本指南的步骤编写了声明文件，是时候将其发布到 npm 上了。主要有两种方式可以将你的声明文件发布到 npm：
 
-1. bundling with your npm package
-2. publishing to the [@types organization](https://www.npmjs.com/~types) on npm.
+1. 将其与你的 npm 包捆绑在一起。
+2. 将其发布到 npm 上的 [@types 组织](https://www.npmjs.com/~types)。
 
-If your types are generated by your source code, publish the types with your source code. Both TypeScript and JavaScript projects can generate types via [`declaration`](/tsconfig#declaration).
+如果你的类型是由源代码生成的，请与源代码一起发布这些类型。TypeScript 和 JavaScript 项目都可以通过 [`declaration`](/zh/tsconfig#declaration) 生成类型。
 
-Otherwise, we recommend submitting the types to DefinitelyTyped, which will publish them to the `@types` organization on npm.
+否则，我们建议将这些类型提交到 DefinitelyTyped，DefinitelyTyped 将会将它们发布到 npm 上的 `@types` 组织中。
 
-## Including declarations in your npm package
-
-If your package has a main `.js` file, you will need to indicate the main declaration file in your `package.json` file as well.
-Set the `types` property to point to your bundled declaration file.
-For example:
+## 在你的 npm 包中包含声明文件
 
+如果你的包有一个主要的 `.js` 文件，你需要在你的 `package.json` 文件中指定主要的声明文件。将 `types` 属性设置为指向捆绑的声明文件。例如：
+
 ```json
 {
   "name": "awesome",
@@ -31,14 +28,11 @@ For example:
 }
 ```
 
-Note that the `"typings"` field is synonymous with `types`, and could be used as well.
-
+请注意，`"typings"` 字段与 `types` 同义，也可以使用。
 
-## Dependencies
+## 依赖
 
-All dependencies are managed by npm.
-Make sure all the declaration packages you depend on are marked appropriately in the `"dependencies"` section in your `package.json`.
-For example, imagine we authored a package that used Browserify and TypeScript.
+所有依赖关系由 npm 管理。确保你所依赖的所有声明包在你的 `package.json` 文件的 `"dependencies"` 部分中得到适当标记。例如，假设我们编写了一个使用 Browserify 和 TypeScript 的包。
 
 ```json
 {
@@ -55,49 +49,45 @@ For example, imagine we authored a package that used Browserify and TypeScript.
 }
 ```
 
-Here, our package depends on the `browserify` and `typescript` packages.
-`browserify` does not bundle its declaration files with its npm packages, so we needed to depend on `@types/browserify` for its declarations.
-`typescript`, on the other hand, packages its declaration files, so there was no need for any additional dependencies.
+在这里，我们的包依赖于 `browserify` 和 `typescript` 包。`browserify` 没有将其声明文件与其 npm 包捆绑在一起，因此我们需要依赖于 `@types/browserify` 来获取其声明。另一方面，`typescript` 包含其声明文件，因此不需要任何额外的依赖。
 
-Our package exposes declarations from each of those, so any user of our `browserify-typescript-extension` package needs to have these dependencies as well.
-For that reason, we used `"dependencies"` and not `"devDependencies"`, because otherwise our consumers would have needed to manually install those packages.
-If we had just written a command line application and not expected our package to be used as a library, we might have used `devDependencies`.
+我们的包在每个包中公开了声明，因此我们的 `browserify-typescript-extension` 包的任何用户也需要具有这些依赖项。因此，我们使用了 `"dependencies"` 而不是 `"devDependencies"`，否则我们的消费者将需要手动安装这些包。如果我们只是编写了一个命令行应用程序，而不希望我们的包被用作库，那么我们可以使用 `devDependencies`。
 
-## Red flags
+## 标识
 
 ### `/// <reference path="..." />`
 
-_Don't_ use `/// <reference path="..." />` in your declaration files.
+在你的声明文件中*不要*使用 `/// <reference path="..." />`。
 
 ```ts
 /// <reference path="../typescript/lib/typescriptServices.d.ts" />
 ....
 ```
 
-_Do_ use `/// <reference types="..." />` instead.
+相反，*要*使用 `/// <reference types="..." />`。
 
 ```ts
 /// <reference types="typescript" />
 ....
 ```
 
-Make sure to revisit the [Consuming dependencies](/zh/docs/handbook/declaration-files/library-structures.html#consuming-dependencies) section for more information.
+确保查看[消耗依赖项](/zh/docs/handbook/declaration-files/library-structures.html#consuming-dependencies) 部分以获取更多信息。
 
-### Packaging dependent declarations
+### 打包依赖声明
 
-If your type definitions depend on another package:
+如果你的类型定义依赖于另一个包：
 
-- _Don't_ combine it with yours, keep each in their own file.
-- _Don't_ copy the declarations in your package either.
-- _Do_ depend on the npm type declaration package if it doesn't package its declaration files.
+- *不要*将其与你的包合并在一起，保持每个包在自己的文件中。
+- *不要*复制在你的包中的声明。
+- 如果它没有将其声明文件打包在一起，*要*依赖于 npm 类型声明包。
 
-## Version selection with `typesVersions`
+## 使用 `typesVersions` 进行版本选择
 
-When TypeScript opens a `package.json` file to figure out which files it needs to read, it first looks at a field called `typesVersions`.
+当 TypeScript 打开一个 `package.json` 文件以确定需要读取的文件时，首先查看一个名为 `typesVersions` 的字段。
 
-#### Folder redirects (using `*`)
+#### 文件夹重定向（使用 `*`）
 
-A `package.json` with a `typesVersions` field might look like this:
+具有 `typesVersions` 字段的 `package.json` 可能如下所示：
 
 ```json
 {
@@ -110,20 +100,17 @@ A `package.json` with a `typesVersions` field might look like this:
 }
 ```
 
-This `package.json` tells TypeScript to first check the current version of TypeScript.
-If it's 3.1 or later, TypeScript figures out the path you've imported relative to the package, and reads from the package's `ts3.1` folder.
+这个 `package.json` 告诉 TypeScript 首先检查当前版本的 TypeScript。如果是 3.1 或更高版本，TypeScript 将查找你相对于包导入的路径，并从包的 `ts3.1` 文件夹中读取。
 
-That's what that `{ "*": ["ts3.1/*"] }` means - if you're familiar with [path mapping](/tsconfig#paths), it works exactly like that.
+这就是 `{ "*": ["ts3.1/*"] }` 的含义——如果你熟悉[路径映射](/zh/tsconfig#paths)，它的工作方式与此相同。
 
-In the above example, if we're importing from `"package-name"`, TypeScript will try to resolve from `[...]/node_modules/package-name/ts3.1/index.d.ts` (and other relevant paths) when running in TypeScript 3.1.
-If we import from `package-name/foo`, we'll try to look for `[...]/node_modules/package-name/ts3.1/foo.d.ts` and `[...]/node_modules/package-name/ts3.1/foo/index.d.ts`.
+在上面的示例中，如果我们导入 `"package-name"`，TypeScript 将尝试在 TypeScript 3.1 运行时从 `[...]/node_modules/package-name/ts3.1/index.d.ts`（以及其他相关路径）解析。如果我们导入 `package-name/foo`，TypeScript 将尝试查找 `[...]/node_modules/package-name/ts3.1/foo.d.ts` 和 `[...]/node_modules/package-name/ts3.1/foo/index.d.ts`。
 
-What if we're not running in TypeScript 3.1 in this example?
-Well, if none of the fields in `typesVersions` get matched, TypeScript falls back to the `types` field, so here TypeScript 3.0 and earlier will be redirected to `[...]/node_modules/package-name/index.d.ts`.
+在这个示例中，如果我们没有在 TypeScript 3.1 中运行会发生什么呢？如果 `typesVersions` 中没有任何字段匹配，TypeScript 将退回到 `types` 字段，因此在这里，TypeScript 3.0 及更早版本将被重定向到 `[...]/node_modules/package-name/index.d.ts`。
 
-#### File redirects
+#### 文件重定向
 
-When you want to only change the resolution for a single file at a time, you can tell TypeScript the file to resolve differently by passing in the exact filenames:
+当你只想一次更改单个文件的解析时，你可以通过传递确切的文件名告诉 TypeScript 差异性地解析文件：
 
 ```json
 {
@@ -136,17 +123,17 @@ When you want to only change the resolution for a single file at a time, you can
 }
 ```
 
-On TypeScript 4.0 and above, an import for `"package-name"` would resolve to `./index.d.ts` and for 3.9 and below `"./index.v3.d.ts`.
+在 TypeScript 4.0 及更高版本中，对 `"package-name"` 的导入将解析为 `./index.d.ts`，而对于 3.9 及以下版本则解析为 `"./index.v3.d.ts"`。
 
-Note that redirections only affect the _external_ API of a package; import resolution within a project is not affected by `typesVersions`. For example, a `d.ts` file in the previous example containing `import * as foo from "./index"` will still map to `index.d.ts`, not `index.v3.d.ts`, whereas another package importing `import * as foo from "package-name"` _will_ get `index.v3.d.ts`.
+请注意，重定向仅影响包的*外部* API；`typesVersions` 不会影响项目内的导入解析。例如，前面示例中包含 `import * as foo from "./index"` 的 `d.ts` 文件仍将映射到 `index.d.ts`，而另一个导入 `import * as foo from "package-name"` 的包将获取 `index.v3.d.ts`。
 
-## Matching behavior
+## 匹配行为
 
-The way that TypeScript decides on whether a version of the compiler & language matches is by using Node's [semver ranges](https://github.com/npm/node-semver#ranges).
+TypeScript 通过使用 Node 的 [semver 范围](https://github.com/npm/node-semver#ranges)来决定编译器和语言版本是否匹配。
 
-## Multiple fields
+## 多个字段
 
-`typesVersions` can support multiple fields where each field name is specified by the range to match on.
+`typesVersions` 可以支持多个字段，其中每个字段名称由要匹配的范围指定。
 
 ```json tsconfig
 {
@@ -160,24 +147,21 @@ The way that TypeScript decides on whether a version of the compiler & language
 }
 ```
 
-Since ranges have the potential to overlap, determining which redirect applies is order-specific.
-That means in the above example, even though both the `>=3.2` and the `>=3.1` matchers support TypeScript 3.2 and above, reversing the order could have different behavior, so the above sample would not be equivalent to the following.
+由于范围有可能重叠，确定应用哪个重定向是有序的。这意味着在上面的示例中，即使 `>=3.2` 和 `>=3.1` 匹配器都支持 TypeScript 3.2 及更高版本，但颠倒顺序可能会有不同的行为，因此上面的示例将不等同于以下内容。
 
 ```jsonc tsconfig
 {
   "name": "package-name",
   "version": "1.0",
   "types": "./index.d.ts",
   "typesVersions": {
-    // NOTE: this doesn't work!
+    // 注意：这样做不起作用！
     ">=3.1": { "*": ["ts3.1/*"] },
     ">=3.2": { "*": ["ts3.2/*"] }
   }
 }
 ```
 
-## Publish to [@types](https://www.npmjs.com/~types)
+## 发布至 [@types](https://www.npmjs.com/~types)
 
-Packages under the [@types](https://www.npmjs.com/~types) organization are published automatically from [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) using the [types-publisher tool](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher).
-To get your declarations published as an @types package, please submit a pull request to [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped).
-You can find more details in the [contribution guidelines page](https://definitelytyped.github.io/guides/contributing.html).
+[@types](https://www.npmjs.com/~types) 组织下包是通过 [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) 使用 [types-publisher 工具](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher) 自动发布的。要将你的声明发布为 @types 包，请向 [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) 提交拉取请求。你可以在[贡献指南页面](https://definitelytyped.github.io/guides/contributing.html)中找到更多详细信息。