Ir para o conteúdo

Guias

Quando algo falha

Comece por npx verbaly doctor. Ele inspeciona o setup inteiro e imprime a correção exata ao lado de cada achado, então quase toda esta página é o que ele lhe teria dito.

O comando verbaly não existe

O comando vive em @verbaly/compiler. Os plugins dependem dele, mas um gestor de pacotes só liga o comando de um pacote que você mesmo instalou, então não basta um plugin trazê-lo. Adicione-o às suas dependências de desenvolvimento:

pnpm add -D @verbaly/compiler

Apareceu um idioma que eu nunca pedi

Se você não listar locales, cada arquivo JSON da sua pasta de catálogos conta como um idioma, tirando o do pseudo-idioma. Por isso um que ficou de uma execução anterior também é, e o build começa a pedir as traduções dele. Liste os seus idiomas e a lista fica completa:

locales: ['es', 'en']  // now a stray pt.json is ignored

Um aviso diz que um idioma não é um código válido

pt-BR é como se escreve um código de idioma, com um hífen entre as suas partes. pt_BR, do jeito que o gettext e muitos backends escrevem, não é um código que o navegador consiga ler. O Verbaly o lê como pt-BR para que números, datas e plurais continuem formatando, e avisa uma vez que fez isso. Um código sem correção segura formata no idioma padrão do navegador, com o mesmo aviso. O doctor nomeia cada um da sua config com o novo nome: mude o nome do arquivo do catálogo e a sua config juntos.

[verbaly] "pt_BR" is not a locale tag, so Intl reads it as pt-BR

o wrap reportou arquivos que não escreveu

Um arquivo onde t não está disponível é listado e fica intacto, porque envolver texto ali deixaria o seu projeto sem compilar. O relatório diz quantos textos esperam em cada um e se é um componente de cliente, para você saber que linha adicionar. Adicione-a e execute de novo.

O build diz que uma tradução está quebrada

Não falta, está quebrada: a tradução está lá e não consegue renderizar o que a fonte renderiza. Perdeu um {value}, tirou um caso do plural ou mudou uma tag. Cada build as lista primeiro, porque renderizam errado, e o npx verbaly check dá o motivo exato de cada mensagem e falha com elas no CI.

O build compilou e depois listou traduções

É ali que a verificação roda. No Next.js, o next build compila o seu app primeiro e depois lista as chaves que faltam, as quebradas e as desconhecidas, então os comandos que só carregam o seu config, como next typegen, nunca a rodam. Preencha o que ele lista, ou rode npx verbaly check antes do build para ver a mesma lista antes. Com failOnMissing: true, o build para ali em vez disso.

O build diz que uma opção está no plugin

verbaly check e verbaly extract leem o seu verbaly.config, nunca as opções que você passa ao plugin. Quando os dois não coincidem, a linha de comandos verifica algo diferente do que o build publica. Mova a opção para o arquivo e o aviso some.

[verbaly] sourceLocale is set in the plugin options, which `verbaly check` and `verbaly extract` never read: move it to verbaly.config so the command line checks what the build ships

switchLocale fica no mesmo endereço no Astro

O i18n do Astro e a sua config do Verbaly não coincidem, então switchLocale e localePath ficam com um só endereço em vez de mandar o visitante para uma página que não existe. O servidor de desenvolvimento e o build dizem qual dos dois casos é: o defaultLocale do Astro não é o seu sourceLocale, ou um idioma tem um caminho que não é nenhum dos seus códigos. No primeiro, faça com que sejam o mesmo idioma ou defina prefixDefaultLocale: true. No segundo, use o código do idioma como caminho.

[verbaly] Astro's i18n serves its defaultLocale "es" at the root, but Verbaly's sourceLocale "en" is the language without a prefix, so switchLocale and localePath keep one address: make them the same language, or set prefixDefaultLocale: true

Aparece uma chave na tela em vez do texto

Uma mensagem que não resolve em lugar nenhum se renderiza como a sua própria chave. Normalmente o catálogo desse idioma ainda não chegou, ou o grupo é um que você excluiu do navegador com bundle.exclude e algo o pede em runtime. O build avisa do segundo caso pelo nome. Se só acontece no seu idioma fonte, o mais provável é que a chave esteja em uma tradução e não no seu catálogo fonte: npx verbaly check a lista como uma chave que só uma tradução tem.

Minha edição no catálogo fonte sumiu

Esse texto está escrito no seu código, com t`…` ou t.id, então ele é do código: o servidor de desenvolvimento, o extract e o build colocam o texto do código de volta. A mensagem diz qual arquivo o tem, e é lá que se muda. Se você quer editar um texto no catálogo, deixe só a chave dele no código, como t('key'). No terminal, o extract imprime uma linha para cada texto que colocou de volta, com o texto que tinha, para você ver exatamente o que ele desfez.

[verbaly] es.json: your edit of "footer.copyright" was replaced, its text lives in src/components/Footer.tsx:12: change it there

Uma tradução aparece como desatualizada

