Cria gerador de dicionário modular

[andrepg]

Descrição de PR

Há possibilidade de estes códigos precisarem de alterações para inclusão no CI e novo fluxo de formatação incluído (ou o contrário).

Cria script para ler pastas com termos e gerar arquivo de dicionário.

Issue relacionado

• 📝 Nova estrutura de organização de termos do dicionário #256
• 📝 Nova estrutura de organização de termos do dicionário #171

Motivações

Buscando aquilo discutido na #171, este PR visa incluir um modo automatizado de construir o dicionário de termos e permitir melhor manutenção do conteúdo.

Informações adicionais

A ideia inicial consistia em um script JavaScript para coletar as informações e juntar na renderização. Após verificar commits recentes e novas implementações do GH Actions e Git hooks, optei por seguir de outra forma.

Assim, evitamos tocar o código relacionado à leitura dos cards. Vamos, em vez disso, trabalhar na geração do arquivo-fonte para este código.

O generator.py recebe dois argumentos e faz a leitura dos termos na pasta correspondente, para gerar, ao final, um dicionário no mesmo modelo do arquivo cards_pt-br.json que hoje existe.

Os argumentos são

• -l/--language: código da linguagem (e nome da pasta fonte dos arquivos)
• -o/--output: caminho de dump do dicionário em JSON, após processamento

⚠️ É importante notar que, da forma como construído, o script precisa estar dentro da pasta dicionario, pois lerá as pastas de forma relativa à sua execução. Podemos mudar se necessário.

[netlify]

✅ Deploy Preview for diciotech ready!

Name	Link
🔨 Latest commit	9df0da4
🔍 Latest deploy log	https://app.netlify.com/sites/diciotech/deploys/672a1d069f15120008427344
😎 Deploy Preview	https://deploy-preview-257--diciotech.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[george-gca]

Por curiosidade, por que acha melhor um script por fora pra isso, ao invés de ler tudo em javascript?

[andrepg]

Por curiosidade, por que acha melhor um script por fora pra isso, ao invés de ler tudo em javascript?

Foi uma decisão mais “cômoda”, por assim dizer. Já existe um scritpt Python que faz a manipulação dos arquivos e no repositório, dentro do meu estudo, parecia mais tranquilo trabalhar como este arquivo e gerar o JSON final para manter o código de leitura do JSON intocado.

Então, peguei a ideia emprestado e comecei a trabalhar nesse sentido. Isso evitou modificações no que já está funcionando e nos permite criar várias linguagens diferentes dos termos, já que basta passar um argumento para script.

[george-gca]

O problema disso é que ele não tá integrado ao CI e precisa ser rodado manualmente. Pra dar cabo de todos os usos possíveis tem que adicionar ele num GitHub action pra rodar automaticamente. Mas toda vez que ele for rodado ele vai gerar um novo arquivo, que aí precisa também ser versionado.

Inclusive isso é feito atualmente no sass e não sei se é a melhor opção. O ideal é que tanto esse arquivo integrado quanto os arquivos css não fossem versionados e sempre gerados a partir do sass e dos arquivos individuais de letras nesse caso. Mas acho que isso precisa ser discutido melhor.

[andrepg]

Bom ponto. A minha ideia foi justamente utilizar o CI, já que andei observando o trabalho de vocês e havia alguns scripts para rodarem assim (formatação e hooks).

Confesso que não considerei a integração com Netlify. E, hoje, está em Python. Mas, transformar este script para JS ou até mesmo implementar um sistema de build Vite não é complicado. O raciocínio lógico (que era o mais importante para mim) está pronto. Agora com este código funcionando é possível adaptar.

A minha ideia principal era não tocar no cards_pt-br.json e tratá-lo como um asset. Daí a transferência dos termos para outra pasta sem relação com a public. Deixando para a build a responsabilidade de gerar o arquivo de cards antes do deploy (e isso mataria aquele problema de conflito).

Por outro lado, temos os termos já separados em letras na estrutura proposta. Agora a gente invoca a @levxyca para dar uma terceira visão.

[george-gca]

Pensando melhor sobre isso, se a gente usasse o Jekyll isso poderia ser integrado ao build, tanto essa parte como a parte do sass. Uma das vantagens seria que a gente poderia deixar de versionar os arquivos css e o cards_pt-br.json e versionar somente os scss e as letras individuais, porque o css e o cards_pt.br.json seriam gerados automaticamente.

