Aspell 拼写检查完全教程 / 第4章词典管理

第 4 章：词典管理

词典是拼写检查的核心。本章详解 Aspell 的词典体系——主词典、个人词典、额外词典的管理方法，以及词典格式规范和常见运维操作。

4.1 Aspell 词典体系总览

┌──────────────────────────────────────────────────────┐
│                  Aspell 词典层次                       │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │  主词典     │  │  个人词典   │  │  额外词典   │     │
│  │ (Master)   │  │ (Personal) │  │ (Extra)    │     │
│  │            │  │            │  │            │     │
│  │ en_US-aspell│ │ ~/.aspell. │  │ tech.pws   │     │
│  │ en_GB-aspell│ │ en_US.pws  │  │ names.pws  │     │
│  │ de-aspell  │  │            │  │            │     │
│  └────────────┘  └────────────┘  └────────────┘     │
│       │                │               │             │
│       └────────┬───────┘────────┬──────┘             │
│                │                │                     │
│         ┌──────▼────────────────▼──────┐              │
│         │      词典查找顺序             │              │
│         │  Personal → Extra → Master   │              │
│         └──────────────────────────────┘              │
│                                                      │
└──────────────────────────────────────────────────────┘

词典类型说明

类型	说明	文件格式	位置
主词典 (Master)	语言官方词典，随词典包安装	`.aspell`（压缩）	`/usr/lib/aspell-0.60/`
个人词典 (Personal)	用户自定义补充词表	`.pws` (plain word list)	`~/.aspell.<lang>.pws`
额外词典 (Extra)	项目/领域专用词表	`.pws`	任意路径

查找优先级

输入单词 → 个人词典 → 额外词典 → 主词典 → 未找到（拼写错误）

如果单词在任何一层词典中被找到，则认为拼写正确。

4.2 个人词典（Personal Dictionary）

个人词典是 Aspell 最灵活的词典管理机制，用于存储用户名、专业术语、缩写等主词典中没有的词汇。

4.2.1 默认路径

# 查看个人词典默认路径
aspell config personal
# 输出: ~/.aspell.en_US.pws

# 不同语言对应不同个人词典
# en_US → ~/.aspell.en_US.pws
# de    → ~/.aspell.de.pws

4.2.2 自动添加（交互模式）

在交互模式中，按 4（Add）或 5（Add lowercase）将单词加入个人词典：

aspell check document.txt
# 当遇到 "Aspell" 时按 5 → 会将 "aspell" 加入个人词典
# 当遇到 "GitHub" 时按 4 → 会将 "GitHub" 加入个人词典（保留大小写）

4.2.3 手动编辑

个人词典是纯文本文件，可以直接编辑：

# 查看个人词典内容
cat ~/.aspell.en_US.pws

# 典型内容:
# personal_ws-1.1 en 3
# Aspell
# GitHub
# Markdown

格式说明：

personal_ws-1.1 en <count>
word1
word2
word3

第一行：文件头，包含版本号、语言代码、单词数量
后续行：每行一个单词

4.2.4 手动创建个人词典

# 创建个人词典文件
cat > ~/.aspell.en_US.pws << 'EOF'
personal_ws-1.1 en 5
API
Aspell
Docker
GitHub
Kubernetes
EOF

# 验证
echo "Aspell" | aspell -a --personal=~/.aspell.en_US.pws
# 应该输出 * （拼写正确）

4.2.5 指定自定义路径

# 使用自定义路径的个人词典
aspell check --personal=./project-dict.pws document.txt

# 管道模式
echo "Aspell" | aspell -a --personal=./project-dict.pws

4.2.6 个人词典合并

#!/bin/bash
# merge_dicts.sh — 合并多个个人词典

DICTS=("~/.aspell.en_US.pws" "./project.pws" "./team.pws")
OUTPUT="./merged.pws"

# 收集所有单词（跳过文件头）
WORDS=()
for dict in "${DICTS[@]}"; do
    expanded=$(eval echo "$dict")
    if [ -f "$expanded" ]; then
        tail -n +2 "$expanded" >> /tmp/all_words.txt
    fi
done

# 去重并生成新词典
SORTED=$(sort -u /tmp/all_words.txt)
COUNT=$(echo "$SORTED" | wc -l)

{
    echo "personal_ws-1.1 en $COUNT"
    echo "$SORTED"
} > "$OUTPUT"

rm /tmp/all_words.txt
echo "合并完成: $OUTPUT ($COUNT 个单词)"

4.3 主词典（Master Dictionary）

主词典由语言包安装时提供，包含该语言的完整词表和 affix 规则。

4.3.1 查看主词典信息

# 查看当前语言的主词典路径
aspell config master

# 查看主词典数据目录
aspell config dict-dir

# 列出主词典中的单词数（会很多，用 head 查看前几个）
aspell -d en_US dump master | head -20

# 统计主词典单词数
aspell -d en_US dump master | wc -l

4.3.2 dump 命令族

# 列出所有已安装的词典
aspell dump dicts