O texto fonte dela mudou depois que foi escrita, e ninguém a tocou desde então. Também pode aparecer logo depois de um import: o arquivo de um tradutor traz o texto fonte de onde partiu, então um arquivo feito para uma versão anterior já chega desatualizado. Atualize a tradução e o aviso some sozinho. Se ela ainda diz a coisa certa, mantenha com npx verbaly review --approve. Nunca quebra um build a menos que o seu CI rode check --outdated.

O verbaly.lock tem um conflito de merge

O verbaly.lock registra quais traduções são rascunhos da máquina e para qual texto fonte cada uma foi escrita. Quando duas branches traduziram em paralelo, um merge pode deixá-lo com um conflito, e não há lado para escolher: o Verbaly lê os dois e mantém todos os rascunhos de cada um. O próximo extract escreve o arquivo inteiro e avisa. Adicione-o ao commit que resolve o merge.

verbaly.lock had a merge conflict and now holds both sides, drafts and stamps included: add it to the commit that resolves the merge

Se o arquivo continuar ilegível (um conflito editado pela metade, por exemplo), os comandos que só o leem avisam e seguem, e os que escreveriam rascunhos param antes de escrever qualquer coisa. Corrija-o à mão e mantenha as entradas dos dois lados: apagá-lo, ou ficar com um lado só, aprovaria rascunhos que ninguém leu.

Um texto fica no meu idioma fonte

O compilador só lê as chamadas que se chamam t, então de uma função de tradução com outro nome, como const tr = useT(), o texto nunca é extraído. O extract e o doctor apontam cada uma com o arquivo e a linha, também em arquivos .vue, .svelte e .astro: renomeie para t. Se o arquivo está fora do seu include, nada nele é lido também, e o seu build e o servidor de desenvolvimento o apontam ao começar, com o padrão a adicionar:

[verbaly] components/save-button.tsx uses t`…` outside the include of your verbaly config, so its texts are never extracted and show in en in every language: add "components/**/*.{js,jsx,ts,tsx,mjs,mts,cjs,cts,svelte,vue,astro}" to include (or the file to exclude, if it is not app code)

A página trocou de idioma logo depois de carregar

A página chegou em um idioma e a instância do navegador começou em outro, então o bindDom traduziu a página para o dele. Ele avisa uma vez, nomeando os dois. Quando o endereço leva o idioma, crie a instância com o idioma que o localeFromPath lê dele; quando não, chame antes o persistLocale, para que a página e o navegador partam da mesma escolha.

[verbaly] the page is <html lang="es"> and this instance is in "en": read the url with localeFromPath, or call persistLocale first

Uma mensagem mostra o seu código ICU em vez do texto

A sintaxe ICU precisa do seu parser, e o compilador só o inclui quando algum dos seus catálogos usa essa sintaxe no build. Uma mensagem que chega depois, de um CMS ou pelo addMessages, não encontra parser, então mostra o seu próprio código e avisa uma vez. Coloque icu: true na sua config do verbaly para incluir sempre o parser, ou passe icu: parseIcu ao createVerbaly se você cria a instância.

[verbaly] a message uses ICU syntax and no ICU parser is loaded: set icu: true in your verbaly config, or pass icu to createVerbaly

As minhas chaves não estão tipadas, ou os tipos estão velhos

Os tipos são escritos pelo extract, pelos servidores de desenvolvimento e por cada build, e o svelte-check e o Vitest escrevem os mesmos, então um clone novo não tem nenhum até que um deles rode. Um script que verifica os tipos antes de construir (tsc -b && vite build, como o do template de React) roda antes de todos: npx verbaly typegen os escreve sozinho, e é a solução para Cannot find module 'verbaly/app'. Eles vão para onde o seu framework já os lê, e um Cannot redeclare significa um verbaly.d.ts antigo que ficou na raiz, que a próxima execução remove. Um erro de digitação numa chave falha com a chave no erro.

O prune deixou chaves que você não usa mais

Enquanto algum arquivo fonte não puder ser lido, o extract --prune não remove nada e aponta o arquivo. Um arquivo que ele não consegue ler pode ser justamente o que usa essas chaves, e removê-las nesse momento apagaria as traduções delas. Corrija o erro de sintaxe e rode de novo.

Não se consegue importar t do verbaly

Nenhum pacote exporta t. Ele vem do módulo próprio do seu projeto, verbaly/app, ou do hook do seu framework. O doctor reporta este como erro porque nenhum bundler o consegue resolver.

Um alias de verbaly quebra verbaly/app

No Vite um alias roda antes de qualquer plugin, e uma chave de texto também casa com os seus subcaminhos, então { verbaly: './caminho' } pega também verbaly/app. Escreva o alias exato: { find: /^verbaly$/, replacement: './caminho' }.

O ESLint diz que não encontra verbaly/app

verbaly/app é escrito pelo plugin, então a regra import/no-unresolved do ESLint não o encontra em disco. Libere-o do mesmo jeito que um projeto Vite libera os seus módulos virtuais: ignore: ['^verbaly/app$'].

↑↓para navegarEnterpara abrir
Copiado para a área de transferência