[levxyca]

Invocada fui 😝 Calma que já estou chegando nesse PR pra revisar e ficar a par de tudo 💙 Obrigada pela paciência de sempre pessoal!

[george-gca]

Paciência nada. Quero já um pix na minha conta com o valor de uma cerveja a cada dia esperado pela revisão haha.

[levxyca]

@andrepg @george-gca estava dando um bizu aqui 👀 acredito que essa feature possa nos ajudar bastante, tenho alguns pontos, o ideal fosse conseguir executar o fluxo da seguinte forma:

• Pessoa colaboradora adicionar/alterar o termo técnico dentro do arquivo de sua letra inicial.
• Viesse para o review apenas o arquivo original alterado.
• Depois que o PR estivesse aprovado rodar um GitHub Action para gerar esse arquivo automático e assim dar merge.

Ainda tem mais um ponto de consideração:
Atualmente temos dois PR's na fila sobre suporte a múltiplas linguagens: #140 e #217, como vai funcionar após juntar tudo isso? Acredito que vale discutirmos isso também.

Agora o último ponto 😝 acho importante depois de tudo definido também, acrescentar já a documentação de uso. Acho que foi colocar como requisito de features "maiores" ou algo assim, vejo que o pessoal acaba tendo algum dificuldade ás vezes, por exemplo, até com o uso do SCSS, onde editam os arquivos .css direto 🤔

[george-gca]

O #140 e o #217 são mutuamente exclusivos, então um passando o outro deve ser fechado.

Eu acredito que com o jekyll consigo suprir todos esses pontos. Me dá mais uns dias que eu vou fazer uma versão pra ver se supre tudo isso mesmo. Mas eu só vou fazer a documentação quando o resto estiver aprovado, pra não investir um tempo nisso e acabar não subindo a PR. Aí acho que vai mais um tempo na documentação e aí a gente analisa se tá tudo certo.

[andrepg]

Bom, vamos lá @levxyca. Tive um tempo apertado ontem para responder. Quanto aos questionamentos do PR, eu pensei quase nesse mesmo fluxo seu.

1. As alterações de termos são feitas sempre na pasta dicionario, dentro de cada linguagem;
2. O script busca (com ajuda de um argumento --language) dentro de cada pasta específica e gera um cards_[linguagem].json no diretório especificado pelo --output
3. Não há trigger específica, ele pode ser chamado a qualquer momento — foi criado exatamente para isto!

---

Por exemplo:

No caso do #140 a lógica seria incluir os termos em inglês, rodar o gerador na pasta en e revisar a lógica de multilinguagem no frontend.

Lembrando que a minha decisão por um script independente foi adicionar um passo ANTES, e o front sequer saberia dessa modificação, já que o arquivo cards_[language].json continua a existir, mas mantido de outra forma.

---

Agora, entra a questão que o @george-gca levantou: vamos manter os arquivos de linguagem também no diretório public? Ou deixamos para o GH gerar? Ou deixamos para o Netlify resolver isso?

Esse é o grande ponto, já que os manter aumenta complexidade de manutenção, fazendo commit aqui e ali. Acredito que, com tanto craque neste repositório, chegamos fácil em qualquer solução baseada em script (Bash, Python, até PHP 😆) e no Actions para fazer build. Basta definir o pipeline.

Quanto à documentação, posso criar uma pasta no repositório ou podemos utilizar a Wiki do projeto. Planejarei o README deste PR no meu Obsidian e faço upload quando tivermos isto definido.

Quanto a layout, eu não manjo de Jekyll, sou mais do VueJS/Laravel/Tailwind, mas documentação, organização, ideias e pequenas ferramentas e soluções é comigo mesmo 👋🏻

Precisando, só pingar!

---

PS.: ℹ️ Nós já temos NPM e Python no Netlify, conforme os logs de build. No repositório também já existe um package.json que poderia ser usado. Além do próprio GH.

[levxyca]

@andrepg quero agradecer todo o cuidado e empenho que você colocou nesse PR e na resposta tão detalhada que compartilhou 💙 Depois de algumas discussões e reavaliações, decidimos seguir com a abordagem apresentada no PR #267, que implementando essa funcionalidade em conjunto com o Jekyll. Por isso, vou fechar este PR, mas saiba que sua contribuição foi essencial para amadurecermos o caminho que escolhemos seguir.

Muito obrigado mais uma vez!