Skip to content

Commit a667bbb

Browse files
ryosukeeeeeeryosukeeeeee
committed
feat: automate English documentation translation
1 parent e590e19 commit a667bbb

14 files changed

Lines changed: 1438 additions & 8 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ on:
66
workflow_dispatch:
77

88
permissions:
9-
contents: read
9+
contents: write
1010
pages: write
1111
id-token: write
1212

@@ -26,6 +26,8 @@ jobs:
2626
steps:
2727
- name: Check out repository
2828
uses: actions/checkout@v6
29+
with:
30+
fetch-depth: 0
2931

3032
- name: Set up Node.js
3133
uses: actions/setup-node@v6
@@ -36,6 +38,17 @@ jobs:
3638
- name: Install dependencies
3739
run: corepack yarn install --frozen-lockfile
3840

41+
- name: Synchronize English documentation
42+
env:
43+
AZURE_TRANSLATOR_KEY: ${{ secrets.AZURE_TRANSLATOR_KEY }}
44+
AZURE_TRANSLATOR_REGION: ${{ vars.AZURE_TRANSLATOR_REGION }}
45+
run: |
46+
if [ -z "$AZURE_TRANSLATOR_KEY" ]; then
47+
echo "::warning::AZURE_TRANSLATOR_KEY is not configured; using the checked-in English pages."
48+
exit 0
49+
fi
50+
corepack yarn translate
51+
3952
- name: Build site
4053
run: corepack yarn build
4154

@@ -50,3 +63,17 @@ jobs:
5063
- name: Deploy to GitHub Pages
5164
id: deployment
5265
uses: actions/deploy-pages@v4
66+
67+
- name: Save generated English documentation
68+
run: |
69+
git add -- docs/uk
70+
if [ -f .i18n-cache/azure-en.json ]; then
71+
git add -- .i18n-cache/azure-en.json
72+
fi
73+
if git diff --cached --quiet; then
74+
exit 0
75+
fi
76+
git config user.name "github-actions[bot]"
77+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
78+
git commit -m "chore(i18n): sync generated English documentation"
79+
git push

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
node_modules/
22
dist/
33
*.log
4+
.env
5+
.env.*
6+
!.env.example

‎TRANSLATING.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# 英文文档自动翻译
2+
3+
中文 `docs` 目录是本站内容的唯一来源。`docs/uk` 中的英文 Markdown 由构建流程生成，请不要直接编辑。
4+
5+
## 首次启用
6+
7+
1. 在 Azure 中创建单服务 **Translator** 资源，区域选择 **Global**，定价层选择 **Free F0**。
8+
2. 在资源的 **Keys and Endpoint** 页面复制其中一个密钥。
9+
3. 打开 GitHub 仓库的 **Settings → Secrets and variables → Actions**。
10+
4. 新建名为 `AZURE_TRANSLATOR_KEY` 的 Repository secret，并填入 Azure Translator 密钥。
11+
5. 如果资源不是 Global 区域，再创建名为 `AZURE_TRANSLATOR_REGION` 的 Repository variable，值为资源区域代码。
12+
6. 在 GitHub Actions 中手动运行一次 **Deploy documentation**，或推送一次中文文档修改。
13+
14+
密钥只提供给 GitHub Actions，不会写入仓库、生成文件或浏览器代码。
15+
16+
## 同步规则
17+
18+
- 新增中文 Markdown：创建同路径英文页面。
19+
- 修改中文 Markdown：只请求翻译没有命中段落缓存的内容。
20+
- 删除中文 Markdown：删除同路径英文页面。
21+
- 移动或重命名：表现为删除旧英文页面并创建新页面。
22+
- 代码块、行内代码、链接目标、图片地址和 HTML 注释保持原样。
23+
- 根路径文档链接自动增加 `/uk` 前缀。
24+
- `i18n.config.json` 中的 Arch Linux 术语保持原文。
25+
- API 请求失败时不写入部分翻译，也不会部署不完整版本。
26+
27+
本地拥有 Azure Translator 密钥时，可以设置 `AZURE_TRANSLATOR_KEY` 环境变量后运行 `yarn translate`。区域资源还需设置 `AZURE_TRANSLATOR_REGION`；Global 资源可以省略。日常只需维护中文文档，英文生成文件和 `.i18n-cache` 缓存由 GitHub Actions 提交。

‎docs/index.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@
7070
})();
7171
</script>
7272
<link rel="stylesheet" href="./vendor/gitalk.css" />
73-
<link rel="stylesheet" href="./styles/theme.css?v=20260716-7" />
73+
<link rel="stylesheet" href="./styles/theme.css?v=20260716-8" />
7474
</head>
7575
<body>
7676
<a class="skip-link" href="#main">跳到正文</a>
@@ -122,7 +122,7 @@
122122
</noscript>
123123

124124
<script src="./vendor/gitalk.min.js"></script>
125-
<script src="./scripts/site.js?v=20260716-8"></script>
125+
<script src="./scripts/site.js?v=20260716-9"></script>
126126
<script src="./vendor/docsify.min.js"></script>
127127
<script src="./vendor/prism-bash.min.js"></script>
128128
<script src="./vendor/search.min.js"></script>

