[V2] Adiciona suporte a múltiplas línguas usando Jekyll Polyglot

[george-gca]

Descrição de PR

Essa PR é uma continuação da #217, mas preferi criar uma nova PR porque era mais fácil fazer do 0 a partir da main do que fazer um merge naquela branch. Inclusive tenta priorizar analisar essa PR @levxyca antes de aprovar as outras. Acho que é mais fácil depois a gente pegar a contribuição da galera de termos e só aplicar aqui, ou pedir pra refazerem a partir da nova main.

Explicando um pouco mais o jekyll: por definição ele é um gerador de sites estáticos. Pensa nele como um "compilador de sites", ele faz um build usando vários arquivos e gera os arquivos html, css e js finais. Por isso que com ele dá pra fazer essas coisas.

Principais novidades:

• implementa a Cria gerador de dicionário modular #257 (resolve 📝 Nova estrutura de organização de termos do dicionário #256) usando o próprio jekyll, sendo possível separar os arquivos dos cards por letra
  • os dados dos cards agora estão em yml, o que é mais legível pra um ser humano e acho que facilita a adição de novos termos. Eles ficam em _data/LANG/LETRA.yml
  • os arquivos yml são lidos nos arquivos _assets/LANG/cards.json e unificados em um json por língua (resolve Implementação de Tradução nos Cards #185), sendo que eles não precisam ser modificados e os arquivos json finais não precisam ser versionados (são gerados durante o build do jekyll)
• resolve o problema do css
  • arquivos css removidos do git, e o arquivo style.css é gerado durante o build do jekyll, ou seja, só existe os arquivos scss no git então a modificação precisa ser feita neles

Faltam:

• documentar tudo isso direitinho (farei assim que aprovada a ideia, ainda nesta PR)
• traduzir todos os termos do dicionário
• estilizar o botão de troca de idioma (prefiro deixar isso pra quem manja, eu sei como seria legal ficar mas não sei como fazer isso)

Pra ter uma noção, basicamente a estrutura de pastas do projeto vira isso (tirei os arquivos que não serão modificados da visualização, como README, etc, pra simplificar):

diciotech
├── _assets (cria os cards.json final a partir dos yml)
│   ├── en-us
│   │   └── cards.json
│   └── pt-br
│       └── cards.json
├── assets (vão ser copiados tal qual pro repositório final, menos o style.scss)
│   ├── css
│   │   └── style.scss (usado pra gerar o style.css final)
│   ├── img
│   │   └── ...
│   └── js
│       ├── cookies.js
│       ├── levenshtein.js
│       └── theme.js
├── _config.yml
├── _data (onde ficam os dados de fato dos cards)
│   ├── en-us
│   │   ├── a.yml
│   │   ├── ...
│   │   └── z.yml
│   └── pt-br
│       ├── a.yml
│       ├── ...
│       └── x.yml
├── Gemfile
├── Gemfile.lock
├── _includes
│   └── script.liquid (= script.js)
├── _layouts
│   └── base.liquid (= index.html)
├── _pages (onde ficam as traduções dos termos nas páginas)
│   ├── en-us
│   │   └── search.md
│   └── pt-br
│       └── search.md
└── _sass (vai ser todo compilado no style.css)
    ├── base.scss
    ├── cookies.scss
    ├── dark_theme.scss
    ├── light_theme.scss
    └── variables.scss

E esse é o resultado do build do jekyll, ou seja, as pastas que vão subir pro Netlify:

_site/
├── assets
│   ├── css
│   │   └── style.css
│   ├── data
│   │   └── cards.json
│   ├── img
│   │   └── ...
│   └── js
│       ├── cookies.js
│       ├── levenshtein.js
│       └── theme.js
├── diciotech.webmanifest
├── en-us
│   ├── assets
│   │   └── data
│   │       └── cards.json
│   ├── diciotech.webmanifest
│   └── index.html
└── index.html

Pra acessar o site em português é só acessar normal, e o em inglês é só acessar com /en-us.

Issue relacionado

• 📝 Nova estrutura de organização de termos do dicionário #171
• Resolve Implementação de Tradução nos Cards #185

Motivações

Pra não copiar todo o texto de novo, as motivações e etc estão na #217.

Informações adicionais

O build do Netlify vai falhar até mudar pra usar o Jekyll nele, então gerei uma versão no Netlify do meu branch aqui.

[netlify]

❌ Deploy Preview for diciotech failed.

Name	Link
🔨 Latest commit	0bd27ef
🔍 Latest deploy log	https://app.netlify.com/sites/diciotech/deploys/67699111cc11ca000892db07

[levxyca]

@george-gca eu finalmente consegui olhar sua PR! Eu gostei bastante, acho que definitivamente vai facilitar o projeto e tendo uma documentação boa, não vejo o motivo de não fluir bem! Vou dar um check com o pessoal nas duas PRs maiores que estamos abertas para seguirmos por esse caminho!

[levxyca]

@george-gca consegue dar uma avaliada nessa ideia de issue #270? Acha que faz sentido? Como issa impactaria sua implementação?

[george-gca]

Beleza, então vou dar continuidade na implementação. É bom que tu vais ser o teste de documentação, conseguir reproduzir o ambiente só lendo haha o/

[levxyca]

Perfeito @george-gca hahahaha

[george-gca]

@levxyca tô dando um trato nisso agora. Por favor, não aceita NENHUMA outra PR até eu terminar isso, que tá dando um trabalho fazer o merge porque eu mudei muita coisa na estrutura.

[george-gca]

@levxyca chegou o momento de testar. Clona o meu branch, dá uma lida no CONTRIBUTING.md e vê se entende todo o processo, se consegue replicar, etc.

Não precisa fazer a instalação manual se não quiser, ela é o caminho que eu uso pra executar localmente então essa eu garanto que funciona. O devcontainer que eu não tenho muita experiência e seria legal validar, até porque é a forma mais fácil de ter todas as dependências necessárias pra rodar o código localmente de uma forma isolada.

Vê se a documentação tá clara, as explicações fazem sentido, se alguém que nunca viu Jekyll consegue pegar e começar daí. Qualquer melhoria que conseguir ver, só falar o/

PS: essas 2 ações tão falhando faz um tempo mas elas tão bem estranhas. Elas tão falhando na hora inclusive de clonar o repositório, o que é estranho. Tem até um bug aberto sobre isso, comentei lá, bora ver se alguém dá algumas resposta, mas na pior das hipóteses a gente comenta essas ações.

[levxyca]

@george-gca vi depois de aceitar uma PR 😭 mas fechado! vou tentar ir replicando o processo e logo mais volto aqui com os feedbacks!

[levxyca]

@george-gca vou começar aqui os meus feedbacks 😛

Falando de documentação no geral:

1. No CONTRIBUTING.md essa parte ficou meio confusa, lendo não fica totalmente claro qual a diferença dessas duas pastas assets.

├── _assets (cria os cards.json final a partir dos yml)
│   ├── en-us
│   │   └── cards.json
│   └── pt-br
│       └── cards.json
├── assets (vão ser copiados tal qual pro repositório final, menos o style.scss)

2. Aqui é onde as pessoas contribuidoras vão adicionar os termos, certo? Eu alteraria essa descrição para deixar mais assertivo, “_data é onde ficam os dados reais dos cards. Se você precisar alterar ou adicionar termos, é aqui que deve fazer as modificações.”.

├── _data (onde ficam os dados de fato dos cards)
│   ├── en-us
│   │   ├── a.yml
│   │   ├── ...
│   │   └── z.yml
│   └── pt-br
│       ├── a.yml
│       ├── ...
│       └── z.yml

3. Mesmo caso aqui, se quiser modificar algo do script, é aqui que mexe né?

│   └── script.liquid.js (script que gera o script.js final

4. Aqui também:

_sass contém os arquivos de estilo que serão compilados no style.css final. Qualquer ajuste de design deve ser feito aqui.

Sobre a instalação do ambiente para contribuir usando o DevContainer:

1. Eu sei que clicando no link do Docker a gente vai pra página deles que tem tudo, mas seria interessante ter um passo mínimo ali de orientação, sei que parece pode parecer meio óbvio ou simples demais, mas acredito que isso faz com que as pessoas contribuidoras que nunca usaram Docker se sintam um pouco mais seguras. Então talvez ter algo simples mesmo como, acesse o site do Docker... baixe a versão adequada pro seu sistema operacional e por aí vai.

Obs:. Ainda não terminei de olhar tudo mas já vou ir deixando conforme eu for olhando os comentários aqui pra não perder.

[george-gca]

@levxyca boaaaaaa. Quanto as considerações:

• sobre o docker, eu concordo. Inclusive queria que tu fizesses essa parte, se possível, ou de repente alguma outra pessoa. Eu uso linux, e sei que o processo de instalação é completamente diferente do windows. Eu posso fazer essa parte pro linux, mas pro resto não quero fazer um tutorial que não sei se dá certo
• então, eu não quis adicionar todo esse texto nessa parte da árvore de diretórios porque eu achei que ia ficar ruim de ler, tipo:

diciotech
...
├── _config.yml (arquivo de configuração do Jekyll)
├── _data (onde ficam os dados reais dos cards. Se você precisar alterar ou adicionar termos, é aqui que deve fazer as modificações.)
│   ├── en-us
│   │   ├── a.yml
│   │   ├── ...
│   │   └── z.yml
│   └── pt-br
│       ├── a.yml
│       ├── ...
│       └── z.yml
...

Aí eu tentei adicionar esse texto depois de alguma forma, mas concordo que provavelmente muita gente não vai ler muito pra baixo. Acha que deixo uma explicação grande mesmo nessa parte, ou tento só deixar explícito sobre o que deve mudar? Tipo:

diciotech
...
├── _config.yml (arquivo de configuração do Jekyll)
├── _data (aqui devem ser adicionados os termos)
│   ├── en-us
│   │   ├── a.yml
│   │   ├── ...
│   │   └── z.yml
│   └── pt-br
│       ├── a.yml
│       ├── ...
│       └── z.yml
...

Quanto à diferença do _assets/ e assets/ visualmente fica ruim né? É que por convenção toda pasta que começa com _ é uma pasta que o Jekyll processa e que não vai pro site final. Eu usei o nome _assets/ exatamente porque o que ela gera vai pra pasta assets/ dentro do site final. Podemos mudar o nome da pasta também. O que acha?

[levxyca]

@george-gca

• Sobre o Docker, eu posso escrever essa parte sim, vou pegar pra fazer a instalação do zero hoje no Win e trago aqui depois para adicionarmos 🥰
• Sobre os textos nas árvores, acredito que podemos deixar da forma mais direta mesmo então, colocando só, por exemplo "aqui você modifica, adiciona e altera os termos" e por aí vai.
• Sobre os assets, acho que podemos mudar o nome da pasta sim, pra não ficar tão confuso.

[george-gca]

Acabei de testar, e dá também pra abrir o repositório nessa nova versão no GitHub Codespaces e tem um limite gratuito que dá pra usar. Só abrir e ele já abre no esquema, com a página carregada pra visualizar (graças ao devcontainer), sem precisar instalar ou configurar mais nada.

[levxyca]

@george-gca ah, como eu amo a tecnologia, o GitHub Codespaces facilita tudo HAHAHHA alguns cliques e:

[george-gca]

Mais fácil que isso pra configurar o ambiente de desenvolvimento não dá pra ficar haha.

[levxyca]

@george-gca SIM, tá muito bom, sério! Única coisa que tá me faltando agora é sobre o Docker que ainda não consegui tempo pra fazer o passo a passo certinho e usar o Devcontainer.

[levxyca]

@george-gca só pra te avisar que estou fazendo o processo do DevContainer hoje, até o fim do dia te mando meus feedbacks e se funcionou certinho pra gente conseguir andar 🚀

[levxyca]

@brunodmartins consegue dar um review aqui também? 🤩

[levxyca]

@george-gca eu tive um erro na hora da conexão com o DevContainer, apesar disso a aplicação rodou normalmente 🥳🙌🏻, vou deixar o erro aqui no print:

Agora, depois de seguir o passo a passo, segue a minha sugestão de modificação para essa parte da documentação:

### Usando Development Containers (recomendado)

O `diciotech` suporta [Development Containers](https://containers.dev/supporting). Para configurá-lo, siga as etapas abaixo:  

1. Certifique-se de ter o [Docker](https://www.docker.com/products/docker-desktop) instalado e em execução no seu sistema.  
2. Abra o repositório do projeto no **Visual Studio Code (VSCode)**.  
3. O VSCode solicitará que você instale a extensão necessária. Clique em "Instalar" e aguarde a configuração automática (este processo pode demorar na primeira vez).  
4. Após a instalação, clique na opção **"Reopen in Container"** quando solicitado. Novamente, aguarde enquanto o ambiente é configurado (pode levar mais tempo na primeira execução).  
5. Quando a conexão com o DevContainer for concluída, o Diciotech estará pronto para uso.  

#### Visualizando o site em execução  

1. Abra seu navegador e acesse: `http://localhost:4000`.  
2. Você verá uma cópia do [site oficial](https://diciotech.netlify.app/).  

Agora você pode personalizar o site conforme necessário. Após realizar as alterações, lembre-se de **commitar** suas mudanças finais.  

[george-gca]

Mudanças necessárias no Netlify:

1. Nas configurações de deploy

   • Branch to deploy para main
   • Base directory vazio
   • Build command para bundle exec jekyll build
   • Publish directory para _site

2. Adicione as seguintes variáveis de ambiente (edit: RUBY_VERSION é necessário porque se eu subir o arquivo .ruby_version que diz qual é a versão dá ruim com o devcontainer)

   • Chave	Valor
     JEKYLL_ENV	production
     RUBY_VERSION	3.3.4

3. Eu configurei o meu Node.js pra 22.x e o Build image pra Ubuntu Noble 24.04, e aqui tá tudo certo.

---

Mudanças legais pra fazer no repositório:

• adicionar tags na descrição do repositório: jekyll, i18n, multiple-languages, multilanguage, dictionary
• é útil adicionar tags em português?

[george-gca]

Issues que eu vou criar quando a PR for aceita:

• estilizar o botão de mudar de idioma
• explicação de como instalar o Docker
• adicionar um README em inglês? De repente usar badges assim pra direcionar pro idioma

[george-gca]

Dica: quando for aceitar a PR é uma boa dar squash pra não virem 35 mil commits diferentes pra main.

[levxyca]

Pessoal, voltei de recesso 🫣😂 E finalmente temos o mergeeeeeeeee 🚀 @george-gca acredito que no geral tá tudo redondinho 👀