@grstein/dsh-locale-ptbr

Readme

# dsh-locale-ptbr

Pacote de idioma **Português (Brasil)** para a GUI Web do [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

Instalado em um profile, ele acrescenta "Português (Brasil)" a Configurações → Geral e traduz a interface ao vivo. Nada no repositório do harness é alterado.

## Instalar

```sh
dsh plugin --profile web add github:grstein/dsh-locale-ptbr
dsh --profile web --dump-config   # confere a camada "# == @grstein/dsh-locale-ptbr"
dsh web                           # ou: dsh --profile <outro-perfil>
```

`dsh plugin` encaminha para o pnpm dentro do diretório do profile, então qualquer especificador aceito pelo pnpm serve (`github:`, um caminho local, um registry interno).

O idioma entra em Configurações → Geral → Idioma. Um navegador configurado em português seleciona **Português (Brasil)** sozinho no primeiro acesso; a escolha explícita fica gravada em `locale.preference` no `settings.yaml` do seu `$DSH_HOME` e vale por usuário.

![A GUI do DeepSeek Harness em português](docs/ptbr-gui.png)

Remover: `dsh plugin --profile web remove @grstein/dsh-locale-ptbr`.

> `dsh web` é o atalho do profile `web` e não aceita `--profile`; um profile próprio que inclua o bundle `@deepseek-ai/dsh-web-app` sobe com `dsh --profile <nome>`.

## O que é traduzido

A cópia de produto da GUI Web: 33 namespaces e 1.029 chaves — conversa, trajetória, cards de ferramenta, workspace, configurações, aprovações, jobs, subagentes, comandos.

Não é traduzido, por design do harness: o texto gerado pelo modelo, dados de usuário/provedor/protocolo, a saída do CLI e do terminal, a documentação, e a cópia de boot renderizada antes do serviço de locale ativar. Texto capturado no momento do registro (por exemplo, descrições de comando no registry) mantém o idioma do registro até um novo registro.

Chaves ainda não traduzidas caem automaticamente em inglês pela cadeia de fallback `pt-BR → en`, então o pacote nunca mostra chave crua.

## Estrutura

| Caminho | Papel |
|---|---|
| `dicts/<ns>.json` | Fonte de tradução, um arquivo por namespace (`{ namespace, entries }`) |
| `client.js` | Metade browser **gerada**: `addLanguage` + um `register` por namespace |
| `index.js` | Metade Node (vazia); existe porque o Loader do host varre o manifesto `dsh.client` |
| `cordis.patch.yml` | Camada do bundle que insere a row `locale-ptbr` |
| `keys.lock.json` | Conjunto de chaves e placeholders do harness alvo |
| `GLOSSARY.md` | Terminologia pt-BR obrigatória |
| `tools/extract-keys.mjs` | Varredura AST de um checkout do harness → `keys.lock.json` + `en.snapshot.json` |
| `tools/sync.mjs` | Compara o pacote com um harness mais novo e gera o delta de tradução |
| `tools/build-client.mjs` | `dicts/*.json` → `client.js` |
| `tools/check-parity.mjs` | Gate: chaves, placeholders e `client.js` atualizado |
| `tools/check-runtime.mjs` | Gate: o artefato registra 1 idioma + 33 dicionários e descarta limpo |
| `.github/workflows/` | `ci` (gates a cada push) e `drift` (vigia o harness toda segunda) |

Não versionados: `en.snapshot.json` (texto em inglês de cada chave, fonte de tradução) e `.work/` (arquivos de delta). Ambos são regeneráveis a partir de um checkout do harness.

## Traduzir ou corrigir

```sh
npm install       # uma vez: o único dev dependency é o typescript, usado pela extração
# edite dicts/<ns>.json
npm run build     # regenera client.js
npm test          # paridade de chaves, placeholders, artefato e registro em runtime
```

Envie `client.js` regenerado junto com a alteração do dicionário: o gate falha se ele estiver desatualizado.

## Acompanhar uma versão nova do harness

```sh
git -C /caminho/para/deepseek-harness pull      # ou clone raso da tag desejada
node tools/sync.mjs /caminho/para/deepseek-harness           # relatório; sai 1 se houver diferença
node tools/sync.mjs /caminho/para/deepseek-harness --apply   # adota o novo conjunto de chaves
```

O relatório separa três tipos de diferença, porque cada um dá trabalho diferente:

| Tipo | O que aconteceu | Efeito se nada for feito |
|---|---|---|
| `added` | O harness registra uma chave que o pacote ainda não traduz | A chave aparece em inglês (fallback), nunca crua |
| `removed` | O harness deixou de registrar a chave | `--apply` remove a entrada de `dicts/`; o gate rejeita chave desconhecida |
| `reworded` | O texto em inglês mudou | A tradução antiga continua exibida e pode estar errada |

`--apply` reescreve `keys.lock.json` e `en.snapshot.json`, remove as chaves obsoletas de `dicts/`, regenera `client.js` e grava `.work/<ns>.delta.json` com **apenas** o que precisa de tradutor — o texto em inglês das chaves novas e, para as reformuladas, o inglês novo ao lado da tradução atual. Chaves novas não recebem texto automático de propósito: chave ausente cai em inglês, enquanto um inglês copiado para dentro do dicionário pareceria traduzido e nunca mais seria revisto.

Traduza os arquivos de delta para dentro de `dicts/`, e então:

```sh
npm run build && npm test
```

A extração exige um **checkout de código-fonte** do harness (ela lê `packages/*/*/src` pela AST); o pacote publicado no npm não traz as fontes. Um `git clone --depth 1` da tag correspondente basta.

### Vigilância automática

`.github/workflows/drift.yml` roda toda segunda-feira: faz checkout do `deepseek-ai/deepseek-harness`, executa `tools/sync.mjs` e, havendo diferença, abre (ou comenta em) uma issue com o relatório. Assim a defasagem aparece sozinha, sem depender de alguém lembrar de conferir a cada release.

### Versionamento do pacote

Suba a versão em `package.json` a cada conjunto de traduções e anote no CHANGELOG do release qual `harnessVersion` ele mira — `keys.lock.json` guarda esse alvo. Como o fallback para inglês nunca quebra a UI, um pacote defasado degrada aos poucos em vez de falhar.

Alvo atual: `@deepseek-ai/dsh-client-locale` 0.1.2-alpha.1. O histórico de versões está no [CHANGELOG](CHANGELOG.md).

## Contribuir com uma correção de tradução

Divergências de terminologia são resolvidas pelo [GLOSSARY.md](GLOSSARY.md), que é a autoridade do pacote: mudar uma palavra que ele fixa significa mudar o glossário e todos os arquivos afetados, não só um deles.

1. Edite `dicts/<ns>.json` (apenas valores; chaves e placeholders são intocáveis).
2. `npm run build && npm test`.
3. Abra um PR com o `client.js` regenerado junto.

## Relação com o projeto oficial

Este pacote é ecossistema, não um fork. O [CONTRIBUTING](https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.md) do DeepSeek Harness declara que o projeto não aceita pull requests externos no momento e indica a criação de plugins próprios, marcados com o tópico `dsh-plugin`, como a forma de contribuir. É exatamente o que este repositório é.

Um pt-BR embutido no repositório oficial também seria caro tecnicamente: `LOCALE_IDS` é um par tipado `['zh', 'en']` e a forma `register(ns, { zh, en })` exige os dois dicionários completos, então um terceiro idioma interno viraria erro de compilação em toda a árvore de plugins. `addLanguage` + `register(ns, locale, dict)` existem no runtime justamente para pacotes externos, com cadeia de fallback até `en` para tolerar tradução incompleta.