‎docs/scripts/site.js‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,8 @@
4949
}
5050

5151
function editUrl(file) {
52-
return `${REPOSITORY}/edit/master/docs/${encodedFilePath(file)}`;
52+
const sourceFile = normalizeFile(file).replace(/^uk\//, "");
53+
return `${REPOSITORY}/edit/master/docs/${encodedFilePath(sourceFile)}`;
5354
}
5455

5556
function articleChrome() {
@@ -62,6 +63,16 @@
6263
const discussionText = english
6364
? "Sign in with GitHub to join the discussion for this page."
6465
: "使用 GitHub 登录，参与当前页面的讨论。";
66+
const chineseRoute = currentRoute().replace(/^\/uk(?=\/|$)/, "") || "/";
67+
const translationNotice = english
68+
? `
69+
<aside class="translation-notice" aria-label="Translation notice">
70+
<strong>Machine-translated from Chinese.</strong>
71+
<span>The Chinese page is authoritative.</span>
72+
<a href="#${chineseRoute}">Read the source</a>
73+
</aside>
74+
`
75+
: "";
6576

6677
return {
6778
before: `
@@ -70,6 +81,7 @@
7081
<span class="article-meta__separator" aria-hidden="true"></span>
7182
<span class="article-meta__item article-updated" data-file="${normalizeFile(activeFile)}">${updateLabel}</span>
7283
</div>
84+
${translationNotice}
7385
`,
7486
after: `
7587
<footer class="article-footer">

‎docs/styles/theme.css‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1203,6 +1203,31 @@ main:has(> .sidebar.show) > .content {
12031203
background: var(--line-strong);
12041204
}
12051205

1206+
.translation-notice {
1207+
display: flex;
1208+
flex-wrap: wrap;
1209+
align-items: baseline;
1210+
gap: 5px 9px;
1211+
margin: 0 0 28px;
1212+
padding: 11px 14px;
1213+
border: 1px solid color-mix(in srgb, var(--arch-blue) 30%, var(--line));
1214+
border-radius: var(--radius-sm);
1215+
color: var(--ink-secondary);
1216+
background: var(--arch-blue-soft);
1217+
font-size: 13px;
1218+
line-height: 1.55;
1219+
}
1220+
1221+
.translation-notice strong {
1222+
color: var(--ink);
1223+
}
1224+
1225+
.translation-notice a {
1226+
margin-left: auto;
1227+
font-weight: 700;
1228+
white-space: nowrap;
1229+
}
1230+
12061231
.article-footer {
12071232
display: flex;
12081233
align-items: center;

‎docs/uk/_404.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
<!-- AUTO-GENERATED: edit the corresponding Chinese document instead. -->
2+
3+
# 404

‎i18n.config.json‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
{
2+
"sourceDirectory": "docs",
3+
"outputDirectory": "docs/uk",
4+
"cacheFile": ".i18n-cache/azure-en.json",
5+
"sourceLanguage": "zh-Hans",
6+
"targetLanguage": "en",
7+
"apiUrl": "https://api.cognitive.microsofttranslator.com/translate",
8+
"excludeFiles": ["_navbar.md"],
9+
"protectedTerms": [
10+
"Arch Linux",
11+
"ArchLinux",
12+
"ArchTutorial",
13+
"ArchLinuxStudio",
14+
"AUR",
15+
"BIOS",
16+
"Docsify",
17+
"GitHub",
18+
"Gitalk",
19+
"GNOME",
20+
"GRUB",
21+
"initramfs",
22+
"KDE Plasma",
23+
"Linux",
24+
"mkinitcpio",
25+
"NetworkManager",
26+
"pacman",
27+
"PipeWire",
28+
"PulseAudio",
29+
"Qv2ray",
30+
"root",
31+
"sudo",
32+
"systemd",
33+
"UEFI",
34+
"V2rayA",
35+
"v2ray",
36+
"Wayland",
37+
"Xorg",
38+
"Azure Translator",
39+
"Azure",
40+
"yay"
41+
]
42+
}

‎package.json‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@
1616
"dev": "node scripts/sync-vendor.mjs && node node_modules/serve/build/main.js docs -l 3000 --no-clipboard",
1717
"start": "node scripts/sync-vendor.mjs && node node_modules/serve/build/main.js docs -l 3000 --no-clipboard",
1818
"sync:vendor": "node scripts/sync-vendor.mjs",
19-
"check": "node scripts/validate-site.mjs",
19+
"translate": "node scripts/translate-docs.mjs",
20+
"test:i18n": "node scripts/test-i18n.mjs",
21+
"check": "node scripts/validate-site.mjs && node scripts/test-i18n.mjs",
2022
"build": "node scripts/sync-vendor.mjs && node scripts/build.mjs"
2123
},
2224
"dependencies": {
@@ -25,6 +27,9 @@
2527
"prismjs": "1.30.0"
2628
},
2729
"devDependencies": {
28-
"serve": "14.2.6"
30+
"remark-gfm": "4.0.1",
31+
"remark-parse": "11.0.0",
32+
"serve": "14.2.6",
33+
"unified": "11.0.5"
2934
}
3035
}

0 commit comments

Comments
 (0)