Skip to content

Commit f3176ef

Browse files
authored
chore: use OpenAI compatible services instead, change related environments (#306)
1 parent 62d6f03 commit f3176ef

4 files changed

Lines changed: 57 additions & 52 deletions

File tree

‎.changeset/orange-books-burn.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"@alauda/doom": minor
3+
---
4+
5+
chore: switch to OpenAI-compatible service config and rename related env vars
6+
7+
Migration: replace `AZURE_OPENAI_ENDPOINT` / `AZURE_OPENAI_API_KEY` / `AZURE_OPENAI_MODEL` with `ALAUDA_OPENAI_BASE_URL` / `ALAUDA_OPENAI_API_KEY` / `ALAUDA_OPENAI_MODEL`.

‎docs/en/start.mdx‎

Lines changed: 41 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sourceSHA: fa1b3035de2eb1166334fa4c487575bc32fe4886a888be9b9a5efbf7486044cb
2+
sourceSHA: 93a5f6e098906ab31f8264571e394b1f030f5b74cd652e837df39857035545eb
33
---
44

55
# Getting Started \{#start}
@@ -12,19 +12,19 @@ First, you can create a new directory with the following command:
1212
mkdir my-docs && cd my-docs
1313
```
1414

15-
Run `npm init -y` to initialize a project. You can install doom using npm, yarn, or pnpm:
15+
Run `npm init -y` to initialize a project. You can use npm, yarn, or pnpm to install doom:
1616

1717
<PackageManagerTabs command="install -D @alauda/doom typescript" />
1818

19-
Then create files with the following commands:
19+
Then create the files with the following commands:
2020

2121
```bash
22-
# Create docs directories, default supports bilingual Chinese and English
22+
# Create the docs directory, bilingual support for Chinese and English is enabled by default
2323
mkdir docs/en && echo '# Hello World' > docs/en/index.md
2424
mkdir docs/zh && echo '# 你好世界' > docs/zh/index.md
2525
```
2626

27-
Add the following scripts to your `package.json`:
27+
Add the following scripts to `package.json`:
2828

2929
```json
3030
{
@@ -45,7 +45,7 @@ Then initialize a configuration file `doom.config.yml`:
4545
title: My Docs
4646
```
4747
48-
Also create a `tsconfig.json` file with the following content:
48+
At the same time, create a new `tsconfig.json` with the following content:
4949

5050
```jsonc
5151
{
@@ -72,7 +72,7 @@ Finally, create a `global.d.ts` file with the following content:
7272
/// <reference types="@alauda/doom/runtime" />
7373
```
7474

75-
This allows you to use doom's global components in `.mdx` files with type safety.
75+
This way, you can use the global components provided by doom in `.mdx` files with type safety.
7676

7777
## CLI Tool \{#cli}
7878

@@ -118,11 +118,11 @@ Commands:
118118
help [command] display help for command
119119
```
120120
121-
For more configuration, please refer to [Configuration](./usage/configuration)
121+
For more configuration, see [Configuration](./usage/configuration)
122122
123-
### Starting the Development Server \{#dev}
123+
### Start the Development Server \{#dev}
124124
125-
Run `yarn dev` to start the development server, the browser will automatically open the documentation homepage.
125+
Run `yarn dev` to start the development server, and the browser will automatically open the documentation home page
126126

127127
```sh
128128
doom dev -h
@@ -145,17 +145,17 @@ Options:
145145

146146
### Production Build \{#build}
147147

148-
Run `yarn build` to build the production code. After building, static files will be generated in the `dist` directory.
148+
Run `yarn build` to build the production code. After the build is complete, static files will be generated in the `dist` directory.
149149

150150
### Local Preview \{#serve}
151151

152-
Run `yarn serve` to preview the built static files. Note that if you used `-b` or `-p` parameters during build, you need to use the same `-b` and `-p` parameters during preview.
152+
Run `yarn serve` to preview the built static files. Note that if you built with the `-b`, `-p` parameters, you also need to use the `-b`, `-p` parameters when previewing.
153153

154-
### Using Scaffolding Templates \{#new}
154+
### Use Scaffold Templates \{#new}
155155

156-
Run `yarn new` to generate projects, modules, or documentation using scaffolding templates.
156+
Run `yarn new` to generate a project, module, or documentation using scaffold templates.
157157

158-
### Translating Documentation \{#translate}
158+
### Translate Documentation \{#translate}
159159

160160
```bash
161161
doom translate -h
@@ -176,43 +176,44 @@ Options:
176176
-h, --help display help for command
177177
```
178178

179-
- The `-g, --glob` parameter is required. You can specify the directories or files to translate, supporting `glob` syntax. Note that the parameter value must be quoted to avoid unexpected behavior caused by command line parsing. Examples:
180-
1. `yarn translate -g abc xyz` will translate all documents under `<root>/<source>/abc` and `<root>/<source>/xyz` to `<root>/<target>/abc` and `<root>/<target>/xyz` respectively.
181-
2. `yarn translate -g '*'` will translate all documents under `<root>/<source>`.
182-
- The `-C, --copy` parameter is optional. It controls whether to copy local resource files to the target directory when the target file does not exist. The default is `false`, which means changing the resource file reference path to the source path. Examples:
183-
- When enabled:
184-
1. When translating `/<source>/abc.jpg`, it will copy `<root>/public/<source>/abc.jpg` to `<root>/public/<target>/abc.jpg` and modify the reference path in the document to `/<target>/abc.jpg`.
185-
2. In `<root>/<source>/abc.mdx`, when translating `./assets/xyz.jpg`, it will copy `<root>/<source>/assets/xyz.jpg` to `<root>/<target>/assets/xyz.jpg`, and the image reference path remains unchanged.
186-
3. In `<root>/<source>/abc.mdx`, when translating `./assets/<source>/xyz.jpg`, it will copy `<root>/<source>/assets/<source>/xyz.jpg` to `<root>/<target>/assets/<target>/xyz.jpg` and modify the reference path in the document to `./assets/<target>/xyz.jpg`.
187-
- When not enabled:
188-
1. When translating `/<source>/abc.jpg`, if `<root>/public/<target>/abc.jpg` exists, the reference path in the document will be changed to `/<target>/abc.jpg`; otherwise, the image reference path remains unchanged.
189-
2. In `<root>/<source>/abc.mdx`, when translating `./assets/<source>/xyz.jpg`, if `<root>/<target>/assets/<target>/xyz.jpg` exists, the reference path will be changed to `./assets/<target>/xyz.jpg`; otherwise, it will be changed to `../<source>/assets/<target>/xyz.jpg`.
179+
- The `-g, --glob` parameter is required. You can specify the file directories or paths to translate. It supports `glob` syntax. Note that the parameter value must be enclosed in quotes, otherwise it will be parsed by the command line and may cause unexpected behavior. Examples:
180+
1. `yarn translate -g abc xyz` will translate all documentation under the `<root>/<source>/abc` and `<root>/<source>/xyz`
181+
directories to `<root>/<target>/abc` and `<root>/<target>/xyz`
182+
2. `yarn translate -g '*'` will translate all documentation files under `<root>/<source>`
183+
- The `-C, --copy` parameter is optional. It controls whether local asset files are copied to the target directory when the target file does not exist. The default is `false`, which means the reference path of the asset file is changed to point to the source path. Examples:
184+
- When this parameter is enabled:
185+
1. Translating `/<source>/abc.jpg` will copy `<root>/public/<source>/abc.jpg` to `<root>/public/<target>/abc.jpg`, and update the reference path in the document to `/<target>/abc.jpg`
186+
2. Translating `./assets/xyz.jpg` in `<root>/<source>/abc.mdx` will copy `<root>/<source>/assets/xyz.jpg` to `<root>/<target>/assets/xyz.jpg`, and the image reference path remains unchanged
187+
3. Translating `./assets/<source>/xyz.jpg` in `<root>/<source>/abc.mdx` will copy `<root>/<source>/assets/<source>/xyz.jpg` to `<root>/<target>/assets/<target>/xyz.jpg`, and update the reference path in the document to `./assets/<target>/xyz.jpg`
188+
- When this parameter is not enabled:
189+
1. When translating `/<source>/abc.jpg`, if `<root>/public/<target>/abc.jpg` already exists, the reference path in the document will be changed to `/<target>/abc.jpg`; otherwise, the image reference path remains unchanged
190+
2. When translating `./assets/<source>/xyz.jpg` in `<root>/<source>/abc.mdx`, if `<root>/<target>/assets/<target>/xyz.jpg` already exists, the reference path in the document will be changed to `./assets/<target>/xyz.jpg`; otherwise, it will be changed to `../<source>/assets/<target>/xyz.jpg`
190191

191192
:::warning
192-
Specially, if you use `-g '*'` for full translation, the file lists of `source` and `target` directories will be compared, and unmatched `target` files except for `internalRoutes` will be automatically deleted.
193+
In particular, if you use `-g '*'` for a full translation, the file lists in the `source` and `target` directories will be compared. Any mismatched `target` files except for `internalRoutes` will be deleted automatically.
193194
:::
194195

195196
:::tip
196-
The translation feature requires configuring the `AZURE_OPENAI_API_KEY` environment variable locally. Please contact your team leader to obtain it.
197+
The translation feature requires the `ALAUDA_OPENAI_BASE_URL` and `ALAUDA_OPENAI_API_KEY` environment variables to be configured locally. Please contact your team Leader to obtain them.
197198
:::
198199

199-
You can control translation behavior in the document metadata:
200+
You can use metadata in the documentation to control translation behavior:
200201

201202
```yaml
202203
i18n:
203204
title:
204205
en: DevOps Connectors
205-
additionalPrompts: 'The term Connectors in this document is a proper noun and should not be translated'
206+
additionalPrompts: '此文中的 Connectors 是专有名词,不要翻译'
206207
disableAutoTranslation: false
207-
title: DevOps Connectors
208+
title: DevOps 连接器
208209
```
209210
210-
For more configuration, please refer to [Translation Configuration](./usage/configuration#translate)
211+
For more configuration, see [Translation Configuration](./usage/configuration#translate)
211212
212-
### Exporting PDF \{#export}
213+
### Export PDF \{#export}
213214
214215
:::warning
215-
Please run the `yarn build` command before exporting.
216+
Please run `yarn build` before performing the export operation.
216217
:::
217218

218219
```sh
@@ -232,15 +233,15 @@ Options:
232233
-h, --help display help for command
233234
```
234235

235-
Run `yarn export` to export the documentation as PDF files. Note that if you used `-b` or `-p` parameters during build, you need to use the same `-b` and `-p` parameters during export.
236+
Run `yarn export` to export the documentation as a PDF file. Note that if you built with the `-b`, `-p` parameters, you also need to use the `-b`, `-p` parameters when exporting.
236237

237-
The export feature depends on [`playwright`](https://playwright.dev). For CI pipelines, please use `build-harbor.alauda.cn/frontend/playwright-runner:doom` as the base image for dependency installation and documentation build. Locally, you can set the following environment variable to speed up downloads:
238+
The export feature depends on [`playwright`](https://playwright.dev). In pipelines, use `build-harbor.alauda.cn/frontend/playwright-runner:doom` as the base image for dependency installation and documentation builds. For local development, you can set the following environment variable to speed up downloads:
238239

239240
```dotenv title=".env.yarn"
240241
PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"
241242
```
242243

243-
Besides exporting a complete PDF for the entire site, `doom` also supports exporting a single PDF file for a specified entry. For more configuration, please refer to [Documentation Export Configuration](./usage/configuration#export)
244+
In addition to exporting a complete PDF document for the entire site, `doom` also supports exporting a single PDF file from a specified entry point. For more configuration, see [Documentation Export Configuration](./usage/configuration#export)
244245

245246
### Documentation Linting \{#lint}
246247

@@ -261,7 +262,7 @@ Options:
261262
-h, --help display help for command
262263
```
263264

264-
`doom lint` is based on [`ESLint`](https://eslint.org/) and [`cspell`](https://cspell.org/). For a better experience in your editor, you can install the corresponding plugins [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) / [CSpell](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker), then create the corresponding configuration files:
265+
`doom lint` is based on [`ESLint`](https://eslint.org/) and [`cspell`](https://cspell.org/). If you want a better experience in your editor, you can install the corresponding plugins [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) / [CSpell](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker), and then create the corresponding configuration files:
265266

266267
- `eslint.config.mjs`:
267268

@@ -277,11 +278,11 @@ Options:
277278
export { default } from '@alauda/doom/cspell'
278279
```
279280
280-
We also agree that the `.cspell` folder under the current working directory (`CWD`) is used to store CSpell dictionary files. For example, you can create `.cspell/k8s.txt`:
281+
At the same time, we agree that the `.cspell` folder under the current working directory (`CWD`) is used to store CSpell dictionary files. For example, you can create `.cspell/k8s.txt`:
281282
282283
```txt
283284
k8s
284285
kubernetes
285286
```
286287
287-
For more configuration, please refer to [Lint Configuration](./usage/configuration#lint)
288+
For more configuration, see [Documentation Linting Configuration](./usage/configuration#lint)

‎docs/zh/start.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ Options:
168168
-s, --source <language> Document source language, one of en, zh, ru (default: "en")
169169
-t, --target <language> Document target language, one of en, zh, ru (default: "zh")
170170
-g, --glob <path...> Glob patterns of source dirs/files to translate
171-
-C, --copy [boolean] Wether to copy relative assets to the target directory instead of following links (default: false)
171+
-C, --copy [boolean] Whether to copy relative assets to the target directory instead of following links (default: false)
172172
-h, --help display help for command
173173
```
174174

@@ -190,7 +190,7 @@ Options:
190190
:::
191191

192192
:::tip
193-
翻译功能须在本地配置 `AZURE_OPENAI_API_KEY` 环境变量,请联系各自团队 Leader 获取
193+
翻译功能须在本地配置 `ALAUDA_OPENAI_BASE_URL` 和 `ALAUDA_OPENAI_API_KEY` 环境变量,请联系各自团队 Leader 获取
194194
:::
195195

196196
文档中可以使用元数据控制翻译行为

‎packages/doom/src/cli/translate.ts‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import { removeLeadingSlash } from '@rspress/shared'
99
import { Command } from 'commander'
1010
import ejs from 'ejs'
1111
import matter from 'gray-matter'
12-
import { AzureOpenAI, RateLimitError } from 'openai'
12+
import { OpenAI, RateLimitError } from 'openai'
1313
import { pRateLimit } from 'p-ratelimit'
1414
import { glob } from 'tinyglobby'
1515
import { cyan, red } from 'yoctocolors'
@@ -114,8 +114,8 @@ The text for translation is provided below, within triple quotes:
114114
<% } %>
115115
`.trim()
116116

117-
let openai: AzureOpenAI | undefined
118-
const openaiModel = process.env.AZURE_OPENAI_MODEL || 'gpt-4.1-mini'
117+
let openai: OpenAI | undefined
118+
const openaiModel = process.env.ALAUDA_OPENAI_MODEL || 'gpt-5.4-mini'
119119

120120
export interface InternalTranslateOptions extends TranslateOptions {
121121
source: Language
@@ -305,12 +305,9 @@ export const translate = async ({
305305
isChunk = false,
306306
}: InternalTranslateOptions) => {
307307
if (!openai) {
308-
openai = new AzureOpenAI({
309-
endpoint:
310-
process.env.AZURE_OPENAI_ENDPOINT ||
311-
'https://azure-ai-api-gateway.alauda.cn',
312-
apiKey: process.env.AZURE_OPENAI_API_KEY,
313-
apiVersion: process.env.OPENAI_API_VERSION || '2025-04-01-preview',
308+
openai = new OpenAI({
309+
baseURL: process.env.ALAUDA_OPENAI_BASE_URL,
310+
apiKey: process.env.ALAUDA_OPENAI_API_KEY,
314311
})
315312
}
316313

@@ -416,7 +413,7 @@ export const translateCommand = new Command('translate')
416413
)
417414
.option(
418415
'-C, --copy [boolean]',
419-
'Wether to copy relative assets to the target directory instead of following links',
416+
'Whether to copy relative assets to the target directory instead of following links',
420417
parseBoolean,
421418
false,
422419
)

0 commit comments

Comments
 (0)