Skip to content

Commit 9f91170

Browse files
piratfpiratf
authored
feat: 实现多语言支持 (i18n) + SEO 优化 + GitHub Pages (#15)
## 概述 为 Windows 文件夹备注工具添加完整的多语言支持 (i18n) 并优化 SEO，支持中文和英文两种语言。同时建设 VitePress 双语文档站点并部署到 GitHub Pages。 ## 主要功能 - 自动语言检测（Windows 使用 GetUserDefaultLocaleName API） - 手动语言切换（--lang 参数） - 完整的中英文翻译 - 打包后的翻译文件正确加载 - SEO 优化：双语 README、关键词优化、GitHub Topics - VitePress 双语文档站点（/en/ 和 /zh/） - GitHub Actions 自动部署到 GitHub Pages ## 更改内容 ### 新增文件 - `locale/zh/LC_MESSAGES/messages.po` - 中文翻译源文件 - `messages.pot` - 翻译模板文件 - `tests/unit/test_i18n.py` - i18n 单元测试（31 个测试用例） - `docs/` - VitePress 双语文档站点 - `.github/workflows/deploy-docs.yml` - GitHub Pages 部署工作流 - `README.en.md` - 英文版 README - `package.json` / `package-lock.json` - VitePress 依赖 ### 修改文件 - `remark/i18n.py` - 新增 i18n 核心模块 - `remark/cli/commands.py` - 添加 --lang 参数和 UTF-8 编码设置 - `README.md` - 主版本（中文为主，含英文摘要） - `pyproject.toml` - 添加 comment 关键词 - `remark.spec` - 添加 locale 数据文件到打包配置 ### SEO 优化 - 双语 H1 标题：remark + comment 双关键词 - GitHub About 描述：英文，含核心关键词 - GitHub Topics：12 个英文标签（GitHub 不支持中文） - README 结构：README.md（中文为主）+ README.en.md（英文） - 文档站点链接：指向 VitePress 双语门户 ### 版本变更 - 2.0.5 → 2.0.6 ## 使用示例 ```bash # 自动检测系统语言 windows-folder-remark.exe # 手动指定中文 windows-folder-remark.exe --lang zh # 手动指定英文 windows-folder-remark.exe --lang en ```
1 parent 7afb90a commit 9f91170

30 files changed

+4768
-125
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Deploy VitePress site to Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
20+
- name: Setup Node.js
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: '20'
24+
cache: 'npm'
25+
cache-dependency-path: package-lock.json
26+
27+
- name: Install dependencies
28+
run: npm ci
29+
30+
- name: Build VitePress site
31+
run: npm run docs:build
32+
33+
- name: Upload artifact
34+
uses: actions/upload-pages-artifact@v3
35+
with:
36+
path: docs/.vitepress/dist
37+
38+
deploy:
39+
environment:
40+
name: github-pages
41+
url: ${{ steps.deployment.outputs.page_url }}
42+
runs-on: ubuntu-latest
43+
needs: build
44+
steps:
45+
- name: Deploy to GitHub Pages
46+
id: deployment
47+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,12 @@ dmypy.json
3333
*.whl
3434
*.tar.gz
3535
/tools/upx/
36+
37+
# i18n - 不再忽略 .mo 文件，需要提交到仓库以便 CI 使用
38+
# .mo 文件由 pybabel compile 生成，从 .po 文件编译而来
39+
40+
# bv (beads viewer) local config and caches
41+
.bv/
42+
43+
# Node.js
44+
node_modules/

‎.pre-commit-config.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,31 @@ repos:
6565
stages: [pre-push]
6666
pass_filenames: false
6767

68+
# i18n 相关检查
69+
- id: extract-translations
70+
name: Extract i18n messages
71+
entry: bash -c 'pybabel extract -k "_" -k "gettext" -k "ngettext" -o messages.pot remark/ && echo "Translations extracted successfully"'
72+
language: system
73+
types: [python]
74+
stages: [pre-commit]
75+
pass_filenames: false
76+
require_serial: true
77+
78+
- id: check-i18n-completeness
79+
name: Check i18n completeness
80+
entry: bash -c 'pybabel update -i messages.pot -d locale --check'
81+
language: system
82+
types: [python]
83+
stages: [pre-commit]
84+
pass_filenames: false
85+
86+
- id: check-po-files
87+
name: Check PO files with polint
88+
entry: bash -c 'if compgen -G "locale/*/LC_MESSAGES/*.po" > /dev/null; then polint locale/*/LC_MESSAGES/*.po || true; fi'
89+
language: system
90+
types: [po]
91+
stages: [pre-commit]
92+
6893
# 全局排除
6994
exclude: |
7095
^(?:

‎README.en.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Windows Folder Remark/Comment Tool
2+
3+
**[English](README.en.md)** | [中文文档](README.md)
4+
5+
[![PyPI](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
6+
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7+
[![en](https://img.shields.io/badge/lang-en-blue.svg)](README.en.md)
8+
[![zh](https://img.shields.io/badge/lang-zh-red.svg)](README.md)
9+
10+
A lightweight CLI tool to add remarks/comments to Windows folders via Desktop.ini. No system residency, no data upload, safe and secure, use it when you need it. Perfect for organizing your files with custom descriptions.
11+
12+
## ⭐ Star Us
13+
14+
If you find this tool helpful, please consider giving it a star on GitHub!
15+
16+
## Why This Tool
17+
18+
- **Use and Go**: Runs when needed, exits when done — no system residency
19+
- **Safe & Secure**: Completely local operation, no data upload, privacy protected
20+
- **Portable**: Single-file exe packaging, no installation required
21+
22+
## Features
23+
24+
- Multi-language character support (UTF-16 encoding)
25+
- Multi-language interface support (English, Chinese)
26+
- Command-line and interactive modes
27+
- Automatic encoding detection and repair
28+
- Automatic update checking to stay current
29+
- Right-click menu integration for quick access
30+
- Single-file exe packaging, no Python environment required
31+
32+
## Installation
33+
34+
### Method 1: Using exe file (Recommended)
35+
36+
Download `windows-folder-remark.exe` from [releases](https://github.com/piratf/windows-folder-remark/releases) and use directly.
37+
38+
### Method 2: Install from source
39+
40+
```bash
41+
# Clone repository
42+
git clone https://github.com/piratf/windows-folder-remark.git
43+
cd windows-folder-remark
44+
45+
# Install dependencies (no external dependencies)
46+
pip install -e .
47+
48+
# Run
49+
python -m remark.cli --help
50+
```
51+
52+
## Usage
53+
54+
### Command-line Mode
55+
56+
```bash
57+
# Add remark
58+
windows-folder-remark.exe "C:\MyFolder" "This is my folder"
59+
60+
# View remark
61+
windows-folder-remark.exe --view "C:\MyFolder"
62+
63+
# Delete remark
64+
windows-folder-remark.exe --delete "C:\MyFolder"
65+
66+
# Check updates
67+
windows-folder-remark.exe --update
68+
69+
# Install right-click menu
70+
windows-folder-remark.exe --install
71+
72+
# Uninstall right-click menu
73+
windows-folder-remark.exe --uninstall
74+
```
75+
76+
### Interactive Mode
77+
78+
```bash
79+
# Follow prompts after running
80+
windows-folder-remark.exe
81+
```
82+
83+
### Right-click Menu (Recommended)
84+
85+
After installing the right-click menu, you can add remarks directly in File Explorer by right-clicking folders:
86+
87+
```bash
88+
# Install right-click menu
89+
windows-folder-remark.exe --install
90+
```
91+
92+
- **Windows 10**: Right-click folder to see "Add Folder Remark"
93+
- **Windows 11**: Right-click folder → Click "Show more options" → Add Folder Remark
94+
95+
### Auto Update
96+
97+
The program automatically checks for updates on exit (once every 24 hours) and prompts if a new version is available.
98+
99+
You can also manually check for updates:
100+
101+
```bash
102+
windows-folder-remark.exe --update
103+
```
104+
105+
## Encoding Detection
106+
107+
When viewing remarks with `--view`, if the `desktop.ini` file is not in standard UTF-16 encoding, the tool will prompt you:
108+
109+
```
110+
Warning: desktop.ini file encoding is utf-8, not standard UTF-16.
111+
This may cause Chinese and other special characters to display abnormally.
112+
Fix encoding to UTF-16? [Y/n]:
113+
```
114+
115+
Select `Y` to automatically fix the encoding.
116+
117+
## Development
118+
119+
```bash
120+
# Install development dependencies
121+
pip install -e ".[dev]"
122+
123+
# Run tests
124+
pytest
125+
126+
# Code check
127+
ruff check .
128+
ruff format .
129+
130+
# Type check
131+
mypy remark/
132+
133+
# Build exe locally
134+
python -m scripts.build
135+
```
136+
137+
## How It Works
138+
139+
This tool implements folder remarks through these steps:
140+
141+
1. Create/modify `Desktop.ini` file in the folder
142+
2. Write `[.ShellClassInfo]` section and `InfoTip` property
143+
3. Save file with UTF-16 encoding
144+
4. Set `Desktop.ini` as hidden and system attributes
145+
5. Set folder as read-only (makes Windows read `Desktop.ini`)
146+
147+
Reference: [Microsoft Official Documentation](https://learn.microsoft.com/en-us/windows/win32/shell/how-to-customize-folders-with-desktop-ini)
148+
149+
## Notes
150+
151+
- May take a few minutes to display in File Explorer after modification
152+
- Some file managers may not support folder remarks
153+
- The tool modifies system attributes of folders
154+
155+
## License
156+
157+
MIT License

readme.md renamed to README.md

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,30 @@
1-
# Windows 文件夹备注工具
1+
# Windows Folder Remark/Comment Tool - Windows 文件夹备注工具
22

3-
一个通过修改 `Desktop.ini` 文件为 Windows 文件夹添加备注/注释的命令行工具。
3+
**[English Documentation](README.en.md)** | [中文文档](README.md)
4+
5+
[![PyPI](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
6+
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7+
[![en](https://img.shields.io/badge/lang-en-blue.svg)](README.en.md)
8+
[![zh](https://img.shields.io/badge/lang-zh-red.svg)](README.md)
9+
10+
A lightweight CLI tool to add remarks/comments to Windows folders via Desktop.ini. No system residency, no data upload, safe and secure, use it when you need it. / 一个轻量级的命令行工具，通过 Desktop.ini 为 Windows 文件夹添加备注/评论。无系统驻留，无数据上传，安全放心，用完即走。
11+
12+
**Documentation**: [Full Documentation](https://piratf.github.io/windows-folder-remark/en/) | [完整文档](https://piratf.github.io/windows-folder-remark/zh/)
13+
14+
## ⭐ 支持
15+
16+
如果这个工具对你有帮助，请在 GitHub 上给个 Star！
17+
18+
## 工具优势
19+
20+
- **用完即走**：需要时运行，用完即退出，无系统驻留
21+
- **安全放心**：完全本地运行，无数据上传，保护隐私
22+
- **轻量便携**：单文件 exe 打包，无需安装，随处可用
423

524
## 特性
625

726
- 支持中文等多语言字符（UTF-16 编码）
27+
- 支持中英文界面切换
828
- 命令行模式和交互模式
929
- 自动编码检测和修复
1030
- 自动更新检查，保持最新版本
@@ -71,8 +91,8 @@ windows-folder-remark.exe
7191
windows-folder-remark.exe --install
7292
```
7393

74-
- **Windows 10**: 右键文件夹可直接看到「添加文件夹备注」
75-
- **Windows 11**: 右键文件夹 → 点击「显示更多选项」→ 添加文件夹备注
94+
- **Windows 10**：右键文件夹可直接看到「添加文件夹备注」
95+
- **Windows 11**：右键文件夹 → 点击「显示更多选项」→ 添加文件夹备注
7696

7797
### 自动更新
7898

‎babel.cfg‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Babel extraction configuration
2+
# https://babel.pocoo.org/en/latest/messages.html
3+
4+
# Extract translatable strings from Python files
5+
[python: remark/**/*.py]
6+
7+
# Keyword list - recognize strings in these function calls as translatable
8+
keywords = _, gettext, ngettext
9+
10+
# Encoding
11+
encoding = utf-8

‎docs/.vitepress/config.mjs‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'Windows Folder Remark Tool',
5+
description: 'A lightweight CLI tool to add remarks/comments to Windows folders via Desktop.ini',
6+
base: '/windows-folder-remark/',
7+
lang: 'en-US',
8+
9+
locales: {
10+
root: {
11+
label: 'English',
12+
lang: 'en-US'
13+
},
14+
zh: {
15+
label: '简体中文',
16+
lang: 'zh-CN',
17+
link: '/zh/'
18+
}
19+
},
20+
21+
themeConfig: {
22+
nav: () => [
23+
{ text: 'Guide', link: '/en/guide/' },
24+
{ text: '中文', link: '/zh/' }
25+
],
26+
27+
sidebar: {
28+
'/en/': [
29+
{
30+
text: 'Guide',
31+
items: [
32+
{ text: 'Introduction', link: '/en/' },
33+
{ text: 'Getting Started', link: '/en/guide/getting-started' },
34+
{ text: 'Usage', link: '/en/guide/usage' },
35+
{ text: 'API Reference', link: '/en/guide/api' }
36+
]
37+
}
38+
],
39+
'/zh/': [
40+
{
41+
text: '指南',
42+
items: [
43+
{ text: '介绍', link: '/zh/' },
44+
{ text: '快速开始', link: '/zh/guide/getting-started' },
45+
{ text: '使用方法', link: '/zh/guide/usage' },
46+
{ text: 'API 参考', link: '/zh/guide/api' }
47+
]
48+
}
49+
]
50+
}
51+
}
52+
})

‎docs/en/guide/api.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# API Reference
2+
3+
## Command-line Arguments
4+
5+
| Argument | Short | Description |
6+
|---|---|---|
7+
| `--help` | `-h` | Show help information |
8+
| `--install` | | Install right-click menu |
9+
| `--uninstall` | | Uninstall right-click menu |
10+
| `--update` | | Check for updates |
11+
| `--view <path>` | | View folder remark |
12+
| `--delete <path>` | | Delete folder remark |
13+
| `--gui <path>` | | GUI mode |
14+
| `--lang <lang>` | `-L` | Set language (en, zh) |
15+
16+
## Exit Codes
17+
18+
| Code | Description |
19+
|---|---|
20+
| 0 | Success |
21+
| 1 | Error |

0 commit comments

Comments
 (0)