Pular para o conteúdo
Pular para o conteúdo

Docs / Guias

Página traduzida automaticamente

Esta página foi traduzida automaticamente, então pode ter erros ou soar um pouco estranha. A versão em inglês é a fonte da verdade. Ler o original em inglês.

Adicionar um idioma

Adicione um novo locale de destino a um projeto do verbatra com uma linha de configuração e uma execução, sem mexer nos locales existentes.

Use este guia quando um projeto já traduz para alguns idiomas e você quer mais um. Bastam uma linha de configuração e uma execução. O verbatra trata o novo locale como se todas as chaves estivessem ausentes e as preenche; seus locales existentes não custam nada, porque o arquivo de lock ainda os registra como atualizados.

Você precisa de um projeto funcionando: uma configuração, um arquivo de locale de origem e uma chave de API do provedor. Se ainda não tem um, comece pelo Início rápido.

Adicionar o locale à sua configuração

Adicione o código a targetLocales em verbatra.config.ts:

verbatra.config.ts
import { defineConfig } from "@verbatra/cli";

export default defineConfig({
  sourceLocale: "en",
  targetLocales: ["de", "fr"], 
  format: "i18next-json",
  files: { pattern: "locales/{locale}.json" },
  provider: { id: "gemini", options: { model: "gemini-2.5-flash", maxOutputTokens: 4096 } },
});

Regras dos códigos de locale

Escreva o código na forma BCP 47, com hífen: pt-BR, não pt_BR. Se seus arquivos usam sublinhado, continue escrevendo pt-BR e defina files.localeStyle como posix; o verbatra mantém o nome de arquivo pt_BR.json. O carregamento da configuração rejeita um código inválido, o locale de origem e dois códigos que diferem só em maiúsculas e minúsculas. As regras completas estão em Códigos de locale; execute verbatra doctor para ver se um provedor aceita o novo idioma.

Pré-visualizar o trabalho

Veja o que uma execução faria antes de gastar qualquer coisa:

verbatra diff --locales fr

O novo locale ainda não tem arquivo, então toda chave de origem aparece como ausente. Omita --locales para confirmar que seus outros locales não listam nada. O diff não chama nenhum provedor e não grava nada. Para obter um valor de custo, execute verbatra translate --estimate; veja Estimar o custo antes de uma execução.

Traduzir

verbatra translate

A execução traduz toda chave de origem para o novo locale e grava o arquivo no seu files.pattern, aqui locales/fr.json. Só o novo locale dispara chamadas ao provedor: os outros locales não têm chaves ausentes nem alteradas em relação à linha de base no arquivo de lock, então nada é enviado para eles.

Se a execução não mantém nada para o novo locale, porque toda chave falhou em uma verificação, as requisições ao provedor falharam ou um orçamento de tokens reteve as chaves, nenhum arquivo é criado. As chaves continuam ausentes e a próxima execução tenta de novo.

Depois, verbatra check termina com 0 quando todos os locales, inclusive o novo, estão sincronizados.

Idiomas com mais categorias de plural

Alguns idiomas precisam de mais formas de plural do que a sua origem tem. O inglês tem one e other; o polonês precisa de quatro, o árabe de seis e o francês acrescenta many. Por padrão, o verbatra traduz as formas que sua origem tem e não inventa as outras: a execução termina com sucesso e relata um aviso PLURAL_CATEGORIES_INCOMPLETE que indica o que falta.

Gerar as formas que faltam

Se você usa JSON do i18next com um provedor de LLM, o verbatra pode escrever as formas que faltam:

verbatra.config.ts
export default defineConfig({
  // ...
  generatePlurals: true,
});

As formas geradas passam pelas mesmas verificações de integridade de qualquer tradução.

Formas do CLDR

As formas de que um idioma precisa vêm das regras de plural do CLDR embutidas no Node.js, para todos os idiomas, ordinais inclusos. Os formatos ICU (next-intl e ARB) guardam um plural inteiro em um único valor, então não precisam de geração: o verbatra pede ao provedor exatamente os ramos que o idioma de destino usa. Veja generatePlurals para o que recorre ao aviso e Plurais para saber como o verbatra decide de quais formas um idioma precisa.

Continuar mantendo só a origem

Daqui em diante, você edita apenas o locale de origem. Adicione uma string nele e execute translate de novo: o verbatra a preenche em todos os destinos, inclusive no que você acabou de adicionar.

Veja também

Editar no GitHub

Nesta página