# 列出词典配置
aspell dump config

# 列出某个词典的详细配置
aspell -d de dump config

# 列出主词典内容
aspell -d en_US dump master

# 列出个人词典内容
aspell -d en_US dump personal

# 列出所有词典（主 + 个人）
aspell -d en_US dump all

4.3.3 词典别名

# 查看语言别名映射
cat /usr/lib/aspell-0.60/en.alias
# 典型内容:
# en.multi
# en_US.multi

# 查看 multi 文件内容
cat /usr/lib/aspell-0.60/en.multi
# 典型内容:
# add en_US-aspell
# add en_GB-aspell

4.4 额外词典（Extra Dictionaries）

额外词典用于项目或团队级别的补充词表，不修改个人词典或主词典。

4.4.1 创建额外词典

# 创建项目专用词典
cat > ./project-dict.pws << 'EOF'
personal_ws-1.1 en 8
API
Backend
Dockerfile
Frontend
Kubernetes
Microservice
OAuth
WebSocket
EOF

4.4.2 使用额外词典

# 单个额外词典
aspell check --extra-dicts=./project-dict.pws document.txt

# 多个额外词典
aspell check \
    --extra-dicts=./project-dict.pws \
    --extra-dicts=./names.pws \
    document.txt

# 管道模式
echo "Dockerfile" | aspell -a --extra-dicts=./project-dict.pws

4.4.3 团队共享词典

# 将词典放入版本控制
git add project-dict.pws
git commit -m "chore: add project spelling dictionary"

# 团队成员使用
aspell check --extra-dicts=./project-dict.pws README.md

4.4.4 词典文件组织建议

project-root/
├── .aspell/
│   ├── project.pws      # 项目通用词典
│   ├── tech.pws         # 技术术语词典
│   └── names.pws        # 人名/组织名词典
├── docs/
│   └── ...
└── .github/
    └── workflows/
        └── spellcheck.yml

4.5 词典文件格式详解

4.5.1 `.pws` 格式（Personal Word List）

personal_ws-1.1 <lang> <count>
word1
word2
word3

字段	说明
`personal_ws-1.1`	固定文件头标识（版本 1.1）
`<lang>`	语言代码（如 `en`、`de`、`fr`）
`<count>`	单词数量（Aspell 会自动更新）

规则：

每行一个单词
支持 UTF-8 编码
大小写敏感：API 和 api 是两个不同条目
以 # 开头的行为注释（非官方支持，部分版本可用）

4.5.2 `.prepl` 格式（Replacement Pairs）

.prepl 文件定义"替换对"——当用户输入某个词时，自动建议替换为另一个词。

personal_repl-1.1 <lang> <count>
<misspelled> -> <correct>

示例：

# 创建替换对文件
cat > ~/.aspell.en_US.prepl << 'EOF'
personal_repl-1.1 en 3
teh -> the
recieve -> receive
occured -> occurred
EOF

使用效果：

echo "teh" | aspell -a
# & teh 3 0: the, tea, tee   （"the" 排在第一位，因为有替换对）

4.5.3 词典与替换对的区别

特性	`.pws` 个人词典	`.prepl` 替换对
作用	让单词被视为"正确"	让错误单词有优先建议
格式	每行一个单词	`错误 → 正确` 对
使用场景	添加专有名词、术语	纠正常见拼写错误
路径	`~/.aspell.<lang>.pws`	`~/.aspell.<lang>.prepl`

4.6 词典维护实践

4.6.1 从文档中提取候选词

#!/bin/bash
# extract_candidates.sh — 从文档中提取可能需要加入词典的单词

FILE="$1"
if [ -z "$FILE" ]; then
    echo "用法: $0 <file>"
    exit 1
fi

# 提取拼写错误的单词
ERRORS=$(aspell list < "$FILE" | sort -u)

if [ -z "$ERRORS" ]; then
    echo "没有拼写错误"
    exit 0
fi

echo "以下单词不在词典中："
echo "$ERRORS"
echo ""
echo "建议操作："
echo "  1. 确认是正确的专有名词/术语 → 加入个人词典"
echo "  2. 确认是拼写错误 → 修正文档"
echo ""
echo "将这些单词加入词典？(y/N)"
read -r confirm
if [ "$confirm" = "y" ] || [ "$confirm" = "Y" ]; then
    DICT_FILE="${2:-~/.aspell.en_US.pws}"
    # 确保文件头存在
    if [ ! -f "$DICT_FILE" ]; then
        echo "personal_ws-1.1 en 0" > "$DICT_FILE"
    fi
    echo "$ERRORS" >> "$DICT_FILE"
    # 更新计数
    COUNT=$(tail -n +2 "$DICT_FILE" | wc -l)
    sed -i "s/personal_ws-1.1 en [0-9]*/personal_ws-1.1 en $COUNT/" "$DICT_FILE"
    echo "已加入 $DICT_FILE"
fi

4.6.2 清理个人词典中的错误条目

#!/bin/bash
# clean_dict.sh — 检查个人词典中的"可疑"条目

