Skip to content

Commit f8aef20

Browse files
EnochGaoEnochGao
authored
Merge pull request #97 from ts-zh-docs/publishing
init translation of publishing
2 parents 636590d + 4d8ec55 commit f8aef20

File tree

1 file changed

+44
-60
lines changed

1 file changed

+44
-60
lines changed

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

Lines changed: 44 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,23 @@
11
---
2-
title: Publishing
2+
title: 发布
33
layout: docs
44
permalink: /zh/docs/handbook/declaration-files/publishing.html
5-
oneline: How to get your d.ts files to users
5+
oneline: 如何向用户提供 d.ts 文件
66
---
77

8-
Now that you have authored a declaration file following the steps of this guide, it is time to publish it to npm.
9-
There are two main ways you can publish your declaration files to npm:
8+
现在你已经按照本指南的步骤编写了声明文件，是时候将其发布到 npm 上了。主要有两种方式可以将你的声明文件发布到 npm：
109

11-
1. bundling with your npm package
12-
2. publishing to the [@types organization](https://www.npmjs.com/~types) on npm.
10+
1. 将其与你的 npm 包捆绑在一起。
11+
2. 将其发布到 npm 上的 [@types 组织](https://www.npmjs.com/~types)。
1312

14-
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).
13+
如果你的类型是由源代码生成的，请与源代码一起发布这些类型。TypeScript 和 JavaScript 项目都可以通过 [`declaration`](/zh/tsconfig#declaration) 生成类型。
1514

16-
Otherwise, we recommend submitting the types to DefinitelyTyped, which will publish them to the `@types` organization on npm.
15+
否则，我们建议将这些类型提交到 DefinitelyTyped，DefinitelyTyped 将会将它们发布到 npm 上的 `@types` 组织中。
1716

18-
## Including declarations in your npm package
19-
20-
If your package has a main `.js` file, you will need to indicate the main declaration file in your `package.json` file as well.
21-
Set the `types` property to point to your bundled declaration file.
22-
For example:
17+
## 在你的 npm 包中包含声明文件
2318

19+
如果你的包有一个主要的 `.js` 文件，你需要在你的 `package.json` 文件中指定主要的声明文件。将 `types` 属性设置为指向捆绑的声明文件。例如：
20+
2421
```json
2522
{
2623
"name": "awesome",
@@ -31,14 +28,11 @@ For example:
3128
}
3229
```
3330

34-
Note that the `"typings"` field is synonymous with `types`, and could be used as well.
35-
31+
请注意，`"typings"` 字段与 `types` 同义，也可以使用。
3632

37-
## Dependencies
33+
## 依赖
3834

39-
All dependencies are managed by npm.
40-
Make sure all the declaration packages you depend on are marked appropriately in the `"dependencies"` section in your `package.json`.
41-
For example, imagine we authored a package that used Browserify and TypeScript.
35+
所有依赖关系由 npm 管理。确保你所依赖的所有声明包在你的 `package.json` 文件的 `"dependencies"` 部分中得到适当标记。例如，假设我们编写了一个使用 Browserify 和 TypeScript 的包。
4236

4337
```json
4438
{
@@ -55,49 +49,45 @@ For example, imagine we authored a package that used Browserify and TypeScript.
5549
}
5650
```
5751

58-
Here, our package depends on the `browserify` and `typescript` packages.
59-
`browserify` does not bundle its declaration files with its npm packages, so we needed to depend on `@types/browserify` for its declarations.
60-
`typescript`, on the other hand, packages its declaration files, so there was no need for any additional dependencies.
52+
在这里，我们的包依赖于 `browserify` 和 `typescript` 包。`browserify` 没有将其声明文件与其 npm 包捆绑在一起，因此我们需要依赖于 `@types/browserify` 来获取其声明。另一方面，`typescript` 包含其声明文件，因此不需要任何额外的依赖。
6153

62-
Our package exposes declarations from each of those, so any user of our `browserify-typescript-extension` package needs to have these dependencies as well.
63-
For that reason, we used `"dependencies"` and not `"devDependencies"`, because otherwise our consumers would have needed to manually install those packages.
64-
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`.
54+
我们的包在每个包中公开了声明，因此我们的 `browserify-typescript-extension` 包的任何用户也需要具有这些依赖项。因此，我们使用了 `"dependencies"` 而不是 `"devDependencies"`，否则我们的消费者将需要手动安装这些包。如果我们只是编写了一个命令行应用程序，而不希望我们的包被用作库，那么我们可以使用 `devDependencies`。
6555

66-
## Red flags
56+
## 标识
6757

6858
### `/// <reference path="..." />`
6959

70-
_Don't_ use `/// <reference path="..." />` in your declaration files.
60+
在你的声明文件中*不要*使用 `/// <reference path="..." />`。
7161

7262
```ts
7363
/// <reference path="../typescript/lib/typescriptServices.d.ts" />
7464
....
7565
```
7666

77-
_Do_ use `/// <reference types="..." />` instead.
67+
相反，*要*使用 `/// <reference types="..." />`。
7868

7969
```ts
8070
/// <reference types="typescript" />
8171
....
8272
```
8373

84-
Make sure to revisit the [Consuming dependencies](/zh/docs/handbook/declaration-files/library-structures.html#consuming-dependencies) section for more information.
74+
确保查看[消耗依赖项](/zh/docs/handbook/declaration-files/library-structures.html#consuming-dependencies) 部分以获取更多信息。
8575

86-
### Packaging dependent declarations
76+
### 打包依赖声明
8777

88-
If your type definitions depend on another package:
78+
如果你的类型定义依赖于另一个包：
8979

90-
- _Don't_ combine it with yours, keep each in their own file.
91-
- _Don't_ copy the declarations in your package either.
92-
- _Do_ depend on the npm type declaration package if it doesn't package its declaration files.
80+
- *不要*将其与你的包合并在一起，保持每个包在自己的文件中。
81+
- *不要*复制在你的包中的声明。
82+
- 如果它没有将其声明文件打包在一起，*要*依赖于 npm 类型声明包。
9383

94-
## Version selection with `typesVersions`
84+
## 使用 `typesVersions` 进行版本选择
9585

96-
When TypeScript opens a `package.json` file to figure out which files it needs to read, it first looks at a field called `typesVersions`.
86+
当 TypeScript 打开一个 `package.json` 文件以确定需要读取的文件时，首先查看一个名为 `typesVersions` 的字段。
9787

98-
#### Folder redirects (using `*`)
88+
#### 文件夹重定向（使用 `*`）
9989

100-
A `package.json` with a `typesVersions` field might look like this:
90+
具有 `typesVersions` 字段的 `package.json` 可能如下所示：
10191

10292
```json
10393
{
@@ -110,20 +100,17 @@ A `package.json` with a `typesVersions` field might look like this:
110100
}
111101
```
112102

113-
This `package.json` tells TypeScript to first check the current version of TypeScript.
114-
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.
103+
这个 `package.json` 告诉 TypeScript 首先检查当前版本的 TypeScript。如果是 3.1 或更高版本，TypeScript 将查找你相对于包导入的路径，并从包的 `ts3.1` 文件夹中读取。
115104

116-
That's what that `{ "*": ["ts3.1/*"] }` means - if you're familiar with [path mapping](/tsconfig#paths), it works exactly like that.
105+
这就是 `{ "*": ["ts3.1/*"] }` 的含义——如果你熟悉[路径映射](/zh/tsconfig#paths)，它的工作方式与此相同。
117106

118-
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.
119-
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`.
107+
在上面的示例中，如果我们导入 `"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`。
120108

121-
What if we're not running in TypeScript 3.1 in this example?
122-
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`.
109+
在这个示例中，如果我们没有在 TypeScript 3.1 中运行会发生什么呢？如果 `typesVersions` 中没有任何字段匹配，TypeScript 将退回到 `types` 字段，因此在这里，TypeScript 3.0 及更早版本将被重定向到 `[...]/node_modules/package-name/index.d.ts`。
123110

124-
#### File redirects
111+
#### 文件重定向
125112

126-
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:
113+
当你只想一次更改单个文件的解析时，你可以通过传递确切的文件名告诉 TypeScript 差异性地解析文件：
127114

128115
```json
129116
{
@@ -136,17 +123,17 @@ When you want to only change the resolution for a single file at a time, you can
136123
}
137124
```
138125

139-
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`.
126+
在 TypeScript 4.0 及更高版本中，对 `"package-name"` 的导入将解析为 `./index.d.ts`，而对于 3.9 及以下版本则解析为 `"./index.v3.d.ts"`。
140127

141-
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`.
128+
请注意，重定向仅影响包的*外部* API；`typesVersions` 不会影响项目内的导入解析。例如，前面示例中包含 `import * as foo from "./index"` 的 `d.ts` 文件仍将映射到 `index.d.ts`，而另一个导入 `import * as foo from "package-name"` 的包将获取 `index.v3.d.ts`。
142129

143-
## Matching behavior
130+
## 匹配行为
144131

145-
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).
132+
TypeScript 通过使用 Node 的 [semver 范围](https://github.com/npm/node-semver#ranges)来决定编译器和语言版本是否匹配。
146133

147-
## Multiple fields
134+
## 多个字段
148135

149-
`typesVersions` can support multiple fields where each field name is specified by the range to match on.
136+
`typesVersions` 可以支持多个字段，其中每个字段名称由要匹配的范围指定。
150137

151138
```json tsconfig
152139
{
@@ -160,24 +147,21 @@ The way that TypeScript decides on whether a version of the compiler & language
160147
}
161148
```
162149

163-
Since ranges have the potential to overlap, determining which redirect applies is order-specific.
164-
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.
150+
由于范围有可能重叠，确定应用哪个重定向是有序的。这意味着在上面的示例中，即使 `>=3.2` 和 `>=3.1` 匹配器都支持 TypeScript 3.2 及更高版本，但颠倒顺序可能会有不同的行为，因此上面的示例将不等同于以下内容。
165151

166152
```jsonc tsconfig
167153
{
168154
"name": "package-name",
169155
"version": "1.0",
170156
"types": "./index.d.ts",
171157
"typesVersions": {
172-
// NOTE: this doesn't work!
158+
// 注意：这样做不起作用！
173159
">=3.1": { "*": ["ts3.1/*"] },
174160
">=3.2": { "*": ["ts3.2/*"] }
175161
}
176162
}
177163
```
178164

179-
## Publish to [@types](https://www.npmjs.com/~types)
165+
## 发布至 [@types](https://www.npmjs.com/~types)
180166

181-
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).
182-
To get your declarations published as an @types package, please submit a pull request to [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped).
183-
You can find more details in the [contribution guidelines page](https://definitelytyped.github.io/guides/contributing.html).
167+
[@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)中找到更多详细信息。

0 commit comments

Comments
 (0)