Cara Membangun Pemeriksa Tata Bahasa Offline Harper Tanpa Kebocoran Eksternal
TuBrief 편집팀
2026년 7월 25일
0
Computing/Software원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
Ketika kebijakan keamanan perusahaan memblokir alat AI eksternal seperti Grammarly, para pengembang sering kali merasa kesulitan. Membiarkan tipografi pada dokumen teknis atau komentar kode sebelum melakukan prapublikasi dapat menurunkan kredibilitas, tetapi memeriksa semuanya secara manual satu per satu sangat menyita waktu.
Harper menyelesaikan masalah ini dengan rapi. Karena merupakan mesin pemeriksa tata bahasa khusus offline yang dikembangkan dengan Rust, alat ini memblokir komunikasi dengan server eksternal secara total. Berbeda dengan LanguageTool yang berbasis Java dan mengonsumsi memori hingga ratusan megabita, penggunaan memori Harper hanya sebatas belasan megabita. Dengan kecepatan respons di bawah 10ms, editor Anda tidak akan menjadi lambat.
harper-ls melakukan analisis sintaksis hanya dengan menggunakan sumber daya CPU lokal di dalam terminal. Anda cukup menginstal biner melalui manajer paket yang sesuai dengan sistem operasi Anda dan mendaftarkannya sebagai LSP standar pada editor.
Jalankan perintah di terminal untuk menginstal biner.
brew install harpercargo install harper-ls --lockedscoop install harperDi Neovim, gunakan nvim-lspconfig untuk mengatur tipe berkas sasaran dan aturan linter.
`lua
local lspconfig = require('lspconfig')
lspconfig.harper_ls.setup({
filetypes = { 'markdown', 'gitcommit', 'rust', 'go', 'typescript', 'python' },
settings = {
["harper-ls"] = {
userDictPath = "~/config/harper/user_dict.txt",
workspaceDictPath = ".harper-dictionary.txt",
linters = {
SpellCheck = true,
SpelledNumbers = false,
AnA = true,
SentenceCapitalization = false,
UnclosedQuotes = true,
WrongApostrophe = false,
LongSentences = true,
RepeatedWords = true,
Spaces = true,
CorrectNumberSuffix = true
}
}
}
})
`
Saat menggunakan API LSP asli pada Neovim 0.11 atau yang lebih baru, konfigurasikan vim.lsp.config['harper'] dan panggil vim.lsp.enable('harper'). Untuk pengguna VS Code, cukup instal ekstensi elijah-potter.harper lalu tentukan jalur "harper.path": "/usr/local/bin/harper-ls" di dalam .vscode/settings.json.
Harper dilengkapi dengan parser Tree-sitter AST internal, sehingga dapat melewati kode sumber sebenarnya dan hanya memilih teks bahasa Inggris di dalam blok komentar untuk diperiksa. Jika Anda ingin mengecualikan komentar fungsi tertentu sepenuhnya dari pemeriksaan, tambahkan direktif sebaris.
`javascript
// harper:ignore
function processInternalSecurityToken() {
// spellcheck:ignore
// Logika token keamanan internal
}
`
Jika Anda hanya menjalankan kamus kata bahasa Inggris standar, istilah teknis seperti gRPC, OAuth2, dan Prometheus akan dianggap sebagai kesalahan. Dengan memanfaatkan struktur kamus berhierarki, Anda dapat menghapus kebisingan peringatan dengan cepat.
Harper memverifikasi kata melalui 4 tingkatan.
| Tingkat Kamus | Lokasi Penyimpanan | Tujuan |
|---|---|---|
| Static Dictionary | Terintegrasi dalam biner harper-ls |
Basis data kata bahasa Inggris dasar yang tidak dapat diubah |
| User Dictionary | ~/.config/harper-ls/dictionary.txt |
Kamus global untuk lingkungan pengembang pribadi |
| Workspace Dictionary | Root proyek .harper-dictionary.txt |
Kamus istilah khusus proyek (Dikelola dengan Git) |
| File-Local Dictionary | Disimpan di dalam jalur data OS | Penyimpanan pengenal khusus untuk berkas tunggal |
.harper-dictionary.txt di direktori root proyek.`text
Kubernetes
gRPC
OAuth2
OpenTelemetry
Prometheus
mTLS
Netty
Etcd
`
Ctrl + ., Neovim: key binding Code Action) untuk langsung menambahkan kata tersebut ke .harper-dictionary.txt.Cukup dengan mengunggah berkas ini ke repositori Git, seluruh anggota tim akan berbagi daftar kata yang sama.
Matikan aturan yang menyulitkan saat menulis komentar.
SentenceCapitalization: Atur ke false untuk mematikan aturan yang mewajibkan huruf kapital pada huruf pertama komentar.LongSentences: Atur ke false untuk mematikan peringatan kalimat panjang yang sering muncul pada dokumen teknis.SpellCheck dan UnclosedQuotes: Biarkan true untuk pemeriksaan kesalahan ejaan dan tanda kutip yang belum ditutup.Tipografi yang terlewat oleh pengembang di editor harus dicegat pada tahap PR. Dengan menghubungkan alat CLI harper-cli ke alur kerja, kesalahan tata bahasa akan disaring secara otomatis sebelum penggabungan (merge) ke cabang utama.
Definisikan pekerjaan untuk memilih dan memeriksa berkas Markdown yang diubah saja pada berkas .github/workflows/harper-lint.yml.
`yaml
name: Technical Documentation Linting
on:
pull_request:
paths:
- 'docs/'
- '.md'
jobs:
harper-grammar-check:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust Toolchain
uses: dtolnay/rust-toolchain@stable
- name: Cache Harper CLI Binary
uses: actions/cache@v3
with:
path: ~/.cargo/bin/harper-cli
key: ${{ runner.os }}-harper-cli-${{ hashFiles('**/Cargo.lock') }}
- name: Install Harper CLI
run: |
if ! command -v harper-cli &> /dev/null; then
cargo install harper-cli --locked
fi
- name: Get Changed Markdown Files
id: changed-files
run: |
git fetch origin ${{ github.base_ref }}
FILES=$(git diff --name-only --diff-filter=AM origin/${{ github.base_ref }} HEAD | grep '\.md$' || true)
echo "files=$FILES" >> $GITHUB_OUTPUT
- name: Run Harper Lint Check
if: steps.changed-files.outputs.files != ''
run: |
ERRORS=0
for file in ${{ steps.changed-files.outputs.files }}; do
echo "Linting $file with Harper..."
harper-cli lint "$file" || ERRORS=$((ERRORS+1))
done
if [ $ERRORS -gt 0 ]; then
echo "Harper validation failed with $ERRORS error(s)."
exit 1
fi
`
Jika Anda juga melakukan commit pada .harper-dictionary.txt di root proyek, pemroses CI juga akan menjalankan pemeriksaan berdasarkan daftar kata yang sama seperti di editor. Jika menggunakan pembuat situs statis (SSG) seperti MkDocs atau Docusaurus, lebih aman untuk mengonfigurasi perintah harper-cli lint docs/ agar dieksekusi tepat sebelum skrip pembangun (build) dijalankan.