# Traduções

Blockstudio inclui suas traduções na pasta `languages`. WordPress as utiliza sempre que o idioma do site ou o idioma do perfil de um usuário corresponde a um deles. Isso funciona da mesma forma quando Blockstudio é executado como plugin, plugin obrigatório ou pacote Composer.

## Idiomas disponíveis

Blockstudio inclui traduções para as localidades WordPress registradas em seu `languages/locales.json` integrado, incluindo variantes regionais e formais/informais. O inglês (`en_US`) é o idioma de origem e não precisa de um arquivo de tradução. A lista combina localidades compatíveis com WordPress do GlotPress e variantes disponíveis no WordPress de tradução do núcleo do API.

As traduções existentes para alemão (`de_DE`) e alemão formal (`de_DE_formal`) foram preservadas. As traduções adicionais foram geradas por IA usando GPT-6 Luna e identificadas como geradas por máquina em seus cabeçalhos `.po`. Elas passam por verificações automatizadas de integridade e formato, mas nem todas foram revisadas por falantes nativos. Correções são bem-vindas.

As traduções abrangem os controles de campos no editor de blocos, a página de administração, a tela, a sobreposição das ferramentas de desenvolvimento e as mensagens dos endpoints REST. Rótulos e textos de ajuda nos seus próprios arquivos `block.json` pertencem ao seu tema ou plugin e usam seu domínio de texto.

Selecione o idioma em **Configurações > Geral > Idioma do site** ou escolha um idioma pessoal no seu perfil WordPress. Blockstudio usa essa localidade automaticamente. Ele não adiciona idiomas ao seletor de idiomas do WordPress: uma localidade também precisa estar disponível na sua instalação do WordPress. Não é necessária nenhuma solicitação à IA, assinatura de tradução ou configuração adicional de tempo de execução no seu site.

## Substituir uma tradução

Os arquivos de tradução em `wp-content/languages/plugins` têm prioridade sobre os integrados, tanto para as strings PHP (`blockstudio-de_DE.mo` ou `blockstudio-de_DE.l10n.php`) quanto para os scripts (um arquivo por identificador de script, por exemplo `blockstudio-de_DE-blockstudio-blocks.json`).

## Contribuir com uma tradução

Cada idioma corresponde a um arquivo `.po` que você pode editar com qualquer editor de texto ou com uma ferramenta de tradução, como o Poedit. Correções e novos idiomas são bem-vindos como solicitações de pull.

1. Para adicionar um idioma, copie `languages/blockstudio.pot` para `languages/blockstudio-<locale>.po`, por exemplo `blockstudio-fr_FR.po`, e defina os cabeçalhos `Language` e `Plural-Forms`. Para aprimorar um idioma, edite o arquivo `.po` existente.
2. Traduza as strings. Mantenha na tradução os marcadores de posição, como `%1$s`.
3. Execute `npm run i18n`. Ele grava os arquivos `.mo`, `.l10n.php` e `.json` que WordPress carrega.
4. Faça o commit do arquivo `.po` junto com os arquivos gerados e abra uma solicitação de pull.

Se você não puder executar `npm`, uma solicitação de pull somente com o arquivo `.po` também serve. Os arquivos gerados podem ser adicionados antes da integração.

## Gerar traduções ausentes

Os mantenedores podem gerar entradas ausentes com um Codex CLI autenticado. Este é um comando de desenvolvimento opcional, não algo que WordPress executa:

```bash
npm run i18n:translate -- --dry-run
npm run i18n:translate
```

O modelo padrão é `gpt-6-luna`. Para trabalhar em uma localidade, use `npm run i18n:translate -- --locale fr_FR`. O comando extrai as strings de origem mais recentes, preenche as traduções ausentes e, em seguida, compila os arquivos `.mo`, `.l10n.php` e `.json` para cada script. Somente strings da interface pública, seu contexto e suas formas existentes são enviados ao Codex, sem conteúdo do site ou dados de usuários.

Traduções existentes e não vazias nunca são substituídas. Os lotes concluídos são salvos, então, se houver uma interrupção, a execução novamente retoma o trabalho pendente. Marcadores de posição, como `%1$s`, marcação HTML, identificadores técnicos e as formas plurais obrigatórias são validados antes de salvar. Entradas aproximadas e plurais de origem alterados ficam para revisão de um tradutor. Não há substituição por outro modelo se o modelo solicitado estiver indisponível.

`npm run i18n:locales` atualiza explicitamente a lista de localidades e as regras de plural a partir de WordPress/GlotPress. `npm run i18n:coverage` verifica se todas as localidades da lista incluída no repositório estão completas. Nem as verificações de cobertura nem a integração contínua normal recorrem à IA ou buscam dados de localidades. Consulte o README do repositório para ver opções de processamento em lotes, concorrência e recuperação.

## Strings traduzíveis no código

- PHP: use as funções WordPress com o domínio de texto `blockstudio`, por exemplo `__( 'Invalid block.', 'blockstudio' )`.
- JavaScript: importe `__` de `@/utils/__` e passe uma string literal, por exemplo `__( 'Add row' )`. Uma string montada durante a execução não pode ser traduzida, então use uma string literal para cada variante.
- Um novo pacote de script com strings traduzíveis precisa de uma entrada em `scripts/i18n.ts` e de uma chamada a `wp_set_script_translations()` com o mesmo identificador e `Translations::script_path()`.

Depois de alterar as strings, execute `npm run i18n`. Ele atualiza `languages/blockstudio.pot` e todos os arquivos `.po`. As novas strings permanecem em inglês até que um tradutor ou `npm run i18n:translate` as traduza. A CI executa `npm run i18n:check` e `npm run i18n:coverage`, que rejeitam arquivos compilados desatualizados, problemas de extração ou cobertura incompleta de localidades. A geração continua sendo uma ação explícita do responsável pela manutenção.