guides

Migrando da configuração YAML de Espanso para um expansor de texto GUI

Por Equipe Lightning Assist14 de setembro de 20269 minutos de leitura
espansoyamlmigrationguitext-expanderlinuxwindowsmacos
Compartilhar:
Migrando da configuração YAML de Espanso para um expansor de texto GUI

Resposta rápida: O Espanso armazena cada snippet como um par trigger/replace dentro de arquivos YAML de correspondência (~/.config/espanso/match/*.yml), o que significa que adicionar ou editar um snippet exige abrir um editor de texto, respeitar as regras de indentação do YAML e reiniciar o serviço para testar. Migrar para um expansor de texto com GUI como o Lightning Assist significa que cada correspondência vira um snippet em um editor visual — o mesmo texto de gatilho, a mesma substituição, mas um campo de formulário em vez de um arquivo. A partir do Lightning Assist 2.6, os arquivos de correspondência podem ser importados diretamente: escolha o .yml e cada par trigger/replace vira um snippet, com {{date}}, {{clipboard}} e variáveis de formulário convertidas em placeholders. Apenas correspondências com comandos shell e regex ainda precisam de revisão manual.

Divulgação: fazemos Lightning Assist, um expansor de texto pago, então Espanso é um concorrente nosso. Espanso é gratuito e de código aberto, e todas as correções abaixo são para o próprio Espanso – nenhuma delas exige trocar de ferramenta.

Se você nunca abriu ~/.config/espanso/match/base.yml, nada disso significará nada para você, e esse é exatamente o público-alvo deste guia: pessoas que fizeram Espanso funcionar, adicionaram uma dúzia de snippets e agora estão se perguntando se existe uma versão disso em que não precisem pensar em YAML de jeito nenhum.

Por que a configuração YAML de Espanso se torna um atrito

Espanso é genuinamente bem construído. É gratuito, de código aberto, multiplataforma e seu modelo baseado em arquivo é uma escolha de design deliberada, não um descuido - o YAML é portátil, permite comparação com diff e é programável por script. O atrito aparece mais tarde, quando você realmente o usa no dia a dia:

Arquivos de correspondência espalhados pelo seu sistema de arquivos. Espanso organiza a configuração em uma pasta match/ (o que expandir) e uma pasta config/ (como a expansão se comporta), começando em match/base.yml. À medida que sua contagem de snippets aumenta, você continua adicionando àquele mesmo arquivo ou começa a dividir em mais arquivos .yml - de qualquer forma, encontrar "aquele sobre preços" seis meses depois significa abrir arquivos e vasculhar, porque não há caixa de pesquisa.

Indentação é a sintaxe. Uma correspondência básica se parece com:

matches:
  - trigger: ":br"
    replace: "Best Regards,\nJon Snow"

A própria documentação de Espanso é direta sobre isso: "Certifique-se de incluir o recuo, caso contrário não será uma sintaxe YAML válida." Isso é bom para um desenvolvedor confortável em um editor de texto, e é exatamente o tipo de coisa que quebra silenciosamente quando você cola um snippet vindo do Slack ou copia um bloco de várias linhas e o espaço em branco não vem junto. A maneira como você geralmente descobre é que o gatilho simplesmente não expande – nenhum diálogo, nenhum rabisco vermelho, apenas um snippet que silenciosamente não faz nada até que você procure um espaço perdido.

Sem sincronização, sem equipe. Espanso armazena tudo localmente por design - genuinamente bom para a privacidade, mas significa que colocar seus snippets em uma segunda máquina é uma cópia manual de arquivo, uma pasta do Dropbox ou um repositório git pessoal que você mesmo mantém. Não há conta, nem sincronização integrada entre vários dispositivos, nem maneira de entregar sua biblioteca de snippets a um colega, exceto enviando-lhes os arquivos .yml e pedindo-lhes para colocá-los na pasta correta.

Reiniciar para testar. Editar um arquivo de correspondência e confirmar se ele funcionou geralmente significa salvar, voltar para o aplicativo em que você está testando, digitar o gatilho e - se ele não disparar - voltar para verificar o arquivo. É um loop curto, mas é um loop que você repete a cada mudança, para sempre.

Nada disso faz de Espanso um software ruim. Isso o torna um software desenvolvido para pessoas que se sentem confortáveis ​​em tratar a configuração como código. Se não é assim que você deseja gastar seu tempo, uma GUI é a solução - não um editor YAML "melhor".

Qual é a aparência real do equivalente da GUI

Em um expansor de texto com GUI, um snippet é uma linha, não um arquivo. Você abre um painel (em Lightning Assist, é “Meus Snippets”), clica em “Criar Snippet”, digita o gatilho em um campo e a expansão em outro e salva. Não há nenhum arquivo para localizar, nenhum serviço para reiniciar e nenhum recuo para acertar, porque não há recuo - rich text, formatação HTML e conteúdo multilinha são todos digitados ou colados diretamente no campo de expansão sem necessidade de escape. Os snippets são organizados em pastas que você mesmo nomeia e você pode pesquisar em toda a sua biblioteca em vez de vasculhar arquivos.

A compensação é a que você esperaria: você abre mão do acesso direto ao arquivo (sem fazer git diff no histórico dos seus snippets, sem editar no Vim) em troca de não precisar de nenhuma das mecânicas do YAML desde o início.

Espanso → Lightning Assist: Mapa Conceitual

Se você já pensa no vocabulário de Espanso, veja como cada peça é mapeada:

Conceito de Espanso Em YAML Equivalente na GUI
Correspondência Uma entrada em matches: em um arquivo .yml Um snippet — uma linha no painel Snippets
Gatilho trigger: ":br" O campo Trigger — digite a mesma abreviação diretamente, sem necessidade dos dois pontos, a menos que você queira mantê-los
Substituir replace: "Best Regards,\nJon Snow" O texto de expansão do snippet — rich text, HTML e conteúdo multilinha com suporte nativo
Vars/extensões (data, shell, área de transferência, formulário) Um bloco vars: referenciando um tipo de variável Espaços reservados inseridos na expansão — [#Date#] e [#Name#]
Arquivos de correspondência (base.yml, .ymls personalizados) Arquivos dentro de ~/.config/espanso/match/ Pastas no painel Snippets — organize visualmente em vez de por nome de arquivo
Recarregar / espanso restart Reinicialização manual do serviço para coletar alterações Nada para fazer – os snippets ficam ativos no momento em que você salva
Gatilhos Regex, correspondências de comando shell YAML + script, específico de Espanso Não replicado. Se isso for fundamental para seu fluxo de trabalho, continue no Espanso para esses casos

A última linha é importante: este é um guia de migração, não uma afirmação "Lightning Assist pode fazer tudo que Espanso pode". Gatilhos baseados em regex e correspondências apoiadas por comandos shell são pontos fortes genuínos do Espanso, sem equivalente de GUI aqui.

Passo a Passo: Importando Seus Arquivos de Correspondência

Atualizado em 7 de setembro de 2026: o Lightning Assist agora importa arquivos de correspondência do Espanso diretamente, então a recriação um a um que este guia descrevia não é mais necessária.

  1. Encontre suas correspondências existentes. Execute espanso path e abra a pasta match apontada (geralmente ~/.config/espanso/match/). Todo arquivo .yml ali com uma lista matches: pode ser importado como está; não é necessário mesclá-los antes.
  2. Instale o expansor GUI e pule qualquer arquivo de configuração. Experimente o Lightning Assist grátis por 14 dias — sem cartão de crédito. O app abre direto no painel de snippets; não há arquivo de configuração para criar antes.
  3. Importe cada arquivo de correspondência. Em My Snippets, clique em Import e escolha o arquivo .yml. Cada correspondência vira um snippet: trigger (ou a primeira entrada de triggers) vira o gatilho, replace vira a expansão, e label vira o nome do snippet quando presente. Símbolos iniciais são mantidos, então :br continua :br. A importação está disponível em todos os planos. No plano gratuito, cada importação traz até 5 correspondências e a biblioteca comporta 20; o teste gratuito de 14 dias eleva o limite para 20 por importação, e o Pro remove ambos os limites. Qualquer coisa que não couber é listada, não descartada silenciosamente.
  4. Verifique as variáveis. Variáveis {{date}}, {{clipboard}} e {{form.field}} são convertidas nos placeholders correspondentes, como [#date#] e [#clipboard#]. Tudo que o importador não conseguir traduzir — variáveis de comando shell, scripts, gatilhos regex — fica visível no texto da expansão em vez de ser apagado, para que você possa revisar e corrigir. Se esses forem essenciais para uma correspondência, mantenha-a no Espanso.
  5. Configure seu modo de gatilho. A expansão Inline (digite o gatilho e ele se expande conforme você digita) é o padrão e não precisa de configuração. Se preferir pressionar uma tecla após digitar o gatilho, escolha Atalho uma vez na tela Ativação.
  6. Teste antes de apagar qualquer coisa. Experimente cada snippet em um documento de teste. Mantenha sua configuração do Espanso até confirmar que o conjunto migrado funciona como esperado — não há problema em manter ambos lado a lado temporariamente.

A importação em si leva segundos; o tempo maior é gasto no passo 4, revisando correspondências que usam comandos shell ou regex. Para uma biblioteca típica de correspondências em texto simples, toda a migração leva alguns minutos.

O Que Você Ganha e O Que Você Perde

O que você ganha: nada de arquivos de configuração, sem ciclo de reiniciar para testar, uma biblioteca de snippets pesquisável organizada em pastas, comandos de IA que reescrevem ou traduzem texto selecionado via atalho, ditado push-to-talk na mesma aplicação, sincronização automática na nuvem entre dispositivos e compartilhamento de snippets em equipe se precisar. Tudo isso roda no Windows, macOS e Linux com a mesma conta.

O que você perde: o Espanso é gratuito e open-source para sempre — o Lightning Assist também é gratuito e ilimitado, com até 20 snippets, pastas e uma equipe incluídos — mas uma biblioteca maior e mais equipes custam $5.99/mês após o teste de 14 dias (o plano Pro inclui uma cota mensal de créditos de IA para comandos e de créditos de Speech para a voz). Você também perde gatilhos baseados em regex e correspondências com comandos shell, que não têm equivalente no modelo GUI. Se esses são os motivos para usar Espanso, essa migração não é para você — e isso é uma razão legítima para continuar.

Se quiser uma GUI sem sair totalmente do ecossistema Espanso, existem projetos comunitários — espansoGUI (Rust/Iced, no Flathub), EspansoEdit (freeware para Windows) e o EspansoGUI IDE. Vale a pena experimentar, mas cada um é uma camada separada mantida por voluntários sobre os mesmos arquivos YAML; o próprio Espanso ainda não tem GUI oficial além da janela de busca (a última versão estável do projeto principal é a v2.4.1, 2 de setembro de 2026). Se o que você quer é uma ferramenta onde a GUI é o produto, essa é a lacuna que esta migração preenche.

Perguntas Frequentes

Posso importar meus arquivos YAML do Espanso diretamente?

Sim. Em My Snippets, clique em Import e selecione um arquivo de correspondência (.yml). Cada par trigger/replace vira um snippet, label vira o nome, e {{date}}, {{clipboard}} e campos de formulário viram placeholders. Variáveis de comando shell e gatilhos regex não têm equivalente e ficam como texto visível para você revisar.

Vou perder meus gatilhos baseados em regex ou correspondências com comandos shell?

Sim. Essas são capacidades específicas do Espanso baseadas no modelo YAML/scripting, e não há equivalente GUI aqui. Se gatilhos regex ou correspondências com shell são centrais para sua configuração, continue usando Espanso para eles e considere um expansor GUI só para seus snippets mais simples e estáticos.

Posso manter o mesmo texto de gatilho, como :br ou /addr?

Sim. O campo Trigger aceita qualquer texto que você digitar, incluindo um : ou / inicial se essa for sua convenção. Nada obriga você a mudar seu estilo de abreviação durante a migração.

Existe uma GUI oficial do Espanso que eu deveria experimentar antes de trocar de ferramenta?

Não há uma oficial. Projetos comunitários como espansoGUI, EspansoEdit e o EspansoGUI IDE adicionam uma camada gráfica, mas são ferramentas separadas mantidas por voluntários que ficam sobre os mesmos arquivos YAML — você ainda está um passo longe da configuração bruta. Se você quer que a GUI seja o produto inteiro e não um complemento, essa é a diferença que esta migração aborda.

Leitura Relacionada

Fontes

Artigos relacionados