10 de julho de 2026 - Dev Journal

Conduzimos a coleta de conversão de documentos oficiais JSONL de 1.180 para 1.230 usando o Markdown → JSONL Converter
Verificamos que o pipeline de tradução multilíngue está mais atrasado do que o esperado, podendo levar mais tempo para estabilizar
Testamos o pipeline de sincronização de documentos multilíngues em um repositório privado e, nesse processo, estabeleci os seguintes critérios

Critérios de estrutura de documentos:

Use o documento em coreano como documento base
Documentos multilíngues ficam no formato docs/<lang>/...
Caminhos que antes estavam diretamente sob docs/ são considerados documentos base em coreano e são movidos para docs/ko/...
Códigos de idioma devem ser padrões como ja, zh, pt-BR, e não códigos arbitrários como jp, ch
O README.md na raiz permanece como documento raiz
Traduções do README também são tratadas a partir da raiz
Evite que alterações no README.md sejam propagadas erroneamente como alterações em arquivos dentro de docs/
Pastas de idioma já existentes como docs/en, docs/ja não devem ficar aninhadas como docs/ko/en
Ao testar arquivos compactados, extraia apenas README e docs para refletir as mudanças

Critérios de links e caminhos:

Links internos do README e de docs são ajustados ao idioma de destino. Por exemplo, o link docs/ko/... no README coreano deve ser docs/en/... no README em inglês
Caminhos relativos entre documentos dentro de docs também são alterados conforme o idioma de destino
Garanta que caminhos de imagens, links de subdiretórios e caminhos relativos não quebrem durante a tradução/sincronização
Links de idioma no README devem estar em um formato que permita ao usuário perceber que está navegando ou alternando para o documento naquele idioma

Critérios de sincronização automática:

Quando um arquivo é adicionado em docs/ko, crie o arquivo correspondente nos demais idiomas
Quando um arquivo é removido de docs/ko, remova o arquivo correspondente nos demais idiomas
Quando um arquivo específico em docs/ko é modificado, apenas o arquivo correspondente nos outros idiomas deve ser marcado para recriação
Não traduza todo o conteúdo do zero a cada execução
Não traduza novamente idiomas/arquivos que já foram traduzidos com sucesso
Não exclua resultados bem‑sucedidos mesmo que ocorram falhas
Remova apenas os arquivos de destino que falharam e, na próxima execução, gere apenas esses arquivos novamente
Pule pastas de idioma que já estejam corretas ao comparar contagem de arquivos ou arquivos de versão simples
Arquivos de versão devem ser simples, como v1 ou um número, em vez de JSON/hashes complexos

Critérios de processamento de tradução:

Teste a tradução com a API real
Não use tratamento de sucesso “mock”
Defina o tamanho dos chunks com base nos limites de contexto/saída oficiais do modelo
Priorize cortar a saída de tradução para que não ultrapasse max_tokens em relação ao contexto de entrada
Verifique cada chunk imediatamente após traduzi‑lo
Áreas que falharem na verificação imediata são enviadas para uma fila
Re‑traduza/re‑verifique apenas as áreas falhas da fila, aumentando a profundidade e dividindo‑as em partes menores
Evite estruturas que só verificam tudo de uma vez ao final, depois de juntar todos os chunks

Critérios de verificação:

Confirme que nenhum texto em coreano permaneça na tradução
Verifique se os espaços em branco foram preservados
Verifique se a estrutura Markdown foi mantida
Verifique se fences de código, links, imagens e headings foram preservados
Não julgue apenas pelo comprimento ao lidar com idiomas que tendem a ficar mais curtos, como o chinês
Leia o resultado final e assegure‑se de que não há partes estranhas em relação ao original

Critérios de registro de falhas:

Diferencie falhas como HTTP 429, 504, RemoteDisconnected, finish_reason=length, respostas vazias, etc.
Registre cabeçalhos de resposta, corpo da resposta, tempo de execução, nome do modelo, tamanho da entrada e uso de tokens
Garanta que uma única falha não interrompa todo o pipeline nem faça com que os resultados desapareçam
Se as falhas se repetirem, analise a causa primeiro

Critérios de uso da API NVIDIA:

Teste o pipeline de tradução usando a API NVIDIA como referência
gpt-oss-120b aceita até 128 k de contexto de entrada, mas a política da NVIDIA limita a saída a cerca de 4 096 tokens
Mesmo que seja possível inserir grandes quantidades, a limitação de saída pode cortar a tradução; portanto, baseie o tamanho dos chunks no limite de saída de 4 096 tokens
Tente até 40 chamadas por minuto; se houver erros, aplique política de espera/re‑tentativa

Critérios de hard‑coding:

Use regras estruturais como docs/<lang>, marcadores, expressões regulares de links e parsing de fences de código
Não altere ou remova palavras arbitrariamente
Não remova example.com arbitrariamente
Não registre cada arquivo de documento individualmente por caminho
Não force substituições de expressões ou palavras específicas

Critérios operacionais:

Revise tanto GitHub Actions quanto runners auto‑hospedados em Mac
Quando executado em Mac, mantenha o fluxo de commit/push automático após a conclusão
Permita visualização de progresso como em GitHub Actions
Registre quais idiomas/arquivos/chunks estão em andamento
Deixe claros o nome da branch, URL da execução, causa da falha e progresso atual

Separadamente da tradução, descobri um documento interessante recentemente.

Verifiquei o Pollinations APIDOCS.md
Parece que é possível chamar a API com curl sem chave e ainda receber respostas de texto, além de gerar imagens
Acho que podemos experimentar livremente sem nos preocupar com cobrança de chave de API
Primeiro desenvolvi algo divertido com isso e pretendo usar mais antes de publicar
Reorganizei a estrutura de slots JSONL da divisão de versão do Qwen Validation Debugger
- docs_chunks serve como base de explicação de código, então mantemos slots separados para explicações de código Godot 3 e Godot 4
- Em vez de criar JSONL separados para api_mapping e label_prototypes de Godot 3 e Godot 4, incluímos ambos nos mesmos arquivos e geramos um JSONL de referência de conversão 3 -> 4
- O valor esperado de validação para o JSONL de conversão 3 -> 4 é Sim para código Godot 3 e Não para código Godot 4
- O valor esperado de validação para o JSONL de conversão irrelevante é Não tanto para Godot 3 quanto para Godot 4
Retrospectiva: docs/retrospectives/2026-07-10.md