DICT="$1"
if [ -z "$DICT" ]; then
    DICT="$HOME/.aspell.en_US.pws"
fi

echo "检查词典: $DICT"
echo "=========="

# 检查重复条目
DUPES=$(tail -n +2 "$DICT" | sort | uniq -d)
if [ -n "$DUPES" ]; then
    echo "重复条目:"
    echo "$DUPES" | sed 's/^/  /'
fi

# 检查空行
BLANKS=$(grep -c '^$' "$DICT")
if [ "$BLANKS" -gt 0 ]; then
    echo "空行数: $BLANKS"
fi

# 检查大小写冲突（如同时有 API 和 api）
WORDS=$(tail -n +2 "$DICT" | tr '[:upper:]' '[:lower:]' | sort)
CONFLICTS=$(echo "$WORDS" | uniq -d)
if [ -n "$CONFLICTS" ]; then
    echo "可能的大小写冲突:"
    for word in $CONFLICTS; do
        grep -i "^${word}$" "$DICT" | sed 's/^/  /'
    done
fi

echo ""
echo "词典统计:"
echo "  总行数: $(wc -l < "$DICT")"
echo "  单词数: $(tail -n +2 "$DICT" | grep -c '.')"

4.6.3 备份与恢复

# 备份个人词典
cp ~/.aspell.en_US.pws ~/.aspell.en_US.pws.bak

# 恢复个人词典
cp ~/.aspell.en_US.pws.bak ~/.aspell.en_US.pws

# 自动备份脚本
#!/bin/bash
BACKUP_DIR="$HOME/.aspell-backups"
mkdir -p "$BACKUP_DIR"
DATE=$(date +%Y%m%d_%H%M%S)
for dict in ~/.aspell.*.pws; do
    if [ -f "$dict" ]; then
        BASENAME=$(basename "$dict")
        cp "$dict" "$BACKUP_DIR/${BASENAME}.${DATE}"
    fi
done
echo "词典已备份到 $BACKUP_DIR"

4.7 词典优先级与冲突处理

4.7.1 查找顺序

# 当同一个单词出现在多个词典中时：
# 个人词典 > 额外词典 > 主词典

# 验证查找顺序
echo "Aspell" | aspell -a --personal=test.pws --extra-dicts=extra.pws

4.7.2 大小写处理

规则：
- 如果单词在词典中以大写开头（如 API），只有精确匹配才通过
- 如果单词在词典中以小写开头（如 api），大小写变体也通过
- 如果个人词典中有 "api"，则 "api"、"Api"、"API" 都通过
- 如果个人词典中有 "API"，只有 "API" 通过，"api" 不通过

# 演示大小写规则
cat > test.pws << 'EOF'
personal_ws-1.1 en 2
api
EOF

echo "api" | aspell -a --personal=test.pws  # * (通过)
echo "Api" | aspell -a --personal=test.pws  # * (通过)
echo "API" | aspell -a --personal=test.pws  # * (通过)

cat > test.pws << 'EOF'
personal_ws-1.1 en 2
API
EOF

echo "api" | aspell -a --personal=test.pws  # & (不通过!)
echo "Api" | aspell -a --personal=test.pws  # & (不通过!)
echo "API" | aspell -a --personal=test.pws  # * (通过)

4.7.3 最佳实践

建议：对于缩写词（如 API、HTTP、JSON），使用小写形式加入词典（api、http、json），这样大小写变体都能通过。

4.8 业务场景

场景 1：技术文档项目词典

# .aspell/project.pws — 项目专用词典
personal_ws-1.1 en 15
api
backend
cache
containerization
devops
dockerfile
frontend
json
kubernetes
microservice
oauth
proxy
restful
websocket
yaml

场景 2：学术论文词典

# 创建学术论文专用词典
cat > academic.pws << 'EOF'
personal_ws-1.1 en 10
heteroscedasticity
multicollinearity
homoscedasticity
pseudocode
preprocessing
subgradient
backpropagation
hyperparameter
regularization
crossvalidation
EOF

场景 3：多语言项目

# 为不同语言维护不同词典
aspell check --lang=en --personal=~/.aspell.en.pws docs/en/
aspell check --lang=de --personal=~/.aspell.de.pws docs/de/
aspell check --lang=fr --personal=~/.aspell.fr.pws docs/fr/

4.9 本章小结

要点	说明
主词典	语言包提供，包含完整词表和 affix 规则
个人词典	`~/.aspell.<lang>.pws`，用户自定义补充词表
额外词典	项目/团队级别词表，通过 `--extra-dicts` 使用
替换对	`.prepl` 文件，定义错误→正确的优先建议
大小写规则	小写词典条目匹配所有大小写变体，大写只匹配精确形式
查找顺序	个人词典 → 额外词典 → 主词典

下一步

→ 第 5 章：过滤模式 — 学习 Aspell 如何智能处理 TeX、HTML、Email 等格式文档。

Aspell 拼写检查完全教程 / 第4章 词典管理