Como Configurar o Harper: Um Verificador Gramatical Offline Sem Vazamento de Dados

Quando as políticas de segurança corporativas bloqueiam ferramentas externas de IA, como o Grammarly, os desenvolvedores ficam em uma situação complicada. Fazer um deploy mantendo erros de digitação na documentação técnica ou nos comentários do código reduz a credibilidade; por outro lado, revisar tudo manualmente consome um tempo valioso.

O Harper resolve esse problema de forma elegante. Desenvolvido em Rust, ele é um motor de verificação gramatical exclusivamente offline que bloqueia completamente a comunicação com servidores externos. Ao contrário do LanguageTool, que roda em Java e consome centenas de megabytes de memória, o consumo de memória do Harper é de apenas alguns dezenas de megabytes. Com um tempo de resposta inferior a 10ms, ele não causa qualquer lentidão no seu editor.

1. Instalação do Ambiente de Desenvolvimento e Integração LSP com o Editor

O harper-ls executa a análise sintática utilizando apenas os recursos da CPU local da máquina. Basta instalar o binário através do gerenciador de pacotes do seu sistema operacional e registrá-lo como um LSP padrão no seu editor.

Instalação do Pacote

Execute o comando no terminal para instalar o binário.

macOS / Linux: brew install harper
Ambiente Rust: cargo install harper-ls --locked
Windows: scoop install harper

Integração com Neovim e VS Code

No Neovim, configure os tipos de arquivos alvo e as regras do linter usando o nvim-lspconfig.

`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
}
}
}
})
`

Ao usar a API LSP nativa do Neovim 0.11 ou superior, configure vim.lsp.config['harper'] e chame vim.lsp.enable('harper'). Para usuários do VS Code, basta instalar a extensão elijah-potter.harper e definir o caminho "harper.path": "/usr/local/bin/harper-ls" no seu .vscode/settings.json.

Ignorando Código Executável e Controlando o Escopo de Verificação

Como o Harper possui um parser Tree-sitter AST integrado, ele ignora o código-fonte real e verifica apenas o texto em inglês dentro dos blocos de comentários. Se quiser excluir completamente os comentários de uma função específica da verificação, insira uma diretiva inline.

javascript // harper:ignore function processInternalSecurityToken() { // spellcheck:ignore // 내부 보안 토큰 로직 }

2. Controle de Falsos Positivos com Dicionário Personalizado do Projeto

Executar apenas com o dicionário de inglês padrão fará com que termos técnicos como gRPC, OAuth2 e Prometheus sejam identificados como erros. Utilizar uma estrutura de dicionário em camadas permite eliminar rapidamente o ruído dos alertas.

Estrutura de Dicionário em 4 Camadas

O Harper valida as palavras através de 4 camadas.

Camada do Dicionário	Local de Armazenamento	Finalidade
Static Dictionary	Embutido no binário `harper-ls`	Base de dados padrão de palavras em inglês (não modificável)
User Dictionary	`~/.config/harper-ls/dictionary.txt`	Dicionário global para o ambiente de desenvolvimento pessoal
Workspace Dictionary	`.harper-dictionary.txt` na raiz do projeto	Dicionário de termos exclusivo do projeto (gerenciado via Git)
File-Local Dictionary	Salvo no caminho de dados do SO	Armazenamento de identificadores exclusivos de um único arquivo

Registro e Compartilhamento de Termos do Domínio

Crie um arquivo .harper-dictionary.txt no diretório raiz do projeto.
Adicione os termos técnicos usados com frequência, um por linha.

text Kubernetes gRPC OAuth2 OpenTelemetry Prometheus mTLS Netty Etcd

Não se preocupe se um alerta de falso positivo aparecer no editor. Basta usar o recurso Code Action (Ctrl + . no VS Code, ou o atalho de teclado de Code Action no Neovim) para adicionar a palavra diretamente ao .harper-dictionary.txt.

Ao enviar esse arquivo para o repositório Git, todos os membros da equipe compartilharão a mesma lista de palavras.

Ajustando Regras do Linter

Desative regras inconvenientes ao escrever comentários.

SentenceCapitalization: Defina como false para desativar a regra que força a primeira letra do comentário a ser maiúscula.
LongSentences: Defina como false para desativar os avisos de frases longas, comuns em documentações técnicas.
SpellCheck e UnclosedQuotes: Mantenha como true para verificar erros de ortografia e aspas não fechadas.

3. Integração com Pipeline de CI/CD Baseada em GitHub Actions

Erros de digitação que passaram despercebidos pelo desenvolvedor no editor devem ser bloqueados na etapa de PR. Conectar a ferramenta de CLI harper-cli ao pipeline permite filtrar erros gramaticais automaticamente antes da mesclagem na branch principal.

Configuração do Workflow do GitHub Actions

Defina uma task no arquivo .github/workflows/harper-lint.yml para verificar apenas os arquivos Markdown alterados.

