Código do site do GengoJouzu

Dicionário japonês → português brasileiro, construído sobre o Jitendex / JMdict. Backend em Django + Postgres, frontend em React/Vite.

Como contribuir

Traduções e correções vão pelo próprio site, não por pull request. Faça login em www.ggjz.org, abra o termo, edite e envie — isso cria um patch, que entra na fila de revisão. É assim que o dicionário inteiro foi traduzido, e é a forma de contribuição que realmente ajuda.

Código é outra história. Este repositório é mantido por uma pessoa só, e o git.ggjz.org não aceita cadastro próprio: as contas vêm por OAuth do ggjz.org e o acesso ao Forgejo é restrito ao papel Admin, que também dá acesso ao painel de deploy. Ou seja, não há como abrir um PR de fora — e não vale a pena abrir essa porta pelo que ela traria junto. Se você quer mexer no código, mande um email para nostress767@ggjz.org e a gente combina.

Rodando localmente

Não há nada para configurar. O .env já vem no repositório com valores de desenvolvimento.

docker compose watch

Isso sobe o Django em localhost:8000 e o Postgres em localhost:5432, com o código sincronizado a quente.

A primeira execução demora. Ela baixa a release PT-BR publicada (~38 MB) e carrega os ~428 mil termos no banco — uns 10 minutos numa máquina de mesa. Acompanhe:

docker compose logs -f django    # só o Django
docker compose logs -f           # tudo, incluindo o Postgres

Se você só quer um ambiente de pé rápido e não se importa com o que tem dentro, GGJZ_SEED=lite carrega um punhado de termos em vez do dicionário inteiro:

GGJZ_SEED=lite docker compose watch

De onde vêm os dados

De https://www.ggjz.org/data/yomitan-ptbr.zip — a mesma release que o site serve no modo offline e que o Yomitan baixa no "Check for Updates". É um endereço fixo que sempre aponta para a versão mais recente, então um banco local nasce com o conteúdo que está no ar, já em português.

(Antes o seed vinha do Jitendex em inglês, de quando quase nada estava traduzido e a fila de patches era o próprio dicionário. O efeito colateral disso hoje é que um banco novo não tem nenhum patch pendente — se você quer exercitar a tela de revisão, envie um patch pelo site.)

Para fixar uma release específica em vez da mais recente:

GGJZ_SEED_URL=https://www.ggjz.org/data/2026-08-20/jitendex-yomitan-ptbr-2026-08-20.zip \
  docker compose watch

A revisão que você recebeu fica gravada em /state/.setup_complete e aparece nos logs no boot, já que a URL padrão é um ponteiro móvel.

Recarregando os dados

O jeito curto, que apaga tudo e começa do zero:

docker compose down -v && docker compose watch

Se quiser preservar o banco e refazer só o seed, apague a flag no volume:

docker volume ls | grep django_state          # confirme o nome
docker volume inspect website_django_state    # veja o "Mountpoint"
sudo rm /caminho/do/mountpoint/.setup_complete
docker compose watch

Não mexa em POSTGRES_INITDB_ARGS no .env. A collation tem que ser C.UTF-8 igual à de produção — ORDER BY reading é desempate da busca, e qualquer outra locale devolve os resultados em outra ordem sem avisar. O initdb só lê essa variável quando o volume é criado, então mudá-la depois exige docker compose down -v.

Frontend

O SPA não sobe junto com o compose. Rode à parte:

cd frontend
npm install
npm run dev      # Vite em localhost:5173

O servidor de desenvolvimento faz proxy de /api para o Django em :8000 e de /data para https://www.ggjz.org, o que deixa os dois modos do site testáveis localmente:

• anônimo — o dicionário roda inteiro no navegador, a partir da release baixada para o OPFS. É o que o público vê.
• logado — o editor, a review e a gestão de usuários batem na API em :8000, que é onde os patches existem; a busca continua local, e a fonte live do menu só troca o texto dos verbetes da página pelo que está no banco. Você só loga para editar.

Outros comandos:

npm run build    # tsc -b && vite build — é o que o CI roda
npm run lint

Comandos de manutenção

Rodam dentro do container: docker compose exec django python manage.py <cmd>.

comando	o que faz
load_terms <dir>	carrega um diretório Jitendex no banco (--batch-size, padrão 2500)
load_terms_lite <dir>	idem, mas só alguns termos, para subir rápido
update_jitendex	atualização mensal a partir do Jitendex novo — localmente ele precisa de uma base em inglês em /state/jitendex-current
translate_scaffolding	traduz rótulos estruturais que escaparam
fix_xref_leaves	regenera as glosas de referência cruzada
build_yomitan_ptbr	monta o zip da release e carimba a data nas páginas /pt/
build_browse_index	refaz o índice por leitura das páginas /pt/indice/; o build_yomitan_ptbr já refaz ao carimbar
export_moderator_references	exporta os patches aceitos por um revisor, para o conjunto de calibração
setup_groups, setup_oauth_apps	idempotentes; rode ao mudar papéis ou clientes OAuth

Testes

Três suítes, todas locais.

Backend (Django, dentro do container — cria um banco de teste próprio):

docker compose exec django python manage.py test

Frontend, dicionário offline (Playwright, Chrome e Firefox, sem rede):

cd frontend
npm test

Frontend, páginas logadas (Playwright, Chrome, contra a API de verdade). Precisa da stack do docker compose watch no ar; cria no banco local uma conta de cada papel (it_*@test.local) e exercita login, redefinição de senha (lida do log do container), o redirecionamento OAuth, o editor, a página de review e a gestão de usuários:

cd frontend
npm run test:integration

Detalhes das duas suítes do frontend em frontend/tests/README.md.