`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

Se você comitar o arquivo .harper-dictionary.txt na raiz do projeto, o runner do CI executará a verificação utilizando a mesma lista de palavras do editor. Caso utilize geradores de sites estáticos (SSG) como MkDocs ou Docusaurus, é mais seguro configurar a execução do comando harper-cli lint docs/ imediatamente antes do script de build.

Como Configurar o Harper: Um Verificador Gramatical Offline Sem Vazamento de Dados

1. Instalação do Ambiente de Desenvolvimento e Integração LSP com o Editor

Instalação do Pacote

Execute o comando no terminal para instalar o binário.

macOS / Linux: brew install harper
Ambiente Rust: cargo install harper-ls --locked
Windows: scoop install harper

Integração com Neovim e VS Code

No Neovim, configure os tipos de arquivos alvo e as regras do linter usando o nvim-lspconfig.

`lua
local lspconfig = require('lspconfig')

Ignorando Código Executável e Controlando o Escopo de Verificação

javascript // harper:ignore function processInternalSecurityToken() { // spellcheck:ignore // 내부 보안 토큰 로직 }

2. Controle de Falsos Positivos com Dicionário Personalizado do Projeto

Estrutura de Dicionário em 4 Camadas

O Harper valida as palavras através de 4 camadas.

Camada do Dicionário	Local de Armazenamento	Finalidade
Static Dictionary	Embutido no binário `harper-ls`	Base de dados padrão de palavras em inglês (não modificável)
User Dictionary	`~/.config/harper-ls/dictionary.txt`	Dicionário global para o ambiente de desenvolvimento pessoal
Workspace Dictionary	`.harper-dictionary.txt` na raiz do projeto	Dicionário de termos exclusivo do projeto (gerenciado via Git)
File-Local Dictionary	Salvo no caminho de dados do SO	Armazenamento de identificadores exclusivos de um único arquivo

Registro e Compartilhamento de Termos do Domínio

Crie um arquivo .harper-dictionary.txt no diretório raiz do projeto.
Adicione os termos técnicos usados com frequência, um por linha.

text Kubernetes gRPC OAuth2 OpenTelemetry Prometheus mTLS Netty Etcd

Não se preocupe se um alerta de falso positivo aparecer no editor. Basta usar o recurso Code Action (Ctrl + . no VS Code, ou o atalho de teclado de Code Action no Neovim) para adicionar a palavra diretamente ao .harper-dictionary.txt.

Ao enviar esse arquivo para o repositório Git, todos os membros da equipe compartilharão a mesma lista de palavras.

Ajustando Regras do Linter

Desative regras inconvenientes ao escrever comentários.

SentenceCapitalization: Defina como false para desativar a regra que força a primeira letra do comentário a ser maiúscula.
LongSentences: Defina como false para desativar os avisos de frases longas, comuns em documentações técnicas.
SpellCheck e UnclosedQuotes: Mantenha como true para verificar erros de ortografia e aspas não fechadas.

3. Integração com Pipeline de CI/CD Baseada em GitHub Actions

Configuração do Workflow do GitHub Actions

Defina uma task no arquivo .github/workflows/harper-lint.yml para verificar apenas os arquivos Markdown alterados.

`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

Como Configurar o Harper: Um Verificador Gramatical Offline Sem Vazamento de Dados

관련 영상

Harper: A alternativa gratuita e privada ao Grammarly desenvolvida em Rust

Como Configurar o Harper: Um Verificador Gramatical Offline Sem Vazamento de Dados

1. Instalação do Ambiente de Desenvolvimento e Integração LSP com o Editor

Instalação do Pacote

Integração com Neovim e VS Code

Ignorando Código Executável e Controlando o Escopo de Verificação

2. Controle de Falsos Positivos com Dicionário Personalizado do Projeto

Estrutura de Dicionário em 4 Camadas

Registro e Compartilhamento de Termos do Domínio

Ajustando Regras do Linter

3. Integração com Pipeline de CI/CD Baseada em GitHub Actions

Configuração do Workflow do GitHub Actions

커뮤니티의 다른 글

사내 시스템에 llm api 붙일 때 마주하는 현실적인 한계와 대응법

레거시 백엔드에 GPT-6 Astra 붙일 때 예산 승인과 보안 통과를 먼저 끝내는 법이 있습니다

에이전트끼리 대화하다 6천만 원 청구서가 나오는 이유

사내 RAG 벡터 검색에 Okta 권한 필터를 직접 거는 방법

브라우저 에이전트에게 내 구글 계정을 통째로 넘기면 안 되는 이유

Apple Won the AI Race

댓글 (0)

Como Configurar o Harper: Um Verificador Gramatical Offline Sem Vazamento de Dados

1. Instalação do Ambiente de Desenvolvimento e Integração LSP com o Editor

Instalação do Pacote

Integração com Neovim e VS Code

Ignorando Código Executável e Controlando o Escopo de Verificação

2. Controle de Falsos Positivos com Dicionário Personalizado do Projeto

Estrutura de Dicionário em 4 Camadas

Registro e Compartilhamento de Termos do Domínio

Ajustando Regras do Linter

3. Integração com Pipeline de CI/CD Baseada em GitHub Actions

Configuração do Workflow do GitHub Actions